Skip to content

README.md

Latest commit

 

History

History
68 lines (57 loc) · 8.87 KB

README.md

File metadata and controls

68 lines (57 loc) · 8.87 KB
Raw

Chestnut Labs G-code Preview — Documentation

This directory holds the founding planning set (the controlling project plan) and the working records the governance process produces (Design Documents, ADRs, Research Records, compatibility evidence).

Founding planning set — read in this order

  1. 00_PROJECT_MASTER_PLAN.md — vision, scope, principles, roadmap, success measures, Epic map. Controls product direction.
  2. 01_GITHUB_WORKFLOW_PROJECT_GOVERNANCE_AND_DEVELOPMENT_PROCESS.md — authoritative process. Controls workflow; wins over other docs on process.
  3. 02_ARCHITECTURE_AND_PACKAGE_BOUNDARIES.md — system boundaries and dependency direction. Controls package boundaries until a DD/ADR changes them.
  4. 03_UPSTREAM_FORK_LICENSE_AND_CONTRIBUTION_POLICY.md — fork relationship, upstream adoption, MIT attribution, provenance.
  5. 04_GITHUB_BOOTSTRAP_EPICS_MILESTONES_AND_NEXT_STEPS.md — repository/GitHub bootstrap, Epics, milestones, labels, issue hierarchy.
  6. 05_ANYBRIDGE_HANDOFF.md — deferring the viewer out of AnyBridge #593/#581 without losing or duplicating work.

See also ../PROJECT_SETUP.md for the local environment and private-source (ProjectSource/) handling.

These documents do not authorize implementation, package publication, or AnyBridge integration. The first executable work is repository bootstrap and research/audit (E0). Each architecture-sensitive Epic must pass its Design Document gate before its first implementation issue begins.

Working records

Directory Artifact Naming
design/ Design Documents (DD) — approved implementation architecture for one Epic/boundary DD-NNN-<slug>.md
adr/ Architecture Decision Records — one durable decision and its consequences ADR-NNN-<slug>.md
research/ Research Records — reproducible evidence, comparison, or experiment RR-NNN-<slug>.md
compatibility/ Compatibility/support matrices with evidence and dates <topic>.md
reference/ Consumer-facing contract references and integration notes <topic>.md

Provenance of inherited vs. Chestnut code, the exact founding baseline, and the branch mapping are tracked in UPSTREAM_PROVENANCE.md.

Current state (updated 2026-07-25 — v0.2.0 published; E10 phase 1 shipped; E11 docs site live)

Epic Status Gate
E0 Fork Foundation & Upstream Audit (#1) Closed/Accepted RR-001 Accepted (baseline develop @ 15375e56)
E1 ToolpathIR & Package Contracts (#2) Closed/Accepted DD-001 + DD-002 Accepted
E2 Worker Parser & Large-File Pipeline (#3) Closed/Accepted DD-003 Accepted; all §8 benchmark targets met (report)
E3 Three.js Renderer & Viewer MVP (#4) Closed/Accepted (2026-07-22) DD-004 Accepted + benchmark-ratified (#61, report); orbit-fps budgets pending a reference-machine perfRun() (accepted deviation)
E4 Dialect & Container Compatibility (#5) Closed/Accepted (2026-07-23) DD-005 Accepted + benchmark-ratified incl. the container-threshold ratification; §7.3 security review signed off; matrix published (report)
E5 Live Progress Mapping (#6) Closed/Accepted (2026-07-23) DD-006 Accepted (D1–D5 as proposed, D3 clarified) with real AnyBridge telemetry evidence; all 5 phases merged (#90–#94); contract reference + consumer notes published; §8 budgets all PASS (report); GPU ghost-overdraw on the reference-machine list
E6 Vue Package & AnyBridge Consumer Integration (#7) Closed/Accepted (2026-07-23) DD-007 Accepted (D1 amended: first-class Vue/React/Svelte adapters over shared gcode-preview-core); all 8 phases merged; shared behavioral suite green ×3; consumer tarball fixture in CI; evidence + parity table; AnyBridge #783 cross-linked with the consumption recipe
E7 Release, Documentation & Ecosystem (#8) Closed/Accepted (2026-07-24) DD-008 Accepted with amendments; all seven phases merged. v0.1.0 published to npm — all nine @chestnutlabs/* packages (lockstep, provenance) from the v0.1.0 tag on main; both §15 gates met (framework parity ×3 + registry-mode verification); exit report. main promoted off the founding baseline
E9 Toolpath Annotations & Renderer Options (#162) Closed/Accepted (2026-07-24) DD-009 Accepted (D1–D7; D1 + D2 amended at implementation). All items shipped in v0.2.0: retraction markers (#148, D1), orthographic camera (#150, D3), M600 color-change (#147, D2 — parser-detected sparse colorChanges channel), bounded theming API (#153, D4), Custom Element @chestnutlabs/gcode-preview-element (#149, D5 — new 10th lockstep package). Multi-gcode = documented mount-multiple workaround (#151, D6). Epic #162 closed
E10 Motion-Model Correctness (#191) In progress — phase 1 shipped (2026-07-24) DD-010 Accepted (D1–D6; D1/D2 revised firmware-correct). Alters existing IR output → explicit golden-regen + capability-honesty (D5). Phase 1 shipped: M82/M83 extruder mode + G90/G91 positioning + G92 E-datum (#156; #155 mode half), firmware-conditioned via extruderFollowsPositioning, delta-based classification, new extrusionMode/positioningMode capabilities — corpus geometry byte-identical (7 absolute-E fixtures' extrusion corrected). Next: arc planes (#157), then coordinate systems (#158). Sibling DDs: .bgcode (#188→DD-011), CNC/laser (#189→DD-012)
E11 Documentation, SDK Reference & Published Manual (#197) Closed/Accepted (2026-07-25) DD-013 Accepted (D1–D7 as recommended). Completed E7/DD-008's docs ambit. All four phases shipped: typedoc API reference over the ten packages (#198), GitHub Pages + Chestnut Labs theme (#199), SDK manual — getting-started/guides/concepts (#200), accuracy gate + eslint-plugin-tsdoc + version stamp (#201). Live: chestnutlabs.github.io/gcode-preview (manual at /, API at /api/), auto-redeployed on merge/release. No package/IR/renderer change. Deferred: flip the notDocumented doc-coverage check to error once the 55 TSDoc-syntax gaps are filled
E8 Low-Resource Layer Mode (#9) Open, gated Needs its own DD + device-need evidence. Roadmap note (DD-008 §4.8): pure-Node GPU-less still rendering is the deferred E8-class capability if ever demanded (the v0.1.0 renderStill covers Chromium-class/Electron/OffscreenCanvas environments)
#152 STL export Open, gated Follows the #118 chrome/showcase product decision, not an architecture DD (DD-009 §3)

Shipped so far: packages/toolpath-core (SoA ToolpathIR, capability model), packages/gcode-parser (byte-exact port of the inherited engine, worker protocol v1, streaming, limits, adversarial corpus), packages/gcode-renderer-three (geometry builders + scene/lifecycle), the IR adapter (src/ir-adapter.ts), golden/native fixtures + manifest with CI validation, boundary lint, license CI gate, and Vite/Electron consumer smoke harnesses, plus the five framework adapters (gcode-preview-core/-vue/-react/ -svelte/-element). CI (build) is a required check on main/dev. All ten @chestnutlabs/* packages are published to npm at v0.2.0 (lockstep, npm provenance); main is the release branch, publishing from tagged GitHub Releases (v0.1.0 E7/DD-008, v0.2.0 E9/DD-009). An E10-phase-1 changeset accumulates on dev for the next release (0.3.0).