DESEN is a data-only executable design protocol. This repository contains its Web–React reference implementation, the Desen App visual authoring product, and the proof infrastructure used to make bounded, reproducible claims about both.
M10/G10 and M10A-T01 through T20 are complete; T21 is next; M11 remains gated by G10A.
Overall: ███████████████████░░░░░░ 141 / 176 tasks complete (80%)
M02 complete: █████████████ 13 / 13 tasks complete (100%)
M03 complete: ██████████ 10 / 10 tasks complete (100%)
M04 complete: █████████████████ 17 / 17 tasks complete (100%)
M05 complete: █████████ 9 / 9 tasks complete (100%)
M06 complete: ███████████ 11 / 11 tasks complete (100%)
M07 complete: ███████████ 11 / 11 tasks complete (100%)
M08 complete: ██████████ 10 / 10 tasks complete (100%)
M09 complete: ██████████████ 14 / 14 tasks complete (100%)
M10 complete: ████████████ 12 / 12 tasks complete (100%)
M10A: 20 / 28 tasks complete (71%) · T20 is closed; no completed work removed.
Proof gates: 11 / 14 complete · G10: DONE · Runtime Core baseline: frozen ·
Next task: M10A-T21 (NOT_STARTED; resource/operation connections and explicit host readiness) ·
M11: NOT_STARTED
The completed G10 terminal gate joins nine independent Chromium journeys with the exhaustive proof graph. Within the declared Web–React profile, a designer can author, validate, publish, activate, update, reject, and recover a managed surface without a developer recreating that surface in the host's React tree.
The proof includes:
- visible authoring through the normal Desen App product;
- deterministic Source-to-Bundle publication;
- an independently built host consuming the active revision;
- label and layout updates without host source or asset changes;
- invalid-publication rejection without replacing the valid design;
- last-known-good recovery across complete process restarts; and
- a committed Runtime Core tree baseline for the M11 comparison.
It does not prove native runtimes, production security, remote multi-user deployment, arbitrary capability interoperability, or public-alpha release readiness.
Requirements: Node.js 24 or newer and pnpm 11.15 or newer. Exact versions are recorded in
.node-version and package.json.
pnpm install --frozen-lockfile
pnpm --filter @desen/app-browser-e2e exec playwright install chromium
pnpm demo:resetpnpm demo:reset starts a clean, dedicated local M10 demo workspace. Use pnpm demo to resume it.
The demo runbook explains the authoring, test, publish, update, and
recovery journey.
Desen App -> DESEN Source -> Publisher -> immutable Bundle -> Control Plane
|
v
separate Host
|
Runtime Core + target adapters
The protocol, validator, publisher, Runtime Core, and Editor Core are platform-neutral. React, DOM, CSS, and browser concerns enter only through target-specific adapters and applications.
apps/
desen-app/ Visual authoring and publishing product
desen-app-browser-e2e/ Independent Chromium product journeys
design-system-workbench-proof/ Isolated T03 theme/token browser proof
starter-catalog-web-proof/ Isolated starter authoring/host adapter proof
reference-host-web/ Separately built proof host
reference-host-web-server/ Local host/control-plane bridge
control-plane-api/ Local Source, Bundle, channel, and activation service
desen-run/ Future developer-platform surface
packages/
protocol/ Frozen 0.1.0 inputs and portable primitives
validator/ Structural and semantic validation
publisher/ Deterministic Source-to-Bundle publication
runtime-core/ Framework-neutral execution semantics
runtime-react/ React adapter integration
runtime-web/ Browser host ports and recovery storage
catalog-sdk/ Capability registration and manifest tooling
editor-core/ Framework-neutral authoring commands
design-system-core/ App-owned project data and deterministic token resolution
design-system-authoring/ Platform-neutral theme/token editing and transfer
design-system-release/ Platform-neutral immutable release identity and exact-digest store port
editor-web/ Web canvas and inspector integration
reference-catalog-web/ Reference components and adapters
starter-catalog-web/ Base UI-backed DESEN Neutral starter capabilities
testkit/ Fixtures and conformance helpers
desen/ Future public facade and CLI
- Frozen DESEN 0.1.0 upstream bytes are never edited to make implementation tests pass.
- DESEN documents contain data and never select arbitrary executable code.
- Packages never depend on applications; platform-neutral packages never import platform code.
- Desen App preview and the reference host resolve the same registered capabilities.
- The reference host contains no handwritten managed-screen component tree.
- Unknown or incompatible semantics fail explicitly.
- Failed activation preserves the last-known-good revision.
- Public exports require TSDoc, and implementation choices outside the protocol are labeled as reference profiles.
- Current project status — current transition and verified closure only
- Turkish start guide — contributor reading and execution order
- Task board — canonical status, dependencies, deliverables, and evidence
- Master plan — milestone intent and gates
- Architecture — system boundaries and dependency direction
- ADRs — decisions and their consequences
- Proof Matrix — claim-to-evidence authority
- Protocol Findings — frozen-spec ambiguities and profiles
- Debt Register — explicit cleanup ownership and deadlines
- Documentation Standards — document lifecycle and size budgets
Use the bounded baseline for ordinary task feedback:
pnpm format:check
pnpm lint
pnpm typecheck
pnpm build
pnpm boundaries
node scripts/ci/verify-proof-reader-checkpoints.mjsRun pnpm check for an exhaustive local audit or gate closure. Run pnpm test:e2e for the complete
nine-journey Chromium suite. Hosted completion still requires the task's exact-head CI contract.
M10A adds a Base UI-backed starter library with DESEN
Neutral styling, editable themes, reusable components, design-first authoring, separate behavior
connections, and built-in design-system documentation/visual review. These are planned features,
not capabilities of the current five-component demo. The completed M10A-T01 installed Base UI
1.8.0 and proved three adapters in isolated authoring/host harnesses. The completed M10A-T02 adds
the platform-neutral App project envelope and bounded DTCG token resolver; its exact-head and
fresh-main hosted Quality and Browser E2E gates passed. M10A-T03 is DONE: its
platform-neutral @desen/design-system-authoring plus isolated workbench provide
structured theme, mode, token, and whole-token-alias controls; exact sRGB and px/rem handling;
atomic history and import; and bounded loss-aware transfer. The frozen SC-01 inventory's 16 valid
fixtures split into three T02-supported normal edit/preview paths and 13 losslessly preserved,
disclosed unsupported paths that block partial preview only for their selected overlay; seven SC-01
invalid fixtures reject atomically. A separate closed T02-recognized unsupported matrix preserves
and discloses six valid fixtures and atomically rejects ten malformed fixtures. Unreviewed or
invalid forms fail closed without silent loss. Exact-head PR and fresh-main hosted Quality and
Browser E2E gates passed (see the T03 proof). It adds no normal App
integration, persistence, Publisher, Runtime, or protocol authority. M10A-T04 is DONE: its
platform-neutral @desen/design-system-release adds a finite content-addressed token/asset/recipe
manifest, exact host-profile references, and a no-latest release-store port. Its exact-head and
fresh-main closure is recorded in the T04 proof; it adds no runtime
activation, normal-App integration, or persistent production store. M10A-T05 is DONE for its
bounded private layout/content starter Catalog and isolated proof harness, not normal-App integration.
M10A-T06 is DONE with isolated 0.3.0 form-control evidence and hosted closure
(T06 proof). M10A-T07 is DONE with its hosted 0.4.0
selection/numeric Catalog proof. M10A-T08 is DONE with its hosted
0.5.0 overlay/disclosure proof; M10A-T09 is DONE with its hosted
0.6.0 data-display/feedback proof. Those 0.5.0/0.6.0 receipts are immutable; M10A-T12
owns the current 0.7.0 Catalog and is DONE with hosted closure: lazy typed Inspector controls, token/literal/reset styles, responsive preview, and aggregate persistence. M10A-T13 is DONE with hosted closure for safe local assets; M10A-T14 is DONE with hosted closure for bounded history and identity-safe reuse; M10A-T15 is DONE with hosted closure for masters, linked instances, overrides, detach and isolated master editing; M10A-T16 is DONE with hosted closure for named variants and declared visual-state authoring; M10A-T17 is DONE with hosted closure for the Catalog-backed Design System explorer and documentation controls; M10A-T18 is DONE in the same hosted closure for exact library version identity, local usage indexing, impact comparison, explicit adoption/rejection and restore; M10A-T19 is DONE with hosted closure for the separate Connections workspace and durable inert drafts; M10A-T20 is DONE with hosted closure for Source-backed visual behavior wiring. T21 is selected next; M11 remains gated by G10A.
SC-02 records an owner-directed adaptation, not a two-pilot
validation pass. No further external interviews are required for this plan. Map (M11-T01) and
Sortable (M11-T08) wait for G10A and preserve the frozen Runtime Core tree.
The chronological archive and immutable pre-consolidation pointer are owned by the documentation standard. Task results remain in task-owned proof documents. This living README intentionally does not duplicate chronological receipts.
The following line is an immutable CI-02 compatibility pin describing its historical pre-merge state, not current status:
CI-02: conditional DONE on this exact PR head's hosted Quality gate; canonical status remains IN_PROGRESS while it is pending
Read CONTRIBUTING.md before changing code. Report vulnerabilities through the private process in SECURITY.md, never through a public issue.
Apache License 2.0. See LICENSE.