astrolabe/docs/IMPLEMENTATION-PLAN.md

# 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)                      |