# Astrolabe — Incremental Implementation Plan > A rebuild of Astrolabe on Syto's architecture. The behavioral record is > `docs/spec/` (sections 00–10) — the code leads, and the spec is kept > rewritten to match. > > **The M0–M6 build is complete** — the milestone map below is the record. Remaining > work is post-M6 enhancement, tracked in the **live backlog** and owned in detail by > the two scope docs it points to. Per-milestone build notes aren't kept here; the git > history and the spec/architecture docs hold them. > > **Method per milestone:** build core-first (portable, pure, tested) → wire UI → > cover with tests → manual smoke check against the spec's acceptance points. > "Test the Core, Trust the UI": high coverage on `src/core/`, lighter on components. --- ## Architectural ground rules These are decided and apply to all work. The **how** behind each is written up self-containedly in [`docs/architecture/`](architecture/00-overview.md) — read the matching doc before implementing. - **`src/core/` is portable** — no browser APIs, no React, no Monaco. Pure spec operations (detection, profiling, reference resolution, fit transforms, validation, import normalization). This is what we test hardest and what could power a future headless renderer/CLI. - **`src/app/`** holds React + Zustand UI. State lives in Zustand **stores** (`useAppStore`, plus per-feature stores); browser specifics live in **`src/app/infrastructure/`** adapters (IndexedDB, localStorage, URL hash) so the rest of the app never touches `window`/`indexedDB` directly. - **Modals via a registry + coordinator + shell** (see [Architecture 03](architecture/03-modal-system.md)), not ad-hoc conditional rendering. - **CSS Modules + design tokens** (`styles/tokens.css`); themes flip `[data-theme]`. Vega theme follows the UI theme. The design language behind the tokens — type, spacing, color roles, components, themes — is defined in [Architecture 09](architecture/09-visual-design.md) and established in M1.5. - **Editor: Monaco**, **self-hosted from npm + raw `monaco-editor` API** (not the CDN loader / `@monaco-editor/react` wrapper — decided; rationale in [Architecture 08](architecture/08-vega-editor-techniques.md#decision--monaco-integration-self-hosted-raw-api)). Workers are wired explicitly via Vite `?worker`. The Vega-Lite JSON-schema service is what gives autocomplete + validation; mine vega-editor for how it wires the schema. - **No shared library with Syto.** Patterns are copied/adapted, never imported. --- ## Milestone map The whole sequence is shipped. This table is the record; build notes for each live in the git history and the spec/architecture docs. | # | Milestone | Outcome | Spec | | -------- | -------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------- | | **M0** | Skeleton ✅ | Repo builds, tests run, empty shell renders | — | | **M1** | MVP core loop ✅ | Author a Vega-Lite snippet, see it render live, it persists | §02, §03A–C, §04, §09A | | **M1.5** | Visual design foundation ✅ | Apply the design language: tokens, IBM Plex, restyled M1 surfaces, chart theme | [arch 09](architecture/09-visual-design.md) | | **M2** | Editor robustness ✅ | Draft/Published, validation, schema autocomplete, fit modes | §03D–E, §04, §07(editor) | | **M3** | Datasets ✅ | Named reusable data + reference resolution in preview | §05, §03F, §09B | | **M4** | Chart Builder ✅ | No-JSON chart composition from a dataset | §06 | | **M4.5** | Snippet-library consolidation ✅ | Metadata panel (rename/comment/links), Duplicate | §02 | | **M5** | Settings + Import/Export ✅ | Preferences + workspace backup/transfer | §07, §08, §09C | | **M6** | Shell polish ✅ | Resize/toggle panes, routing, shortcuts, toasts, a11y, offline | §01, §10 | **MVP boundary = end of M1** (a genuinely usable single-user chart authoring loop). M1.5 made it _look right_; M2 made it _robust_; M3–M6 made it _complete_. --- ## Live backlog The M0–M6 sequence is done; what's left is post-M6 enhancement. The detail — rationale, citations, status logs — lives in the two scope docs below, which are the source of truth. This is the at-a-glance list; keep it in sync with them. **Next (flagged for build):** - **Multi-view data model** ([`multi-view-data-model-scope.md`](exploration/multi-view-data-model-scope.md)) — durable composition support across the data-facing features. **Complete** (M1–M5): the Vega-Lite-fidelity reference classifier (`core/spec-data`), the view-scoped editor data context, per-view data inspection, view-scoped Extract (inline + self-defined `datasets`), and live/interactive inspection. The durable contract is recorded in `docs/architecture` 05 (live inspection) and 07 (reference detection + extraction, §3.1–3.2). - **Chart Builder · 3B starter examples** ([`chart-builder-enhancement-scope.md`](exploration/chart-builder-enhancement-scope.md) §3) — a small set of curated starters, one per covered FT intent. Reshaped by 3C: a builder-openable starter must reference a dataset, so it ships paired sample datasets (or is reframed) — final shape decided at build time. Distinct from the inline-data onboarding gallery (`core/examples.ts` → `Onboarding.tsx`), which is Monaco-only. - **Chart theming · Color-panel swatch reorder** ([`chart-theming-scope.md`](exploration/chart-theming-scope.md) §5) — the last remaining slice-4b control: reorder a materialized scheme's swatches. **Deferred / gated (have a home; not committed):** - **Chart Builder · Phase 4** (gated until after Phase 3) — `theta`/pie, faceting (small multiples), light styling/scale override panels, builder undo/redo, dataset lookup/join. Each must clear the promotion test: a control enters the builder only when it is **both common and awkward in JSON**. - **Chart Builder** — field-chip drag-and-drop (click/keyboard-first shipped; drag deferred); calculated-field autocomplete popup (Monaco-style completion for expressions). - **Chart theming** — Google Fonts opt-in CDN tier (keyless catalog, opt-in only); theme↔font pairing metadata (a suggestion nicety); built-in expressive preset gallery ("Editorial", "Terminal", "Sketch"). --- ## Cross-cutting, do-as-you-go - **Build to the design language:** the foundation landed in M1.5; every new component uses the [Architecture 09](architecture/09-visual-design.md) tokens and conventions — no placeholder styling, no raw hues. Staying on it is the do-as-you-go part. - **i18n** (optional, deferred): if translation is wanted, split a portable i18n registry (no React) from the app-layer bindings, mirroring the `core` ↔ `app` boundary. The app ships English-only with date formatting locale-aware (§10). Keep user-facing strings centralized so a later retrofit stays cheap. - **Versioning:** simplified semver `0.x.y`, `package.json` → `__APP_VERSION__` (already wired). **Not yet released publicly** — the working version stays pre-1.0; the **first public release will be `1.0.0`**, cut on the maintainer's signal (don't auto-bump in the meantime). - **Docs trio:** keep `SOUL.md` / `AGENTS.md` / `CLAUDE.md` current as the app grows. --- ## Architecture reference The **how** behind each milestone is documented self-containedly in [`docs/architecture/`](architecture/00-overview.md) — no external repo needed: | Need | Doc | | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | | Zustand stores, selector derivations, debounced auto-save | [01 · State & Stores](architecture/01-state-and-stores.md) | | IndexedDB wrapper, lazy loading, migrations, localStorage prefs, storage tiers | [02 · Persistence](architecture/02-persistence.md) | | Modal registry + coordinator + shell, unsaved-change detection, focus trap | [03 · Modal System](architecture/03-modal-system.md) | | URL hash view-state, keyboard routing, interactive-context detection | [04 · Routing & Events](architecture/04-routing-and-events.md) | | vega-embed integration, theming, debounced preview, error display | [05 · Rendering, Theming & Preview](architecture/05-rendering-theming-preview.md) | | Column type inference + dataset profiling | [06 · Type Inference & Profiling](architecture/06-type-inference.md) | | Unique names + import auto-suffix, snippet↔dataset links, rename propagation | [07 · Naming & Relationships](architecture/07-naming-and-relationships.md) | | Monaco setup, Vega-Lite schema service, editor patterns mined from vega/editor | [08 · Vega Editor Techniques](architecture/08-vega-editor-techniques.md) | | Design language: tokens, type, spacing, color roles, components, themes | [09 · Visual Design Language](architecture/09-visual-design.md) | | Interaction & feedback: toasts, busy states, empty states, council resolutions | [10 · Interaction & Feedback](architecture/10-interaction-and-feedback.md) | | Learning section `/learn/`: markdown lessons, before/after spec progressions | [11 · Learning Section](architecture/11-learning-section.md) |