docs: chart json-render package wayfinder

Author: antfubot

plans/json-render/issues/01-research-upstream-json-render.md

@@ -0,0 +1,15 @@
+# Research upstream json-render contracts
+
+Type: research
+Status: resolved
+Blocked by: none
+
+## Question
+
+Which public contracts and runtime semantics in the current `@json-render/core` and `@json-render/vue` releases must the Devframes packages adopt, re-export, configure, or deliberately constrain? Compare the current release with the version embedded by `vitejs/devtools`, covering schema/catalog typing, registries, state and binding expressions, actions and validation, streaming, extension composition, renderer lifecycle, package stability, and licensing.
+
+## Answer
+
+See [Upstream json-render contracts](../research/upstream-json-render.md).
+
+The current upstream pair is `@json-render/core@0.19.0` and `@json-render/vue@0.19.0`. Its catalog and registry types aid authoring but do not fully validate component props, authorize actions, compose extensions, or guarantee lifecycle behavior. A direct Devframes re-export therefore needs reviewed named exports, exact upstream pinning, a separately versioned protocol validator, and compatibility tests. The report also records the Apache-2.0 obligations and recommends keeping streaming optional until the protocol decision explicitly adopts it.

plans/json-render/issues/02-research-existing-integration-seams.md

@@ -0,0 +1,15 @@
+# Inventory existing JSON-render and runtime seams
+
+Type: research
+Status: resolved
+Blocked by: none
+
+## Question
+
+What behavior currently exists in this repository and `vitejs/devtools`, and which devframe and hub seams can host it without violating their boundaries? Trace the current hub types, `createJsonRenderer`, shared-state transport, dock projection, Vite viewer, standalone adapters, static dumps, client host, package build conventions, and tests. Record concrete compatibility obligations and architectural constraints rather than proposing the final API.
+
+## Answer
+
+See [Existing JSON-render integration seams](../research/existing-integration-seams.md).
+
+The current repository owns permissive hub types, a hub-only shared-state factory, and a JSON-render dock discriminator; `vitejs/devtools` owns the only renderer and catalog. Wire projection accidentally strips renderer methods and leaves `_stateKey`, standalone adapters have no renderer assets or factory, and static dumps can replay specs but not RPC actions. The hub's existing headless client boundary is suitable for renderer substitution, while stable scoped identities, explicit serialization, cleanup, standalone assets, declared-action isolation, and dedicated tests are missing.

plans/json-render/issues/03-define-package-contracts.md

@@ -0,0 +1,13 @@
+# Define package ownership and public exports
+
+Type: grilling
+Status: open
+Blocked by: 01, 02
+
+## Question
+
+What does each package own and export, and what dependency direction keeps the protocol stable, devframe-native, and renderer-swappable? Resolve the direct `@json-render/core` re-export surface, schema and catalog exports, renderer handles, Vue registry and shell exports, subpath exports, peer dependencies, type names, and the boundary with `devframe` and `@devframes/hub`.
+
+## Answer
+
+Pending.

plans/json-render/issues/04-define-protocol-semantics.md

@@ -0,0 +1,13 @@
+# Define catalog, state, and action semantics
+
+Type: grilling
+Status: open
+Blocked by: 01, 03
+
+## Question
+
+What makes a Devframes JSON-render spec valid and portable? Define the versioned base catalog, extension catalogs and compatibility metadata, declared and validated actions, state ownership and binding updates, replacement versus incremental updates, whether streaming/generative-UI primitives enter the initial protocol, serialization limits, validation timing, failure behavior, and how direct upstream re-exports coexist with a stable Devframes protocol.
+
+## Answer
+
+Pending.

plans/json-render/issues/05-define-devframe-runtime-integration.md

@@ -0,0 +1,13 @@
+# Define devframe runtime integration
+
+Type: grilling
+Status: open
+Blocked by: 02, 03, 04
+
+## Question
+
+How does an author declare and update one or more JSON-render views on a devframe, and how does the same definition run through CLI, dev, SPA, build, Vite, and embedded adapters? Resolve view identity and lifecycle, scoped shared state and RPC actions, static snapshot behavior, default standalone UI assets, ownership of `createJsonRenderer`, disposal, reconnects, and whether the integration requires a general devframe view primitive.
+
+## Answer
+
+Pending.

plans/json-render/issues/06-define-hub-projection.md

@@ -0,0 +1,13 @@
+# Define hub projection and renderer substitution
+
+Type: grilling
+Status: open
+Blocked by: 03, 04, 05
+
+## Question
+
+How does a hub discover and project a devframe JSON-render view into a dock while remaining headless and UI-framework neutral? Define dock metadata, client-host responsibilities, renderer selection and injection, use of the official Vue UI versus a third-party implementation, catalog compatibility checks, loading and error states, disposal, and migration of the current hub-owned JSON-render types and factory.
+
+## Answer
+
+Pending.

plans/json-render/issues/07-define-official-vue-ui.md

@@ -0,0 +1,13 @@
+# Define the official Vue and Antfu Design UI
+
+Type: grilling
+Status: open
+Blocked by: 04
+
+## Question
+
+What exactly does `@devframes/json-render-ui` ship as the opinionated Vue implementation? Resolve its base component registry, fidelity and intentional changes from the Vite DevTools catalog, `@antfu/design` component mapping, semantic tokens and UnoCSS integration, icons, accessibility, loading and error surfaces, registry extension, renderer shell APIs, static-app assets, Storybook coverage, and theming responsibilities.
+
+## Answer
+
+Pending.

plans/json-render/issues/08-prototype-consumer-api.md

@@ -0,0 +1,13 @@
+# Prototype the end-to-end consumer API
+
+Type: prototype
+Status: open
+Blocked by: 05, 06, 07
+
+## Question
+
+Does one small, disposable API prototype make the intended seams natural for all key consumers? Demonstrate one view authored once, rendered by the official Vue registry standalone and in a hub dock, replaced by a third-party registry, updated through declared live actions and state, and emitted as a static snapshot. Use the prototype to resolve awkward ownership, naming, lifecycle, and configuration before the specification is assembled.
+
+## Answer
+
+Pending.

plans/json-render/issues/09-assemble-implementation-spec.md

@@ -0,0 +1,13 @@
+# Assemble the implementation-ready specification
+
+Type: task
+Status: open
+Blocked by: 01, 02, 03, 04, 05, 06, 07, 08
+
+## Question
+
+Consolidate the resolved decisions and prototype into the destination specification without reopening them. Include package manifests and exports, public TypeScript API sketches, runtime and data flows, component catalog, extension and substitution model, devframe and hub changes, migration of existing repository APIs, diagnostics, documentation, test matrix, acceptance criteria, and an ordered implementation sequence suitable for follow-up tickets.
+
+## Answer
+
+Pending.

plans/json-render/map.md

@@ -0,0 +1,33 @@
+# JSON Render Packages Wayfinder
+
+## Destination
+
+Produce an implementation-ready specification for `@devframes/json-render` and `@devframes/json-render-ui`: their package boundaries, public APIs, protocol semantics, official Vue renderer, devframe runtime support, hub integration, migration inside this repository, acceptance criteria, and implementation sequence.
+
+## Notes
+
+- This map plans the work; implementing or releasing the packages is outside its destination.
+- `@devframes/json-render` is a stable, devframe-native protocol package. It directly re-exports the relevant `@json-render/core` API and owns the Devframes catalog, declared-action contract, runtime handles, and integration helpers.
+- `@devframes/json-render-ui` is the official Vue implementation. Its registry implements the catalog with `@antfu/design`, while third-party registries can replace it.
+- The catalog has a versioned portable base and explicit extensions. A registry is a framework-specific implementation of a catalog.
+- Views work in standalone and hub deployments across live and static devframe outputs. Live outputs can use RPC actions; static behavior must be specified explicitly.
+- Specs invoke only actions declared for that view. An arbitrary string-to-RPC bridge is not part of the target contract.
+- The final specification covers this repository. Adoption and code removal in `vitejs/devtools` is a separate effort.
+- Relevant skills: `research`, `grilling`, `domain-modeling`, `prototype`, `antfu`, `antfu-design`, `vue-best-practices`, `unocss`, `vite`, `tsdown`, and `vitest`.
+- Local tracker operations: tickets are files under `issues/`; `Status: open` is unclaimed, `Status: claimed` is in progress, and `Status: resolved` is closed. A ticket is on the frontier when every number in `Blocked by` is resolved.
+
+## Decisions so far
+
+- [Research upstream json-render contracts](issues/01-research-upstream-json-render.md) — Upstream `0.19.0` is structurally reusable but pre-1.0 typing is not a validation or authorization boundary; direct re-exports require pinning and a Devframes-owned protocol guard.
+- [Inventory existing JSON-render and runtime seams](issues/02-research-existing-integration-seams.md) — The current hub transports whole specs through shared state and an accidental `_stateKey` projection; portable standalone/static rendering, stable identity, action isolation, cleanup, and tests remain to be designed.
+
+## Not yet specified
+
+- The implementation slices and test matrix. These become precise after the public API prototype establishes the package seams.
+
+## Out of scope
+
+- Implementing, publishing, or releasing the packages.
+- Changing `vitejs/devtools` to consume the packages or deleting its current implementation.
+- Official React, Solid, Svelte, or vanilla registries; third-party renderer compatibility is specified through the core contract.
+- Agent-driven UI generation beyond any protocol capability required to keep the base catalog compatible with json-render.