Astrolabe — Incremental Implementation Plan

A spec-driven rebuild of Astrolabe on Syto's architecture. The authoritative behavioral contract is docs/spec/ (sections 00–10).

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/ — 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), 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 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). 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
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):

Chart Builder · 3B starter examples (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 §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 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/ — no external repo needed:

Need	Doc
Zustand stores, selector derivations, debounced auto-save	01 · State & Stores
IndexedDB wrapper, lazy loading, migrations, localStorage prefs, storage tiers	02 · Persistence
Modal registry + coordinator + shell, unsaved-change detection, focus trap	03 · Modal System
URL hash view-state, keyboard routing, interactive-context detection	04 · Routing & Events
vega-embed integration, theming, debounced preview, error display	05 · Rendering, Theming & Preview
Column type inference + dataset profiling	06 · Type Inference & Profiling
Unique names + import auto-suffix, snippet↔dataset links, rename propagation	07 · Naming & Relationships
Monaco setup, Vega-Lite schema service, editor patterns mined from vega/editor	08 · Vega Editor Techniques
Design language: tokens, type, spacing, color roles, components, themes	09 · Visual Design Language
Interaction & feedback: toasts, busy states, empty states, council resolutions	10 · Interaction & Feedback
Learning section `/learn/`: markdown lessons, before/after spec progressions	11 · Learning Section

9.7 KiB Raw Blame History Unescape Escape