[Epic] Qualify unchanged Code OSS webviews and nested document contexts

[wieslawsoltes]

Current webview/nested-document checkpoint — 19 September 2026

Exact inputs are WebScene 2cd3913fceff7a0c9660aca05ab232fa237bda1d, AppScene 0ef434a4040d0bf3bff840045987566904f1a34c, and unchanged Code OSS 645f29cc3176500b4b5762ba887cf2a7f0ffdf2c. Nested lifecycle/security and interaction providers are merged through cancelable beforeunload, ordered unload, same/cross-document history/reload, restricted cross-origin WindowProxy, focus/input, find/Selection, clipboard, links/downloads, drag and semantics.

The latest #268 audit found no additional bounded reusable provider gap. #267/#268 remain open for current-package cumulative behavior across Markdown Preview, notebooks, custom editors, extension panels/views, release notes, Getting Started, Chat/MCP, Mermaid and Simple Browser, including the reported Markdown preview failure. A newly reproduced product-neutral primitive gets a focused child issue/PR.

Only git diff --check runs in this wave. WPT/browser/product/security/lifecycle and package acceptance remain open.

Parent epic: #227

Outcome

Run the unchanged VS Code OSS 1.137 webview stack in WebScene with browser-shaped isolation, resource delivery, interaction, lifecycle, visual, performance, and accessibility behavior. Markdown Preview is the first deterministic reproduction, not the boundary of the work.

Pinned audit baseline: AppScene 9f434e0, WebScene b81f594c, VS Code OSS 645f29c.

Unchanged consumers in scope

• extension API webview panels, webview views, custom editors, and editor insets;
• Markdown Preview and Markdown editor, Mermaid editor, and Simple Browser;
• notebook back-layer/output webviews and notebook diff/output editors;
• release notes, Getting Started, extension details, image carousel, and contributed panels;
• chat tool output, agent-plugin editor, MCP app content, and Copilot suggestion panels.

They all converge on webviewElement.ts and browser/pre/index.html; success from a hand-authored iframe does not qualify this epic.

Proven dependency chain

1. Expose HTMLIFrameElement.sandbox for Code OSS webviews and Markdown Preview #253: HTMLIFrameElement.sandbox.add(...) currently throws synchronously.
2. Complete ServiceWorker control and client lifecycle for Code OSS webviews #265 service-worker control plane: Markdown does not set disableServiceWorker; index.html rejects when navigator.serviceWorker is absent.
3. Stream and cache admitted Code OSS webview resources #266 service-worker resource plane: service-worker.js needs FetchEvent, Clients, CacheStorage, readable/writable/transform streams, ranges, cache validation, and resource-message transfer.
4. Enforce secure nested-document lifecycle for Code OSS webviews #267 secure nested-document lifecycle: the outer frame loads the prelude, then creates fake.html, accesses contentWindow/contentDocument, and uses open/write/close to install extension HTML under CSP and sandbox rules.
5. Complete nested-webview interaction, find, focus, and accessibility handoff #268 messaging and interaction: Implement Worker, transferable MessagePort, and iframe contexts for Code OSS #81 owns transferable MessagePort/worker completion; the webview prelude also needs focus/input/clipboard/find/selection/context-menu/drag/link/download/reload behavior.
6. Release-wide acceptance is owned by Establish Chromium/AppScene visual and geometry regression gates for unchanged Code OSS #259 (visual/geometry), Qualify all unchanged Code OSS workbench commands, panels, and feature lifecycles #260 (workbench consumers), Qualify Code OSS Chat and auxiliary-bar interaction, streaming, and lifecycle #261 (Chat), Qualify Code OSS accessibility semantics, keyboard navigation, and native exposure #262 (accessibility), Publish a Code OSS Web API capability ledger and expand WPT coverage #263 (Web API/WPT ledger), and AppScene#130 (installed release). This epic supplies their nested-document lane rather than duplicating those tickets.

Related cross-repository owners are AppScene#27 (input/focus), #30 (native accessibility), #31 (packaged URLs/origins), #32 (downloads/clipboard/drag), #34 (network/streams), #36 (workers/messaging), and #41 (embedded document contexts). WebScene #81 and #102 remain shared prerequisites. CSS/visual issues remain under #235 and open PR #245 is outside this stack.

Native subissues

• Expose HTMLIFrameElement.sandbox for Code OSS webviews and Markdown Preview #253 — iframe sandbox IDL/token/security semantics.
• Complete ServiceWorker control and client lifecycle for Code OSS webviews #265 — ServiceWorker registration, control, Clients, and lifecycle.
• Stream and cache admitted Code OSS webview resources #266 — FetchEvent, Web Streams, CacheStorage, and admitted resource broker.
• Enforce secure nested-document lifecycle for Code OSS webviews #267 — nested iframe navigation, realms, CSP/origin/permissions, replacement, teardown.
• Complete nested-webview interaction, find, focus, and accessibility handoff #268 — nested-frame find, selection, focus/input, clipboard, links/downloads, reload, and accessibility handoff.

Global gates

• Use selected upstream WPTs plus a checked-in Chromium oracle for each standards surface; document exclusions instead of silently skipping.
• Exercise top-level and nested realms on macOS arm64, Linux x64, and Windows x64 native runners and installed-package consumers.
• Enforce CSP, opaque/same-origin sandbox transitions, local-resource roots, MIME/range/cache headers, navigation admission, and stale-generation rejection. No permissive bypass qualifies.
• At steady state, 100 create/update/find/reload/dispose cycles leave zero live iframe realms, workers, clients, ports, observers, streams, cached response leases, and pending host requests from the disposed generation. After warm-up, retained RSS growth must be <= 8 MiB for the deterministic fixture and no queue may exceed its documented cap.
• For the exact vscode-demo/README.md, cold command-to-first-complete-scene p95 must be <= 2 s and warm edit-to-updated-scene p95 <= 250 ms on the recorded macOS reference machine; each focused issue has tighter component budgets. Publish Chromium and native timings rather than hiding a regression inside the end-to-end allowance.
• Chromium/native comparisons cover geometry, scroll, theme, local/external resources, images, focus order, links, find highlights, and the semantic accessibility tree. AppScene#30 owns native platform exposure.

Proposed PR stacks and schedule

Stack A — synchronous frame creation

1. Expose HTMLIFrameElement.sandbox for Code OSS webviews and Markdown Preview #253 IDL/DOMTokenList shape;
2. Expose HTMLIFrameElement.sandbox for Code OSS webviews and Markdown Preview #253 sandbox enforcement/navigation/teardown;
3. Expose HTMLIFrameElement.sandbox for Code OSS webviews and Markdown Preview #253 WPT, browser oracle, native package smoke.

Stack B — service worker and resources (#265 then #266)

1. registration/container/worker lifecycle and Clients;
2. FetchEvent dispatch and controlled-client routing;
3. streams and CacheStorage;
4. VS Code resource broker, range/cache/security/performance acceptance.

Stack C — nested document and interaction (#267 then #268)

1. src/srcdoc/fake-document navigation and realm isolation;
2. CSP/origin/Permissions Policy enforcement;
3. document replacement, event/focus/find/link/reload behavior;
4. lifecycle, accessibility, and bounded stress gates.

Stack D — product qualification (#259–#263 and AppScene#130)

1. Markdown Preview with the exact current demo README plus deterministic local/external image fixtures;
2. notebooks/custom editors/webview views and panels;
3. release notes/Getting Started/extension/image surfaces;
4. chat/MCP/Mermaid/Simple Browser and final three-RID package matrix.

Stack A is first because it is the current synchronous failure. Stack B follows because the unchanged prelude cannot initialize without it. Stack C may develop behind stable A/B interfaces, but security enforcement must land before product acceptance. Stack D closes only from a cumulative exact-head package. Each stack should use focused PRs, validate its cumulative top, and merge atomically. No implementation PR belongs in this investigation phase.

Acceptance

• Every child issue is closed with WPT/browser/native/product evidence and numeric performance/teardown results.
• All listed unchanged webview consumers either pass or have a specific, fail-closed exclusion with an owning issue.
• The exact pinned package completes Markdown preview and representative non-Markdown consumers without VS Code source changes, Electron, CEF, or an embedded browser.
• Security, accessibility, lifecycle, and resource gates run in release CI rather than remaining manual claims.

Active status — 17 September 2026

#253 is complete. #276/#278 merged at 053a5627/aa786c0e; an exact stamped Code 645f29c run reaches the version-6 controller and logs webview ready after 2.665 s. #281 remains open and blocked by active MessagePort lifetime #288 in PR #245. Hold #266 until #281 rebases, passes the cumulative ServiceWorker/WebSocket gates, and merges. Full Markdown remains blank because #266 still lacks Streams, FetchEvent.respondWith, and CacheStorage resource delivery.

Current webview checkpoint — 19 September 2026

Focused children under #268 now cover nested pointer, keyboard/focus, context menus, links, downloads, inbound drag routing, and bounded outbound drag requests through WebScene 2b64b08. Semantic snapshot/action/live/delta providers are also merged for nested accessibility.

AppScene has all three inbound drag adapters plus macOS and Windows outbound consumers through f3fd2d2e. Linux Wayland/X11 outbound consumption is active under AppScene #187. macOS semantic snapshot/delta peers and the reusable Windows UIA adapter are merged; Linux AT-SPI and action/live delivery are active under AppScene #184/#185.

Remaining work is real platform host wiring and cumulative unchanged Markdown/notebook/custom-editor/extension/Chat/Simple Browser selection/find/clipboard/accessibility/navigation/reload/teardown/package acceptance. Only source diff checks ran in the newest wave.

[wieslawsoltes]

Stack B update: controlled Service Worker resource routing is now cumulative on main at d7720a63.

• Intercept connected resources through Service Workers #310 landed dynamic connected script/style/image interception.
• Intercept parser and frame resources through service workers #319 was promoted by Promote parser and frame service worker interception #321 and closed Intercept parser and nested-frame resources through Service Workers #312, adding initial parser style/script plus nested-frame hydration interception and teardown/performance gates.
• Exact promotion validation passed native focused CTest, native WebPlatformSubset 4/4, Chrome 153 4/4, and 10/10 repeated native teardown exits.

The dependency chain now continues with #266. #267 and #268 remain downstream of its resource-plane completion.

[wieslawsoltes]

Navigation boundary coordination: #270 requalification is complete on current main via merged test-only PR #352 (cc18b9337374ea6aadc570280d503547f3621497). The production top-level Location/native admission implementation remains sufficient; the reopened failure was a stale IndexedDB fixture that attempted script navigation without a host callback. Chromium href/replace controls, native typed-request ordering/performance, realm replacement, close lifecycle, and IndexedDB gates passed. This does not change or widen the nested-document/webview scope owned here.

[wieslawsoltes]

#312 is complete via #354 at 15d55a4c07d742fc3ba5f4290dfa87b082a04b70. Requalification showed the reopened Linux timeout came from a reentrant synchronous frame-writing fixture, not production ServiceWorker interception. The corrected navigated-frame retirement path passed exact-head Linux/macOS CI, portable V8, Native Linux document/SDK contracts, and 20×100 local lifecycle cycles with flat V8 heap and <=62.05 MiB RSS growth. Child portability issue #355 is also closed.

[wieslawsoltes]

Owned from exact post-#354 main 15d55a4c07d742fc3ba5f4290dfa87b082a04b70 on feature/local-resource-admission-266.

The first unsupported/unquealified unchanged-Code resource semantic is host-owned localResourceRoots admission. The current native runtime already contains #323 range/cache metadata, #333 bounded host-message streaming, #341 abort/timeout retirement, and #354's parser lifecycle fixture correction. This slice will preserve 401/404 admission results and fail-closed malformed/traversal behavior through that existing browser pipeline. It will not add filesystem authority or interpret WebScene's single component resource_root as a webview allowlist.

Planned owned paths are the Service Worker resource contract/native gate and a new dedicated WebPlatformSubset admission profile. Runtime files will change only if the reduced exact-worker contract proves a missing generic Fetch/Response/stream/cache semantic.

Collision audit: open PR #76 owns only docs/code-oss-compatibility.md; active #248 owns File System Access runtime/ABI/broker paths; #362 owns webscene_stylesheet_cssom_compatibility.h, browser DOM CSSOM tests, and its MediaList contract/profile. This slice excludes all of those, AppScene, CSS parsing/cascade, localhost mapping, vscode-demo, and consolidation work.

[wieslawsoltes]

Resource child #364 is complete through merged #368 (83b2c4e8). WebScene now preserves unchanged Code's host-owned local-resource admission results through streamed Service Worker response tees, cache validation, ranges, fail-closed denials, late-message retirement, and 100-cycle teardown without adding filesystem authority.

#266 now advances to the remaining localhost port-mapping semantic, then final product/offline acceptance.

[wieslawsoltes]

Resource child #371 is attached under #266 from exact WebScene 83b2c4e8. It qualifies only the generic Fetch redirect step after unchanged Code's host-authorized localhost mapping reply. Code/AppScene retain mapping, tunnel, network-permission, and socket authority; the slice is disjoint from File System Access lifetime #370, AppScene#156, CSS #366/PR #369, AppScene source, WebSocket transport, #76, and vscode-demo.

[wieslawsoltes]

Resource-plane update: #371 / #374 merged as c9079ba7dd9488f1ed59520444703c370c9afd20. The unchanged Code OSS v6 load-localhost / did-load-localhost exchange now reaches the host-authorized target through WebScene's existing loader with browser-compatible redirect modes and fail-closed invalid/loop handling. This adds no mapping, tunnel, WebSocket, filesystem, origin, or CSP authority. Direct Linux/macOS/portable-V8/native-document gates and the 100-cycle Chrome oracle passed.