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

[wieslawsoltes]

Current implementation checkpoint — 18 September 2026

Pinned integration heads are AppScene eef005596716174594e9ec74966b89a0aba99a10, WebScene c595be47332adb88a50c374804c299f3db814616, and unchanged VS Code OSS 1.137 645f29cc3176500b4b5762ba887cf2a7f0ffdf2c.

Merged focused fixes in the latest tranche: AppScene #171; WebScene #431, #433, #434, #435, and #436. These cover directory deletion authority, the webview resource consumer matrix, canonical CSSStyleRule serialization, browser-shaped MessagePort accessors, directory removal, and dedicated-Worker cross-isolate MessagePort reachability. The current exact SDK archive is /private/tmp/appscene-webscene-sdk-ac235de-eef0055.tar.gz (2,868 files, SHA-256 031161a9c32274148852057b4af87e03635ae94d987e15271267a30a439e5b52).

User priority is implementation throughput. Release build and broad validation were stopped after the Code OSS payload completed and native host compilation began; no promotion claim is made. Validation debt remains recorded for one exact package after the implementation wave.

Active focused lanes:

• workspace/folder/file watch, Explorer refresh, open/save: WebScene Qualify remote workspace bootstrap, Explorer contents, and watcher refresh #252/Implement File System Access pickers and handles over AppScene native panels #248/Qualify VS Code file edit, save, revert, and hot-exit recovery #269 and AppScene Make transition frame-demand test deterministic #131;
• Markdown/webview nested-document lifecycle and interaction: WebScene Enforce secure nested-document lifecycle for Code OSS webviews #267/Complete nested-webview interaction, find, focus, and accessibility handoff #268 under [Epic] Qualify unchanged Code OSS webviews and nested document contexts #264;
• CSS/layout/paint/performance implementation: highest remaining VS Code-planned child under [Epic] CSS features, compatibility, validation, and performance #235;
• coordination: keep this epic and vscode-demo PR Typescript #1 current while focused PRs merge.

Remaining dependency order: finish and merge focused implementations; close the ServiceWorker/iframe remainder of #288/#81; complete workspace/files/save; complete webviews/Markdown; complete CSS/layout/paint and terminal behavior; then run one cumulative exact-package smoke, visual comparison, performance, size/disk, accessibility, workbench/Chat, lifecycle, zero-browser, signing/archive, and supported-RID release gate.

The consolidation PRs AppScene #65, WebScene #76, and vscode-demo #1 remain open and unmerged. Focused AppScene/WebScene implementation PRs merge immediately during this implementation wave; skipped checks are explicit validation debt.

Current implementation focus is the earliest reusable nested-document failure that blocks unchanged Markdown preview. #267 owns secure lifecycle/resource delivery; #268 owns focus, find, input, and accessibility handoff. #431 already merged the resource consumer matrix.

Implementation-wave update: WebScene #438 / PR #441 merged as 622a955c512dbf1853a042effe6a5b41cad53052, adding browser-shaped FileSystemObserver over opaque file and directory handles with bounded recursive polling and cleanup. WebScene #440 / PR #442 merged as 0ff47fc45bf574d71263821923c8e24e8dda34cb, adding nested-document execCommand("selectAll") and live multi-node Selection text. Current WebScene upstream main and the local integration gitlink are c595be47. Both PRs record deliberately deferred validation debt.

Final implementation-wave merges: WebScene #439 / PR #444 merged as d28995e2a8cd898a6ba5a3f43baffe091ccda18a, implementing aspect-ratio exposure, cascade/inline mutation, computed serialization, invalidation, pseudo projection, box-edge handling, and ordinary/flex/grid/floating/positioned sizing. WebScene #443 / PR #445 merged as c595be47332adb88a50c374804c299f3db814616, adding non-constructible Document.queryCommandSupported for copy/cut/paste/selectAll across top-level and iframe realms.

The local integration gitlink and WebScene upstream main now both point to 4ea2feeb. The previously built SDK archive at ac235def predates #441/#442/#444/#445 and is retained only as provenance; a new SDK/package plus all validation is deferred. All queued focused-PR CI tails were canceled under the implementation-only directive.

Implementation-only wave complete. WebScene main and the vscode-demo gitlink are c595be47332adb88a50c374804c299f3db814616. Focused merges after #445: #447 :required/:optional; #450 iframe clipboard Permissions Policy; #451 circle clip; #453 :read-only/:read-write; #455 nested meta CSP script admission; #458 Code OSS polygon clip; #459 end-to-end input.indeterminate; #461 stale iframe generation rejection; #464 brightness() paint; #465 :in-range/:out-of-range; #467 one-shot nested pagehide; #469 grayscale() paint.

Every child issue and parent epic records deliberately deferred WPT/browser/native/build/performance/memory/lifecycle/package/CI validation. The newest SDK archive remains the pre-wave ac235def package and is stale against current main; cumulative validation and a new SDK/release are the next phase. WebScene draft #76 is rebased to 4e79c127 on c595be47 and remains unmerged. AppScene #65 and vscode-demo #1 also remain unmerged.

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.

[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.