This directory holds product constraints, work specifications, architecture notes, measured
verification, and experiments; architecture/CHARTER.md is the
binding document, and CURRENT-CHALLENGES.md is the one place open
limitations are recorded.
- CURRENT-CHALLENGES is the single record of every known limitation, what is being done about it, and the evidence behind each. Limitations belong there, not scattered across the docs that describe what the framework does.
- ROADMAP explains the product path and the claims that still need evidence.
- CONFLICTS records decisions where strategy and the binding document disagree.
- Latest round ledger gives the current self-improvement state. The Studio hosting series describes the proposed container, session broker, and production path — for the private Studio repository, not this one.
- Engine-load comparison is the current external performance comparison; per-object cost records the Three.js submission-cost finding.
| Folder | Holds | Status of contents |
|---|---|---|
PRDs/ |
Numbered work specs, active proposals, and archived delivery records | Status follows the owning folder; pnpm budgets reports counts but does not enforce a PRD-file cap |
bugs/ |
One file per root-caused defect | Historical record; the open ones are indexed in CURRENT-CHALLENGES.md |
verification/ |
Gate results per PRD, dated, plus round ledgers | Historical record |
benchmark/ |
Protocol, sealed prompts, dated results | Binding protocol, VOID result |
strategy/ |
Market position, roadmap, money, metrics | Proposal. Nothing here is committed |
architecture/ |
Shape of things not yet built | Proposal, except where it records shipped behaviour |
product/ |
Constraints that will bind the product later | Mixed — store policy is external fact, the rest is proposal |
spikes/ |
Throwaway de-risking experiments and their results | Not binding, not shipped. Results amend the binding document |
- Active work: concern-specific folders under
PRDs/hold active proposals; direct-childPRD-*.mdfiles are a filing error.pnpm budgetsreports the active PRD count recursively. - Done work: completed PRDs live in
done/. - Blocked work: PRDs blocked on a named external dependency live in
BLOCKED/<reason>/, where blocked is not done. - Archive rule: a PRD moves to
done/in the same commit that finishes its acceptance evidence.
Active PRD categories are agent-leverage/,
experiments/, feature-mining/,
lighting/, mobile/, native/,
package-naming/, performance/,
starter-kits/, studio-hosting/,
tech-debt-code-quality/, tooling/, and
useful-defaults/.
The asset-pipeline series closed on 2026-08-22 as
done/asset-pipeline/.
batch-2026-08-22-defects/ closed on 2026-08-22 as
done/batch-2026-08-22-defects/.
Historical batch aliases and retired category names remain only in dated records; new active PRDs
use the concern-specific folders above. The former batch-26-08-17/ closed as
done/fps-friction-26-08-17/.
Studio is no longer in this repository. It is the local agent-and-preview surface — a server
plus one self-contained page — and on 2026-08-16 it became the paid product and moved to a private
repository, along with the hosting/ service that serves it (PRD-129). Nothing in this repository
is anything but MIT. The Studio PRDs stay here as the record of how it was built:
PRD-084,
PRD-085,
PRD-086, and the
Studio hosting series — all of them now describing work that
lives elsewhere.
A verification file is dated evidence for a gate, PRD, device run, or benchmark; it records what
was executed and what remains unproven. Native claims are evidence-bound: hosted macos-15
execution can produce iOS-simulator evidence, while physical-device, signing, thermal, battery,
and performance-parity claims remain open.
The technical-debt audit is a dated sweep of the whole repository rather than of one PRD: measured gate state, the code the gates do not fail, the friction recorded in builder sessions, and the defect shapes reviewers keep re-finding.
A round ledger records one self-improvement round's inputs, decisions, evidence, and resulting
state. pnpm round:next resumes from the latest ledger, and pnpm round:deletions reports
persistent unused-export evidence. The newest ledger is round 12;
the earlier rounds sit beside it.
The benchmark protocol, sealed genre briefs, and LOC report define the comparison. The dated result remains VOID; it is a measurement result, not a product claim.
Genre sweeps live under benchmark/sweeps/. Each archive retains the
built source, playtests, package manifest, sealed sweep manifest, and framework declarations
used by the measurer. Every run has a matching sweep ledger
with the brief hash, reach rate, used and unused exports, and blocking APIs. Round distinguishes
a baseline from a re-measure.
Compare archives with pnpm sweep:delta <round-1-archive> <round-2-archive>; pair completed
framework and vanilla archives with pnpm sweep:pair <framework-archive> <vanilla-archive>.
Proof sets under benchmark/genres/<genre>/proof/ run with
pnpm sweep:proof <sandbox-or-archive>. The round-2 delta
and caller census are the current supporting records.
Vendored package tarballs under each archive's vendor/ directory are not archived; they are
reproducible with pnpm pack, and sweep tests build their own temporary fixtures.
- VALUE-PROPOSITION — the framework's earned and unearned claims compared with vanilla Three.js
- POSITIONING — Runtime, Studio, Cloud, audience, and refusals
- ROADMAP — production path and evidence-bound status
- BUSINESS-MODEL — open-core and pricing hypotheses
- METRICS — north star and supporting measures
- CONFLICTS — resolved disagreements with the binding document
- ENTITY-MODEL — the ECS question and its closed decision
- THREEJS-CONSTRAINTS — Three.js gaps and framework ownership
- NATIVE-RUNTIME — device path, owned runtime, and physics ABI
- AGENT-INTERFACE — how an agent drives a project
- NATIVE-PERF-BOTTLENECKS — performance hypotheses
- NATIVE-RENDER-TRANSPORT — proposed render-thread layers and why they are not a roadmap
- CHARTER-HISTORY — how the binding document changed, so the Charter itself does not carry its own diff
Write-once/run-anywhere is owned as a gate by PRD-054; it remains blocked at acceptance criterion 1.
- PERFORMANCE-BUDGETS — frame budgets as test assertions
- ASSET-PIPELINE — deferred build-time pipeline and its triggers
- STORE-POLICY — Apple and Google constraints
- STRANGER-TEST-PROTOCOL — the single definition of the five-minute player experiment
Three folders hold dated technical write-ups. They are the detail behind CURRENT-CHALLENGES, which is the summary and the index:
bugs/— one file per root-caused defect, with the reproduction and the fix.
- 0a-mobile-render — closed mobile-render question and retained evidence
- studio-loop-2026-08-12 — Studio-loop de-risking experiment
A spike buys an answer and ships nothing; it is not a PRD. Its result remains here when later documents still cite it.