[AI-8410] loadSidebarV2 host API bridge, context, and integration docs

[matipojo]

Summary

• Add host API bridge for loadSidebarV2: postMessage handlers for GET_EXTERNAL_HEADERS, website/analytics context, and host localStorage.
• Wire bridge into sidebar boot and export ExternalHeadersCallback, LAYOUT_SIDEBAR, and LAYOUT_FLOATING_CHAT from the package.
• Expand browser demos (sidebar, floating chat, full-config example with aiContext, custom CSS, and callbacks) and add src/load-sidebar-v2/README.md plus root README link.
• Bump version to 1.4.9.

Builds on merged loadSidebarV2 core (#43) and layouts/chat toggle (#44).

Test plan

• npm test (171 tests)
• npm run build then open demo/load-sidebar-v2-sidebar/, demo/load-sidebar-v2-floating-chat/, and demo/load-sidebar-v2-full-config/ via local static server
• Confirm host toggle opens sidebar; full-config demo logs onClose and sends demo headers via getExternalHeaders
• Verify embedded Angie receives aiContext / widget config on HOST_READY

✨ PR Description

1. Problem & Context

Implements host-side postMessage API bridge for loadSidebarV2 to enable secure two-way communication between embedded Angie iframe and host page. Allows iframe to request external auth headers, website/analytics context, and localStorage access without exposing host internals.

2. What Changed (Where)

File	Change
host-api-bridge.ts	New 148-line module handling iframe postMessage, origin validation, external headers callback, context builders
config.ts	Added ExternalHeadersCallback type, analytics field to HostConfig, getExternalHeaders to CallbacksConfig
boot-sidebar.ts	Calls initHostApiBridge() before container setup with iframe origin + callbacks
resolve-config.ts	Threads getExternalHeaders callback through config resolution
index.ts	Exports ExternalHeadersCallback type
Demo + docs	Full-config example, README.md integration guide, test coverage (237-line test suite)

3. How It Works

On boot, initHostApiBridge() registers a global message listener (origin-checked against iframe). When iframe posts GET_EXTERNAL_HEADERS, GET_WEBSITE_CONTEXT, GET_ANALYTICS_CONTEXT, or localStorage ops on a MessagePort, host invokes the callback (or fetches from config) and responds via port.postMessage(). Undefined headers filtered; errors wrapped in error response. Bridge state is singleton per page (prevents double-registration).

4. Risks

None material. Origin validation prevents CSRF. Callback is optional (defaults to empty). localStorage errors gracefully degrade (catch blocks). Test coverage is comprehensive (237 lines). Minor: resetHostApiBridgeForTests() is export-only used in tests—fine for test cleanup.

Generated by LinearB AI and added by gitStream.
_{AI-generated content may contain inaccuracies. Please verify before using.
💡 Tip: You can customize your AI Description using Guidelines Learn how}

[wiz-9a149474ff]

Wiz Scan Summary

Scanner	Findings
Vulnerabilities	-
Sensitive Data	-
Secrets	-
IaC Misconfigurations	-
SAST Findings	1
Software Management Findings	-
Total	1

View scan details in Wiz

To detect these findings earlier in the dev lifecycle, try using Wiz Code VS Code Extension.