[josemontespg]

Summary

This change adds the two components of the iframe catalog to @a2ui/catalog-iframe as universal components: WebAppFrameUrl, which loads an external web application from an http or https URL, and WebAppFrameSrcdoc, which renders inline HTML. Both render the sandbox proxy in their light DOM, hand it the content once it reports ready, and connect the frame to the surface through WebAppFrameBridge, so the application gets the bound data paths, the allowlists and a MessagePort in the handshake, and its actions, data changes, function calls and resize requests go through the validated host bridge. iframeCatalog exposes them to a MessageProcessor.

The components target A2UI v1.0: they import from @a2ui/web_core/v1_0, the bridge uses the v1.0 ActionPayload and AgentToRendererMessage types, and iframeCatalog is a Catalog for protocol 1.0.

The pieces the components are made of are shared: SandboxedFrameElement (proxy frame rendering, height, proxy handshake, bridge lifecycle across context and content changes, cleanup on removal) and ComponentContextFrameHost (the FrameHost over a universal component's ComponentContext) live in typescript/catalogs/shared/sandbox/ and are exported, so a catalog that adds another sandboxed frame component can build on them.

Changes

• WebAppFrameUrl (a2ui-web-app-frame-url) and WebAppFrameSrcdoc (a2ui-web-app-frame-srcdoc) with zod APIs that match the catalog schema, iframeCatalog, and the exports in src/index.ts.
• WebAppFrameUrl only loads http and https URLs and appends the host origin as the origin query parameter; other schemes load nothing and are reported once. WebAppFrameSrcdoc decodes the url_encoded: form, keeps author CSP meta tags (they can only narrow the policy), injects the strict policy and the link interceptor, and loads nothing for empty content.
• SandboxedFrameElement: one <iframe> in the light DOM pointing at the sandbox proxy, no sandbox attribute on the proxy frame (the inner frame the proxy creates runs with allow-scripts allow-forms allow-modals and never allow-same-origin), title from accessibility.label, height applied to the element with app-driven resizing through FrameSizing, proxy-ready listening and resource sending, bridge reconnection when the context or the content changes, teardown on disconnect and a new session on re-attach. Styling through --a2ui-sandboxed-frame-* custom properties.
• ComponentContextFrameHost: data paths through the component's data context, functions through the surface catalog invoker with signal results unwrapped, actions dispatched as events of the component.
• @a2ui/web_core and lit become peer dependencies (and dev dependencies); the wireit build, test:types and lint scripts depend on typescript/web_core:build.
• Tests: schema parity of each component with catalog.json; component tests that process small inline v1.0 message fixtures with a real MessageProcessor, render the elements and play the proxy and the application over an inert same-origin page and the real transferred port; tests of the base class and the host adapter; real-frame scenarios under tests/ that load the real proxy from dist/sandbox/ (served by Karma at /a2ui-sandbox/) and a fixture application in both modes, covering the double-iframe bootstrap and handshake, action, two-way data, function call and resize round trips, and the negative cases (undeclared actions, invalid payloads and unbound data dropped, ambient protocol messages ignored, foreign-origin handshakes ignored, top navigation blocked, no allow-same-origin on the inner frame).
• README: installation with the peer dependencies, registration with a web renderer next to the basic catalog (components set catalogId to use the frames in a basic surface), the component properties with an example message, styling, and how to write another sandboxed frame component. The CHANGELOG entry extends the package bullet from [iFrame] Add the @a2ui/catalog-iframe package and frame bridge #2797.

Verification

• yarn workspaces foreach -R --from @a2ui/catalog-iframe --topological-dev run build: passes from a clean tree.
• yarn workspace @a2ui/catalog-iframe test: 258 of 258 Karma specs pass in headless Chrome, including the real-frame scenarios.
• yarn workspace @a2ui/catalog-iframe lint, yarn lint:deps, ./scripts/fix_format.sh --check and python3 scripts/fix_licenses.py --check: pass.
• yarn pack --dry-run in the package: the components ship under dist/; no tests, test support or fixtures are included.

Pre-launch Checklist

• I read the Contributors Guide.
• My code changes have tests.

Related to #3157

[gemini-code-assist]

Code Review

This pull request introduces the iframeCatalog along with the WebAppFrameUrl and WebAppFrameSrcdoc universal components, which render sandboxed iframe content and connect it to the host via WebAppFrameBridge. It also adds base classes and host adapters (SandboxedFrameElement and ComponentContextFrameHost) to support custom sandboxed frame components, alongside comprehensive unit and integration tests. The feedback highlights a potential security vulnerability in injectContentSecurityPolicy where regular expressions are used to parse and inject elements into HTML, and suggests using DOMParser for a more robust and secure implementation.

[josemontespg]

Agent: Do we really need to export these symbols as part of the public API of this package? Are consumers expected to use frameHeightFromProp,
frameTitleFromProps,
SandboxedFrameElement, ?, or is this an internal implementation detail of the package?