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
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.
Decisions so far
-
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.
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
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.
Decisions so far
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