Design a portable contribution SDK and WebExtension runtime

[dvcolomban]

Current frontier, 2026-10-04

Portable contribution proof is accepted and closed after the owner's walkthrough. Its bounded proof does not complete broader SDK conformance. The inventory now records that acceptance; its documentation derives counts from the generated report and describes the actual shared browser/debugger receipt contract.

Continue with State scope and recovery, the open dependency of renderer and reload work. Native ownership stays settled. Both browsers now prove natural suspension with quiet or waiting RPC clients and explicit fresh restoration. Production-panel navigation proves sibling continuity, admitted handler completion, a fresh document/caller with current state and real peer closure. A separate minimal native birpc backport prevents replies after RPC closes, retaining handler diagnostics. Malformed Firefox storage proves visible startup rejection without overwrite, no retry after correction alone, explicit reload and saved state in fresh peers. No SDK API, cancellation or recovery controller was added. Broader supported modes and native I/O/installation limits remain open. Same-host native filesystem recovery now proves a later explicit mutation after caller path repair through both actual native backends, using the same clients/provider. All 18 affected package tests, strict lint/types and a separate live in-app confirmation pass; current full CI is queued/running.

Examples and API coverage contract retains the complete obligation: 814 public paths, 460 linked paths and 38 groups with broader gaps. Local conformance validates 110 browser references across 65 receipts, 621 distinct checks and 366 unit-test references. The two new references are actual native server path-repair cases. Prior independently inspected full CI passed at 241fd1e, including the then-linked suspension, navigation and malformed-storage slices and the documentation reconciliation. Its downloaded artifact independently verifies all 110 browser references, 65 receipts, 621 referenced checks and 364 unit-test references; every linked unit case passed. The prior full CI at 8a6e682 is successful and independently verified against its downloaded artifact: 107 references, 62 receipts, 599 checks and 362 unit-test references. Superseded intermediate jobs are not counted as full validation of the new code.

Manual Chrome permission interaction and upstream publication approvals remain separate owner inputs. The minimal birpc source candidate now passes fresh frozen upstream-native lint/types/build and baseline/fixed regression checks in b8c958d; its full CI passed. Debugger and CDB contract now retains refreshed peer callbacks, native activation, worker recovery and detached-child source/test handoffs in 8adbb19. Scoped frozen installs and native checks pass; DevTools publication retains its callback-capable hub prerequisite. These optional publication permissions introduce no new SDK architecture choice. Publication approval does not block independent implementation because verified pnpm backports are installed. The separately approved state-echo correction remains Devframe draft 422.

Destination

Produce an implementation-ready specification for a generic, modular contribution SDK, complete WebExtension runtime, and devframe/devtools adapters in dvcol/devkit-extension. The specification must support writing one framework-neutral contribution and using its capabilities through different providers, with explicit differences in availability and lifecycle.

The eventual monorepo must contain working examples of every piece and automated proof for every public SDK API, hook, and feature across all supported hosts. A completed decision map supplies the contracts and implementation sequence; the implementation release requires the examples and tests themselves to work.

Notes

Agreed requirements

• Stay close to Devframe public APIs and terminology. Reuse native auth, RPC, codec, shared state, JSON rendering and Vite lifecycle. Any new adapter API must name a concrete missing behavior; prefer deletion once upstream supplies it. The implementation and map review maps every maintained package and open ticket to that rule.

• Own the common contracts and adapters in a pnpm/Turbo monorepo in this repository. Separate reusable contracts, capability implementations, adapters, renderer integration, build tooling, reference extension, and examples so later upstream adoption is practical. Upstream acceptance is not a prerequisite.

• Support current stable Chromium and Firefox initially, as selected by the project owner. Record exact tested versions for each audit/release and advance the baseline with stable releases. Capability availability is explicit, can change during execution, and can differ by browser or realm. Third parties must be able to add capabilities and realms without extending a closed central switch.

• Compose executable contribution packages at build time. A contribution can consist of UI alone, actions alone, state, HTML transforms, HTTP transforms, realm implementations, or any combination. Shared behavior is supported where the required capabilities exist.

• Reuse the devframe JSON protocol and reference renderer where feasible. Contribution authoring and public contracts are framework-neutral; renderer implementations may use any framework. Provide a working custom-renderer example to demonstrate replacement through the public contract.

• Include background execution, isolated content scripts, page-world integration, DevTools, options, popup, side panel/sidebar, and debugger integration. Contribution views and extension controls use JSON rendering; the replaceable host owns mounting, navigation, and browser lifecycle.

• Every capability API exposes typed context. Distinguish provider identity/realm, execution context, capability-specific resource identity, and UI surface. Native handles remain local to the execution context that owns them; remote callers receive descriptors and transported operations.

• Contributions declare routing defaults with per-operation overrides. Support broadcast, selection callbacks, precedence by provider ID or realm, and selection driven by UI input. Broadcast exposes individual provider outcomes, including partial failure. Provider state remains distinct; explicit selection, aggregation, and optional synchronization belong to contributions.

• Support development HMR and watched production builds with a live preview backend. Update/restart/reload the affected layer, reconnect, and restore explicitly retained state. Determine the precise change matrix through the reload decision ticket.

• Provide native debugger access and a real optional adapter for dvcol/chrome-debugger-bridge, including an extension-only path. Prove target/session ownership and HTTP-interception compatibility. Resolve current managed-domain configuration gaps before promising capability support.

• Use current Vite/Oxc tooling, strict Oxlint rules and enforced Oxfmt formatting. Migration from ESLint, Stylelint and Prettier is a required foundation step before production SDK packages and maintained examples: replace direct tooling dependencies, configurations, scripts, staged-file hooks and CI invocations; enforce warnings-as-errors, supported type-aware checks and formatter check failures. Default-rule research probes do not satisfy this gate. Prefer TypeScript 7 when checking, build, declaration emit, package consumption, and required tools all work with it. The existing template may be replaced. Release and conformance contract retains the migration completion checks.

• Deliver runnable examples for contributions, custom renderers, standalone devframe hosts, devtools hosts, Chromium and Firefox extension hosts, routing/composition, transforms, debugger/CDB, and development/live-preview workflows. Share fixtures through public packages rather than duplicating implementations.

• Maintain an API/hook/feature → example → automated test → supported host/mode matrix. Every supported cell must execute successfully; unsupported combinations must assert an explicit unavailable result. Test success, error, disposal, permission changes, navigation, disconnect/reconnect, and retained-state recovery where applicable. A passing build or mocked browser API alone is insufficient proof of browser behavior.

• Keep local validation scoped to affected packages/tasks. Full repository validation belongs in CI. Vitest tests use exact expect.assertions(N); avoid coverage-ignore pragmas and production dependency-injection parameters added only for tests.

Workflow and issue quality

Use the wayfinder, grilling, domain-modeling, and research workflows. Child issues are self-contained decision briefs with existing-code context, alternatives, illustrative pseudocode, concrete scenarios, dependencies, and specific Definition of Ready and Definition of Done checklists. API names in open-ticket pseudocode are candidates until a resolution settles them.

Claim a ticket by assigning it to the developer driving the map before starting work. The frontier consists of open, unassigned children whose native blockers are closed. Continue the map and implementation after architecture settles until a material owner decision requires input, as explicitly authorized in the live review. Keep commits separate by ticket. Independent research may run in parallel; unresolved human decisions still require the owner’s answer. A human-led ticket requires a real discussion and confirmation of its resolution.

Post the canonical answer as a resolution comment with evidence links, close the issue, and add a short named link below. Newly exposed questions become equally detailed children with native dependency links. Inspect evidence rather than treating a successful tool invocation or an agent summary as proof.

Evidence and current scope

Server adapter contract is resolved and closed: native adapter interfaces, host ownership, development/preview lifetimes and current real-host proof are recorded. Remaining reload, authority, script and full-matrix acceptance stay with their named owners. The latest full CI passed at bcd79213ea47a11ae13d0e923e75e71e1a5e7359.

Maintained package exports, ARCHITECTURE.md, and GLOSSARY.md define the implemented contracts. Child issues own implementation receipts and remaining acceptance criteria. Dated checkpoints describe their recorded commit; they are not current blockers. This map is an index, not a delivery log. Native sub-issues and dependency links identify unfinished work.

Native server/Port connections, separate provider state, JSON action routing, custom rendering and browser-surface reload behavior have maintained evidence. These partial deliveries do not establish complete API/host conformance, arbitrary worker-suspension recovery or untrusted page authority. CDB is an optional capability integration and does not block generic scripts/transforms.

Current implementation pointers, reconciled 2026-10-02:

Current progress is indexed by its owning ticket:

Examples and API coverage contract records 814 public paths, 413 linked execution paths and 34 remaining gap groups; the preceding full CI passed. Injection and transform contract now adds native child-frame/CSP acceptance in commit de473a7: all four local native modes pass, and independently verified evidence totals 232 exact native checks across 30 receipts. Full CI for this slice passed; all 41 references to 30 distinct retained payloads were independently verified, including all 232 exact checks and 288 new frame/CSP document observations. Broader script/transform obligations stay open. Debugger and CDB contract now records pending child-command acceptance through both native backends. Raw Chrome reproduces delayed child-detach settlement; existing provider cleanup rejects the pending call. Local native/unit/lint/type checks and full CI pass; actual Linux receipts independently confirm both pending-child outcomes and final cleanup. Production and SDK APIs stay unchanged; prompt child-detach settlement remains a native gap. Prior failure investigations and their exact limits remain in their owning tickets.

• State scope and recovery now includes natural background idle in Chromium and Firefox, with confirmed-write restoration through explicit fresh clients. The latest Firefox idle commit and full CI pass. Firefox quota pilots retain actual write rejection, a failed first post-deletion attempt and a successful further explicit action with unchanged native identities. They still need a maintained runner. Interrupted work and broader native failure acceptance remain open.
• Injection and transform contract contains maintained native script, Vite HTML and Chromium/Firefox header examples. Native redirect examples are committed and pass both production and development browsers locally, with exact receipt mapping and the executed API gate passing. Latest combined full CI passed. The preceding renderer republication failure has a matching delayed native-state echo reproduction. The separate native correction passes deterministic installed-package regressions and real production browsers; its full CI passed. Devframe draft #422 now contains the independently reproduced native fix and reproduction steps. The earlier CI packet history remains unknown. Native response-body streaming now passes all four local browser commands: Firefox streams preserved bytes and completes admitted work after disposal; Chromium explicitly rejects the unavailable method. Retained receipts, scoped strict checks and combined full CI pass. Idle wakeup, broader encodings and remaining native lifecycle acceptance stay open.
• Debugger and CDB contract now exercises both real native backends with minimal callback-forwarding patches. Its implementation and full CI pass. Shared child-session acceptance passes through both real native backends and full CI. Publishing the two new upstream drafts awaits owner approval; local patches already allow implementation to continue.
• Release and conformance contract records the native publisher module identity correction. Native Vite deduplication restores one publisher/index owner; baseline failures, scoped checks and four real-browser reruns are recorded separately from the state-echo investigation.
• Permissions and trust still needs the human Chrome native refusal/grant/regrant sequence. The in-app browser cannot perform extension-native permission prompts. Background-owned native content execution needs no new SDK trust policy; remaining document/frame acceptance can proceed independently.

No new generic SDK architecture choice is identified at this frontier. Pending human input is Chrome prompt availability and approval for the two reviewed peer-lifecycle drafts. The separately approved native state-echo correction is published as Devframe draft #422; full downstream CI passed, and full upstream CI passed across lint, Ubuntu/Windows Node 22/24/26, end-to-end tests and Bun/Deno. Local patches already allow independent implementation to proceed; no new SDK architecture choice is required. The owning tickets retain detailed receipts and acceptance gaps.

Dependency-order correction: State scope and recovery remains a native blocker of Renderer and surface contract. The implemented view slice uses accepted native state behavior; the open state acceptance gate was not closed by that slice. Complete the state gate before expanding the broader renderer work. Debugger and CDB contract is independent and can advance without a new generic architecture decision.

• Renderer and surface contract: 52bc770 implements the accepted native setup recipe, defineView({ id, execution, requires?, setup }). The same counter recipe runs in Devframe, DevTools, Vite and extension hosts. Native browser tests verify dependency loss, removal, current-state republication and cleanup of pending reads. Scoped validation passes; full CI passed, including both production browsers, native persistence, concurrent development transitions and the executed API-evidence gate. Surface placement, renderer HMR and broader management UI remain open.
• Provider discovery and routing is resolved and closed. Realm/provider selection, callback and broadcast semantics, application-owned discovery and native connection ownership are accepted and implemented; authority/surface/full-matrix follow-ups retain their own owners.
• State scope and recovery verifies forced Chromium worker termination, independent server connections surviving background loss and explicit fresh connections. The native server persistence example now restores saved counters on both hosts, with real file-failure tests and live in-app peer checks. Full CI passed for the server commit. Opt-in native extension persistence now verifies confirmed-write restoration after forced Chromium worker termination, real quota failure and invalid-data rejection. Its full CI passed. Firefox explicit-reload persistence also passes locally with no runtime changes; the combined final CI passed at 34e301f77bb9edfd767419e1506855f0ce00b3cb, including workspace validation, both native persistence tests, every production browser suite, concurrent development transitions and the combined executed API-evidence gate. Normal Chromium restart now also restores confirmed native storage for two fresh clients, with scoped checks passing. Stable Firefox browser restart with explicit native fixture loading now passes all six local checks in bfd62d3. Natural suspension, crashes, interrupted writes, permanent signed Firefox installation/automatic availability and broader lifecycle cases remain open.
• Live preview and reload contract records native DevTools registration-HTML updates, the corrected Firefox peer observation during reload and bounded native-sidebar control readiness. The exact actor-destruction observation fix passed full CI. Host-specific reload behavior remains explicit.
• Examples and API coverage contract now includes a runnable custom contribution kind in both native server demos and exact declaration/error-guard evidence. The native persistence evidence follow-up links exact Chromium and Firefox recovery scenarios. Public core declaration evidence now adds 24 compiled consumers for settled typing guarantees, with scoped checks passing. Its ticket owns the current coverage counts, CI status and remaining host/mode matrix.
• Debugger and CDB contract now also verifies native child-session routing and cleanup after frame removal. A minimal dependency patch corrects the reproduced cleanup defect. Full CI passed after the Firefox test correction. The owning ticket retains local results, the preceding failure and remaining debugger obligations.
• Release and conformance contract now also records removal of the four expired release-age exceptions in 0b533e8, with normal trust/age policy and packed native consumer checks passing. The earlier timeout correction records the reproduced native-build test timeout and its scoped two-line correction. Full CI passed for the combined changes; the owning ticket links the exact run and retains the remaining release obligations.
• Permissions and trust still needs a passing Chrome native permission sequence and remaining document/frame acceptance. Background-owned native content execution needs no new SDK trust decision; privileged page relays remain unimplemented and require a host-specific policy only when introduced. Injection and transform contract now has an accepted and implemented common script setup API in bcd7921. Native Vite/WXT declarations package code; defineScript owns registration and cleanup on Devframe/DevTools and WebExtension providers. All affected checks, native production/development browsers and the live in-app server confirmation pass. Full CI passed, including all native browser suites and the combined evidence gate. Broader script stages and HTTP transforms remain open; the packaging decision no longer needs owner input.

Decisions so far

• Portable contribution proof: owner accepted the bounded shared inspector across native and extension hosts, both renderers and selected packed consumers; wider SDK conformance retains its named owners.

• Server adapter contract: native provider composition, host ownership and development/preview boundaries resolved; broader execution evidence retains named owners.

• Provider discovery and routing: accepted recipient selection, implementation-owned applicability, identity, fallback, callback and broadcast policies are implemented on native server and extension connections.

• Upstream reuse audit: adopt pinned released RPC/state/JSON contracts through local adapters; renderer typing, browser lifecycle, CDB/Fetch and preview integration have named follow-up owners.

• Browser capability audit: current stable Chromium/Firefox native feasibility verified, including both native DevTools attachment orders and buffered response transforms; unrun lifecycle, permission-transition and broader interception guarantees have named acceptance gates.

• Toolchain and reload audit: adopt the measured TS7/Vite/Oxc/pnpm/Turbo portable pipeline; WXT is conditional on declaration and reload gates, with a working custom Vite fallback. Full example/conformance enforcement remains required.

• Contribution and realm contract: settled glossary, typed declarations, service ownership, lifecycle and multi-provider boundaries; canonical artifacts and 25 negative type fixtures published.

Not yet specified

Compatibility accommodations and migration decisions that may emerge from the selected upstream versions, extension build tooling, and complete portability experiment. Promote each newly concrete question into a child issue instead of leaving decisions in conversation history.

Out of scope

• Company-specific code, business capabilities, and migration of downstream extensions.
• Safari implementation for the initial release; the contracts must remain extensible.
• Runtime installation of executable contribution packages.
• Requiring upstream acceptance to proceed. Upstream PRs need specific owner authorization and start as drafts; existing authorized proposals and exact-version backports are tracked by their owning tickets.
• Recreating the complete native browser debugger frontend.
• Treating the planning prototype as completion of the eventual production SDK, working-example catalogue, or full conformance suite.