Repository navigation
Upstream reuse audit #2
Description
Part of Design a portable contribution SDK and WebExtension runtime.
Question
Which existing devframe, hub, JSON-render, Vite DevTools and Chrome Debugger Bridge contracts can the generic extension ecosystem reuse, which need adaptation, and what evidence justifies each boundary?
This research decision produces an adoption matrix and feasibility findings. It does not implement the SDK or change upstream repositories.
Context and current behavior
The destination is a generic pnpm/Turbo monorepo in dvcol/devkit-extension, with build-time contributions shared by server and extension providers. Contributions combine UI, actions, state, transforms and native behavior. Local packages establish contracts before optional upstream adoption.
Inspected devframe branch dvcol/rpc-client-disposal is at a3f967755af99a0a0d8dd82b7b5d4f3dd4aec0bc. Its JSON-render protocol defines serializable views and replaceable renderers. Its RPC client supports WebSocket, SSE and static backends; lower birpc channels are more general. Node contexts include filesystem and server assumptions.
Inspected DevTools branch codex/configurable-dock-renderers is at 121656dfc5866b2f8de5baa8e0b6166ec28599c8. Its kit context adds Vite primitives and JSON-render authoring. Its extension displays server-hosted UI without an extension-backed contribution runtime.
Inspected CDB revision 89bdf211e8e21d86aba70051c366bb03b38d43d8 is on dvcol/webmcp. @dvcol/cdb/embedded exposes an in-process broker/client; @dvcol/cdb-extension exposes a publisher with injected debugger operations. Core is runtime-neutral and extension helpers target browsers. Optional WebSocket entry points separate browser and Node transports. CDB's Devframe service and broker orchestration are Node-hosted; its connection client is browser-consumable. Audit these public exports for extension-only composition and reuse over an existing Devframe peer. None of these checkout observations establishes published-package or main-branch parity.
Requirements and scope
- Inventory public exports, dependency boundaries and lifecycle behavior for RPC, state, services, commands, docks, rendering, page channels, asset serving, Vite integration and optional CDB composition.
- Separate reusable protocol/types, reusable browser code, reusable Node code, private internals and missing capabilities. Record license and package-version constraints for actual reuse.
- Verify released-package availability independently of checkout availability. Record exact versions, exports and entry points; account for differences without silently depending on unreleased code.
- Identify where extension transport, service-worker recovery, permissions, target identity and isolation require adaptation. Browser feasibility itself belongs to Browser capability audit.
- Include development HMR and watched production builds served by a live preview backend. Existing static snapshots are a distinct operating mode.
- Define runnable example and test obligations for every adopted public SDK API, hook and feature, including unsupported, failure and lifecycle outcomes on every supported host.
Options and recommendation
One option directly exposes existing Node and hub contexts as the common SDK. It minimizes wrapping but carries server-specific assumptions into extension execution. Another builds an independent protocol and renderer, offering control at the cost of duplicate models and compatibility work.
The recommended direction to evaluate is selective reuse: preserve established JSON-render and transport-neutral contracts, place thin provider adapters in the new monorepo, and identify small upstream changes separately. Reuse the existing renderer implementation where feasible; its internal framework is compatible with a framework-neutral authoring API. Record evidence that could reject this recommendation, including browser bundling failures or required reliance on private internals.
Proposed API or experiment
Illustrative audit output, not a proposed public SDK API:
type ReuseDecision = {
feature: string;
sourceCommit: string;
publicExport: string | null;
releasedVersion: string | null;
disposition: 'reuse' | 'adapt' | 'upstream-change' | 'new';
supportedHosts: string[];
evidence: string[];
exampleAndTestObligations: string[];
};Trace a JSON view through state, transport, rendering and action dispatch, plus a page action and server operation. Trace embedded CDB and optional Devframe/WebSocket compositions. Check browser bundles for Node dependencies and verify package exports rather than assuming source-file imports are public.
Use disposable experiments when inspection cannot settle compatibility. Capture commands, package/browser versions, results and cleanup. One rendered button proves only that path, not complete SDK coverage.
Scenarios and acceptance criteria
- The same JSON spec renders through the reference renderer in a server-hosted page and an extension page; actions reach the intended provider or return an explicit unsupported outcome.
- A browser-target bundle imports shared contracts without pulling Node-only runtime dependencies. A failure identifies the responsible public import and viable extraction boundary.
- A transport interruption rejects pending operations and releases subscriptions. Record which behavior is already upstream and which requires a new contract.
- A watched renderer rebuild changes served bytes, while existing module caching is accounted for explicitly. Distinguish live state updates, renderer replacement and page reload.
- The adoption matrix connects every proposed public export to runnable examples and real-host assertions. Every supported API/host cell must execute successfully, with failure and lifecycle assertions added separately. Explicitly unsupported cells assert the unavailable result. Omissions prevent an implementation-complete claim.
Dependencies
No blocking dependency. This research unblocks Contribution and realm contract and Debugger and CDB contract through native dependencies. Exchange findings with Browser capability audit without introducing a cycle. Parent-map membership does not replace blocking edges.
Definition of Ready
- The three inspected revisions and relevant package manifests are available for read-only inspection.
- The destination, generic scope and local-first ownership are recorded.
- Public release metadata and official package documentation can be checked, or any inaccessible evidence is explicitly identified.
Definition of Done
- The adoption matrix records source and release evidence for all three projects, including CDB public exports, main/published parity, and embedded/browser/Node boundaries.
- Each recommended reuse has a public entry point, compatibility limits and an alternative if the required release is unavailable.
- Feasibility questions have observed evidence or become precise blocked decision tickets; uncertainty is not reported as support.
- The resolution specifies exhaustive example/test coverage obligations and names the contracts later tickets must settle. This ticket does not claim the future SDK is implemented or fully tested.
- Close the issue only after recording the answer; add a named link and one-line gist to the parent map.
Resolution record
Post the adoption matrix, checked revisions/releases, experiments, boundaries, coverage obligations, rejected alternatives and newly exposed decisions in the resolution comment. The map stores its named pointer.
Activity
dvcolomban commentedon Sep 22, 2026
Research checkpoint — this audit remains open.
Devframe release metadata, DevTools kit metadata, and CDB metadata distinguish the inspected development branches from released contracts: devframe and the relevant @devframes packages are at 1.0.0, Vite DevTools/kit at 0.7.5, and CDB packages at 0.3.0. The adoption report records public export and source/release differences.
Sixteen browser-facing public entries bundled with Rolldown's browser target and tree-shaking disabled, without Node builtins or external imports. The JSON-renderer hub registration entry is Node-only; its referenced prebuilt renderer asset bundled separately. This supports packaging feasibility, but does not prove mounting, disposal, transport recovery or host integration.
The recommended boundary is selective reuse of public JSON-render, RPC and runtime-neutral contracts, with provider adapters owned here. Native handles stay local. CDB extension-only composition, debugger ownership and response-stage Fetch configuration need runtime proof before support is promised.
Remaining gates include the real shared renderer/action/state path across hosts, lifecycle and reconnection checks, live-preview renderer replacement, CDB integration, and the complete API-to-example-to-test inventory. Published package availability and successful bundling cannot substitute for that execution evidence.
Explicit RPC close, shared-state patch/unsubscribe, and empty embedded-CDB disposal also passed bounded Node runtime probes. They do not establish browser Port recovery or Chrome debugger composition.
Retained research context: local, unpushed branch
dvcol/research/upstream-reuse, commit768a3ca, reportdocs/research/upstream-reuse.md. The full research artifact remains local; no public artifact URL is claimed. This checkpoint is not a resolution or an implementation-complete claim.dvcolomban commentedon Sep 22, 2026
Resolution
The Upstream reuse audit supports selective reuse through local provider adapters. Exact published artifacts and their integrity records are the operational baseline. The audit records viable contracts and explicit gaps; it does not claim the portable SDK, browser adapters or conformance suite already exist.
Consumable baseline
Checked on 2026-09-22:
devframe,@devframes/hub,@devframes/json-render,@devframes/json-render-ui,@devframes/vite: 1.0.0.@vitejs/devtoolsand@vitejs/devtools-kit: 0.7.5.@dvcol/cdb,@dvcol/cdb-extension,@dvcol/cdb-devframe,@dvcol/cdb-birpc,@dvcol/cdb-websocket,@dvcol/cdb-broker: 0.3.0.All thirteen downloaded baseline tarballs matched their npm registry SHA-512 integrity values; all 150 declared export targets existed. The Devframe package family has exact 1.0.0 peer relationships, and CDB's Devframe adapter pins that family at 1.0.0. The Vite adapter accepts Vite 7 or 8. These are package constraints, not proof of every permitted combination. Devframe, hub, Vite adapter, DevTools, kit, CDB Devframe adapter.
The checked source baselines were Devframe
a3f967755af99a0a0d8dd82b7b5d4f3dd4aec0bc, DevTools121656dfc5866b2f8de5baa8e0b6166ec28599c8and local CDB89bdf211e8e21d86aba70051c366bb03b38d43d8. Selected files were compared with upstream main at Devframe18fa60effeb928eb445add2a536cd44906a59981, DevToolsad2d6df720a513670f93ac09318ae6dc8b4a0623and CDB4053273d6d15ddb17abc3e1b14fc8d58122cb49a. Registry records supplied nogitHead; complete byte equivalence to those source revisions is not proved or assumed. Pinned published artifacts, their exports and observed behavior are sufficient for this audit's baseline. A reproducible upstream build would answer a stronger provenance question and is not required here.Adoption matrix
devframe/rpc/clientwith a local browser Port adapter.createRpcClientaccepts channel callbacks and exposes explicit call/close methods. High-leveldevframe/clientonly models WebSocket, SSE and static transports.devframe/utils/shared-statefor in-memory mutation, patching and subscriptions. Adapt server publication; define persistence, conflict, generation and recovery policy locally.devframe/node,@devframes/hub/node,/typesand/clientwithin their respective host boundaries. Do not expose Node contexts, filesystem or terminal facilities as universal extension APIs.@devframes/json-renderand/hub. Adapt/nodeview publication because its public argument is a Node context.jsonRenderUiRenderer()from@devframes/json-render-ui/hub. There is no public browser factory export. The Renderer and surface contract owns host typing before an extension adapter can be claimed.devframe/in-page-channel; extension isolated/main-world integration and trust remain separate work.@devframes/vite/huband@vitejs/devtools-kit/node, includingcreatePluginFromDevframe. Vite raw context is optional and local; Devframe, hub and kit contexts are layered.@dvcol/cdb/embeddedwith@dvcol/cdb-extension; keep browser/clientand/connectionimports separate from Node orchestration.@dvcol/cdb-birpc/clientand@dvcol/cdb-websocket/browserare optional transports.These classifications follow the public RPC channel, state implementation, kit context, renderer export map, CDB exports and extension exports. If a required release or adapter seam is unavailable, keep that capability explicitly unavailable or implement a narrow local alternative. Do not silently adopt unpublished source or private deep imports.
Observed evidence and limits
With Node 26.9.0, pnpm 12.5.1 and Rolldown 1.2.6, sixteen relevant released browser entry points bundled with tree shaking disabled and no Node builtins or external imports. The returned renderer asset also bundled. As expected, the renderer's Node helper,
devframe/nodeand the CDB Devframe package root failed the browser-builtin guard.A real Node MessageChannel probe confirmed that explicit RPC close rejects an outstanding call and removes listeners. Released shared-state instances passed patch synchronization, deduplication and unsubscribe checks. An empty embedded CDB bridge listed no targets and rejected use after disposal. These tests do not prove browser Port disconnect detection, worker recovery, rendering under extension CSP or actual CDP execution.
The renderer's current public type requires
DevframeClientContext; its RPC type restricts transport towebsocket | sse | static. Runtime use is narrower, but a cast or fabricated transport value would not prove a valid Port-backed contract. The Renderer and surface contract must choose a narrower supported interface, wrapper or upstream extension point. Mount contract, RPC type.CDB reserves
Fetch.enableandFetch.disable; the publisher's subscription activation sends domain enable/disable without configuration parameters. This is an explicit gap for configured patterns or response-stage interception. It is not evidence that all Fetch functionality is impossible. The Debugger and CDB contract and Injection and transform contract must settle a supported mechanism and one lifecycle owner. Catalogue, publisher.Remaining decisions and acceptance
Full Node contexts as the portable API, private renderer imports, assumed browser execution from successful bundling, and automatic equivalence between static builds and live preview are rejected approaches. Framework-neutral authoring remains compatible with a Vue-based reference renderer. The Devframe/DevTools/CDB manifests declare MIT; upstream JSON-render core/Vue declare Apache-2.0. Preserve notices and the wrapper's
@json-render/core ^0.20.0compatibility range rather than independently moving it to 0.21.0. Wrapper metadata, upstream core metadata.The audit's substantive Definition of Done is met through observed evidence and these named follow-ups. They own the remaining integration evidence and implementation decisions. Audit completion does not claim that those later obligations have passed, and does not create reverse dependencies on descendant tickets.
Retained evidence: local, unpushed branch
dvcol/research/upstream-reuse, commit0f808a2, reportdocs/research/upstream-reuse.md. The linked primary sources and the findings above are the public resolution; no hosted artifact URL is claimed.docs(issue-2): preserve upstream reuse audit and resolution