oleh/astrolabe
1
0
Fork 0
mirror of https://github.com/olehomelchenko/astrolabe.git synced 2026-08-08 02:02:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

Plan: mark M0–M6 complete, replace milestone detail with a post-M6 backlog

Browse Source
This commit is contained in:
Oleh Omelchenko
2026-06-26 23:15:55 +03:00
parent 43d3b480d9
commit fff7ae98f2
1 changed files with 58 additions and 479 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/IMPLEMENTATION-PLAN.md
+50 -471
View File
@@ -1,8 +1,12 @@
# Astrolabe — Incremental Implementation Plan # Astrolabe — Incremental Implementation Plan
> A spec-driven rebuild of Astrolabe on Syto's architecture. The authoritative > A spec-driven rebuild of Astrolabe on Syto's architecture. The authoritative
> behavioral contract is `docs/spec/` (sections 00–10). This document sequences > behavioral contract is `docs/spec/` (sections 00–10).
> the build into the **quickest path to a usable MVP**, then layers the rest. >
> **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 → > **Method per milestone:** build core-first (portable, pure, tested) → wire UI →
> cover with tests → manual smoke check against the spec's acceptance points. > cover with tests → manual smoke check against the spec's acceptance points.
@@ -12,7 +16,7 @@
## Architectural ground rules ## Architectural ground rules
These are decided and apply to every milestone. The **how** behind each is written up 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 self-containedly in [`docs/architecture/`](architecture/00-overview.md) — read the matching
doc before implementing. doc before implementing.
@@ -42,499 +46,73 @@ doc before implementing.
## Milestone map ## 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 | | # | Milestone | Outcome | Spec |
| -------- | --------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------- | | -------- | -------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------- |
| **M0** | Skeleton ✅ | Repo builds, tests run, empty shell renders | — | | **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** | 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) | | **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) | | **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 | | **M3** | Datasets ✅ | Named reusable data + reference resolution in preview | §05, §03F, §09B |
| **M4** | Chart Builder ✅ | No-JSON chart composition from a dataset | §06 | | **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 | | **M5** | Settings + Import/Export ✅ | Preferences + workspace backup/transfer | §07, §08, §09C |
| **M6** | Shell polish ✅ | Resize/toggle panes, routing, shortcuts, toasts, a11y, offline | §01, §10 | | **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). **MVP boundary = end of M1** (a genuinely usable single-user chart authoring loop).
M1.5 makes it _look right_; M2 makes it _robust_; M3–M6 make it _complete_. M1.5 made it _look right_; M2 made it _robust_; M3–M6 made it _complete_.
Ship/dogfood after M1, iterate.
--- ---
## M0 · Skeleton ✅ (done) ## Live backlog
Vite + React + Zustand + TypeScript + Vitest (happy-dom) + vite-plugin-pwa. The M0–M6 sequence is done; what's left is post-M6 enhancement. The detail — rationale,
`src/core` ↔ `src/app` split, `useAppStore`, design tokens, three-pane placeholder citations, status logs — lives in the two scope docs below, which are the source of truth.
shell, first core module (`format-detection`) with tests. This is the at-a-glance list; keep it in sync with them.
**Verified:** `npm run typecheck`, `npm test`, `npm run build` (PWA SW generated). **Next (flagged for build):**
--- - **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
## M1 · MVP core loop → _the quickest usable Astrolabe_ 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
**Goal:** select/create a snippet, edit its spec JSON, watch a live Vega-Lite gallery (`core/examples.ts` → `Onboarding.tsx`), which is Monaco-only.
preview, and have it survive reload. Single source kind: inline-data specs only - **Chart theming · Color-panel swatch reorder** ([`chart-theming-scope.md`](exploration/chart-theming-scope.md) §5) —
(datasets come in M3). No draft/published yet — edits save directly. the last remaining slice-4b control: reorder a materialized scheme's swatches.
**Core (`src/core/`)** **Deferred / gated (have a home; not committed):**
- `snippet.ts` — the Snippet type (spec §09A) + factory (`createSnippet`, - **Chart Builder · Phase 4** (gated until after Phase 3) — `theta`/pie, faceting (small
default sample bar-chart template, auto-generated date/time name). multiples), light styling/scale override panels, builder undo/redo, dataset lookup/join. Each
- `rendering.ts` — `prepareSpecForRender(spec, { fitMode })` skeleton; in M1 it's must clear the promotion test: a control enters the builder only when it is **both common and
near pass-through (reference resolution is a no-op until M3, fit-mode is M2). awkward in JSON**.
Establish the "transform a copy, never mutate stored spec" contract now. - **Chart Builder** — field-chip drag-and-drop (click/keyboard-first shipped; drag deferred);
calculated-field autocomplete popup (Monaco-style completion for expressions).
**Infrastructure (`src/app/infrastructure/`)** - **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",
- `idb.ts` — thin IndexedDB wrapper (open, get/put/delete/getAll by store). "Terminal", "Sketch").
_(see [Architecture 02 · Persistence](architecture/02-persistence.md))_
- `snippet-store.ts` — persist snippets (object store `snippets`).
**App**
- `stores/SnippetStore.ts` — `useSnippetStore` with `snippets`, `activeSnippetId`,
selector-derived `activeSnippet`; load-on-startup; create/select/delete/update actions
(debounced auto-save of edits, spec §03B). Seed one sample snippet on first run.
_(Superseded later: an empty library now shows the onboarding canvas instead of a
placeholder seed — spec §02 → First-Run & Empty Workspace.)_
- `components/SnippetLibrary.tsx` — list + "Create New" pinned item + select/delete.
- `components/SpecEditor.tsx` — Monaco JSON editor bound to active snippet's spec;
debounced write-back to the store. (Worker wiring via Vite `?worker` imports —
mine vega-editor's Monaco setup.)
- `components/LivePreview.tsx` — render current spec via `vega-embed` (actions:
false), debounced; clean empty pane when no/blank spec; basic error text.
- Fill the three panes in `App.tsx` with these.
**Tests (core-first)**
- `snippet.test.ts` — factory defaults, sample template validity, unique naming.
- `rendering.test.ts` — copy-not-mutate invariant; pass-through shape.
- A store test for create/select/delete/auto-save reducer logic (logic extracted
from the component so it's testable without DOM).
**Manual checks**
- Fresh load shows the onboarding canvas (welcome + Create + live example gallery);
Create or an example's Add lands you in the editor with a rendered chart. _(M1 originally
seeded a sample snippet; replaced by the onboarding canvas — spec §02.)_
- Type in the editor → preview updates after the debounce; bad JSON → editor keeps
working, preview shows an error, recovers when fixed.
- Reload → snippets and selection persist.
---
## M1.5 · Visual design foundation ✅ (done) → _make the MVP look like itself_
**Goal:** apply our design language so the running MVP looks deliberate, and every
later milestone builds on settled tokens instead of placeholders. The expensive part
(the design decisions) is already done — this milestone is _application_, not
invention. See [Architecture 09 · Visual Design Language](architecture/09-visual-design.md)
and the companion `visual-specimen.html`.
**Styles**
- Port the settled specimen tokens into `styles/tokens.css` (IBM-Plex type scale,
8px-based spacing, role-based color, square chrome, motion); light + dark themes
via `[data-theme]`.
- Self-host **IBM Plex Sans + Mono** in `styles/base.css` via `@fontsource`
(offline/PWA — never a CDN).
**App**
- Restyle the four M1 surfaces against the tokens: App shell, SnippetLibrary,
SpecEditor (Monaco theme follows `[data-theme]`), LivePreview. Tokens only — no
raw hexes, no hardcoded hues in components.
- Establish the reusable component conventions (buttons, fields, list rows, status,
focus ring) that M2–M6 reuse.
- **Header theme toggle** (pulled forward from M5): a one-click light⇄dark control,
persisted via the `ui.theme` settings key (a minimal forward-compatible
`settings-store` adapter the full M5 UserSettings store will absorb). Hydrated
before first paint (no FOUC). Justified: the theme system was already complete,
so dogfooding dark mode through M2–M4 beat waiting for the full settings UI.
**Core**
- Align `src/core/vega-themes.ts`: chart `Config` per theme + a categorical
`range.category` palette (clone `carbon-design-system/carbon-charts` for the
sequence — see Architecture 09 §8).
**Tests**
- Light: the design is mostly visual — a token/theme smoke check, trust the eye.
**Manual checks**
- The real app looks deliberate in both themes; theme flip repaints UI + chart.
- Keyboard focus ring visible; text/UI contrast passes AA in light and dark.
- No placeholder styling remains on the M1 surfaces.
**Verified:** `typecheck` + `test` (incl. `vega-themes.test.ts`) +
`build` (Plex woff2, all script subsets, bundled & precached via the PWA
`globPatterns`). Both themes screenshotted via the real
app (chrome + Monaco + chart all repaint on theme flip); focus ring visible.
Notes from the build-out: the placeholder `'experimental'` theme was renamed to
`'dark'` (the settled name); the swappable `[data-accent]` layer landed with
deep teal as the robust default (no switcher UI until M5); Monaco's `fontFamily` is
set to Plex Mono explicitly since it can't read the CSS token.
---
## M2 · Editor robustness ✅ (done)
**Goal:** the editor becomes trustworthy — draft vs published, schema-aware
assistance, and the fit-mode rendering contract.
**Core**
- `rendering.ts` — implement **fit-mode** transform (Original/Width/Height/Full →
Vega-Lite `"container"`), recursing into layered/concat/child specs (spec §04
Rendering Contract, step 2).
- `vega-lite-schema.ts` — provide the Vega-Lite JSON schema for Monaco's
validation/autocomplete. _Delivered early in M1.5 as
`infrastructure/monaco-schema.ts` (bundled schema, offline, `markdownDescription`
hover docs); no further work needed in M2._
**App**
- Snippet gains `spec` (published) + `draftSpec` (working) per §09A; editing
touches `draftSpec` only.
- `SpecEditor` header: Draft/Published toggle; **Publish** (promotes draft, recomputes
dataset refs — refs land in M3) + **Revert** (confirm dialog).
- Library list item: draft-vs-published **status indicator**.
- Monaco wired with the Vega-Lite schema → squiggles + autocomplete; inline error
surface in the editor pane (§03E).
- Preview **Fit control** (4 modes), persisted (`previewFitMode`).
**Tests**
- Fit-mode transforms for each mode incl. nested specs; copy-not-mutate.
- Draft/publish/revert reducer logic; "has unpublished changes" derivation.
**Manual checks**
- Edit draft, see status flip to "draft"; Publish → status clears; Revert →
draft restored with confirmation.
- Invalid spec shows inline error; autocomplete suggests Vega-Lite properties.
- Each fit mode resizes the chart as specified; choice survives reload.
**Verified:** `typecheck` + `test` (`rendering` fit-mode incl.
nested layer/concat/facet specs, `SnippetStore` draft/publish/revert/editorView,
`settings-store` `previewFitMode` round-trip) + `build` (PWA, 41 precache
entries) + `eslint` clean. Implementation notes: editing now writes the
**draft** only (`commitDraft` no longer touches `spec`); `publish`/`revert` live
in `SnippetStore`, with a `bufferEpoch` counter so programmatic buffer reloads
(select/create/revert) refresh Monaco without fighting the cursor mid-typing.
The Draft/Published view is a store-level `editorView`; the published view is
read-only and the preview renders whichever version is shown (`selectShownText`).
The editor (§03E) and preview (§04) share one render error via a small
`PreviewStore`. `previewFitMode` was pulled into `AppStore` + the settings
adapter, hydrated/persisted by a new `orchestration/preferences.ts` mirroring the
theme slice. Publish/Revert **success toasts** stay deferred to M6 (TODO
breadcrumbs at the call sites), matching the existing delete-toast convention.
Fit-mode rendering needed a layout fix: vega-embed brands the embed host with its
own `.vega-embed { display: inline-block }` (injected at runtime, wins the
cascade), which shrink-wrapped the host so `width: "container"` collapsed (Height
survived only via the old `min-height: 100%`). Fix: embed into a static-class
inner host (React never reconciles its className, so Vega's runtime classes
survive) inside a React-owned frame that carries the fit-sizing class via
two-class selectors that out-specify `.vega-embed`. All four fit modes
user-verified in the running app.
---
## M3 · Datasets ✅ (done)
**Goal:** named, reusable data that snippets reference by name; preview resolves
the reference.
**Core**
- `profiling.ts` — row/column counts, column names, **per-column type inference**
(number/text/date/boolean). _(see [Architecture 06 · Type Inference](architecture/06-type-inference.md))_
- `rendering.ts` — implement **dataset reference resolution** (§04 Rendering
Contract, step 1): `{data:{name}}` → inline values / raw text+format / URL+format,
recursing into sub-specs; "dataset not found" error.
- `dataset.ts` — Dataset type (§09B); name uniqueness helpers; rename-propagation
into referencing specs. _(see [Architecture 07 · Naming & Relationships](architecture/07-naming-and-relationships.md))_
**Infrastructure**
- `dataset-store.ts` — separate high-capacity IndexedDB store (§09E).
**App**
- `stores/DatasetStore.ts` + Datasets **modal** (list/detail panes, create form,
edit, delete, copy-reference) via the modal registry/coordinator.
- Snippet `datasetRefs` maintained on publish; library shows dataset icon +
Linked Datasets; dataset detail shows Linked Snippets (bidirectional name link, §09F).
- **Extract-to-Dataset** flow from the editor (§03F).
- URL datasets fetched once on add and **snapshotted** locally (profiled like inline;
render from the snapshot, refreshable on demand — see §05 / §04 rendering contract).
**Tests**
- Reference resolution per source/format incl. nested; not-found error.
- Profiling/type inference across mixed columns, nulls, booleans.
- Rename propagation; name-uniqueness + import-style auto-suffix.
**Manual checks**
- Create a dataset, reference it by name in a snippet → preview renders.
- Extract inline data → spec rewritten to a reference, dataset appears, links show both ways.
- Delete/rename a referenced dataset behaves per spec.
---
## M4 · Chart Builder ✅ (done)
**Goal:** no-JSON chart composition from a dataset → a new snippet.
> **Enhancement push (post-M4).** The forward plan now lives in
> [`docs/exploration/chart-builder-enhancement-scope.md`](exploration/chart-builder-enhancement-scope.md) — it merges
> the Tier-B backlog ([`chart-builder-research.md`](exploration/chart-builder-research.md) §8) with the
> Lyra interaction review ([`lyra-review.md`](exploration/lyra-review.md)) and sets a **Tier-C** target.
> Shipped beyond the Tier-B floor so far: per-channel aggregate/bin/`timeUnit`, sort/stack;
> **actionable hints** (one-click warning fixes); and a builder UX/perf batch (near-fullscreen
> modal, canvas preview + canvas max-dimension guard, data-aware default pre-population). See
> the scope doc §4 for the sequenced plan and current status.
**Core**
- `chart-builder.ts` — pure spec assembler: (mark ∈ Bar/Line/Point/Area/Circle) +
channels (X/Y/Color/Size) with field types (Quantitative/Nominal/Ordinal/Temporal)
- optional width/height → complete Vega-Lite spec with tooltips + named data ref
(§06 Output). Field-type defaults from inferred column type.
**App**
- Chart Builder **modal** (config pane + live preview pane), launched from a
selected dataset; default pre-population (first col→X, second→Y); validation
(≥1 channel); Create Snippet → new linked snippet becomes active.
**Tests**
- Spec assembly: mark/channel/type permutations, unmapped channels omitted,
width/height inclusion, field-type derivation, validation gate.
**Manual checks**
- Build a bar chart from a dataset in a few clicks; preview live-updates;
Create → new snippet opens and renders.
**Council** — **FT Visual Vocabulary** + **Datawrapper** are now **seated** (chart-choice
canon): this is where Astrolabe stops being a pass-through JSON editor and starts making
chart-shaped suggestions/defaults, so "_which chart, and why_" becomes a decision the app
owns — the one thing Carbon's data-viz styling doesn't cover. Rather than a styling-only
seating, we ran a full **research-first** pass (FT + Datawrapper + the formal engines
**Draco** and **Voyager**), recorded in [`docs/exploration/chart-builder-research.md`](exploration/chart-builder-research.md),
and chose the **Tier B "smart + guarded"** design: smart default mark for the data shape,
valid-type-locked field-type menus, Size-channel discipline, and non-blocking guidance.
The convergent rules and citations live in that doc; the spec (§06) was amended to match.
**Verified:** `typecheck` + `test` green — the pure `chart-builder.ts` assembler
(`chart-builder.test.ts`: mark/channel/type permutations, unmapped-channel omission,
validation gate). The Chart Builder modal is wired through the registry, launched from a
selected dataset (`DatasetsModal` → `openModal('chartBuilder')`). Data-aware
cardinality/extent profiling + chart warnings landed (A3/A4).
---
## M4.5 · Snippet-library consolidation ✅ (done)
**Why out of band:** a spec-vs-implementation audit after M4 found §02 features that no
later milestone owned — the **Selected-Snippet Metadata Panel** (inline name + comment
editing, timestamps, linked datasets) and the **Duplicate** operation. Without them a
snippet could only ever carry its auto-generated date-time name (no rename, no annotation,
no copy), a sharp edge for a _snippet manager_. Closed before M5 since the spec text
already existed and the work was core-first and cheap.
**Core**
- `snippet.ts` — `duplicateSnippet(source, {now,id})`: independent copy carrying both spec
versions, comment, tags, and dataset refs; "(copy)" name; fresh identity/timestamps;
cloned mutable members.
**App**
- `SnippetStore` — `renameSnippet`, `setComment` (both advance `modified` per §02 → Sort,
no editor-buffer touch), `duplicateActiveSnippet` (flushes the live buffer first, prepends
the copy, makes it active).
- `SnippetLibrary` — the metadata panel below the list: Name + Comment auto-save (debounced
while typing, flushed on blur), read-only Created/Modified, Linked Datasets list, and
Duplicate / Delete. Duplicate raises a success toast (the copy isn't self-evident, unlike
Create); §02-compliant.
**Also fixed (§03C divergence):** the preview debounced _every_ change, so a snippet
load / Draft↔Published switch incurred a 300 ms blank instead of the spec's **immediate**
render. `LivePreview` now renders immediately on `bufferEpoch`/`editorView` change and
debounces only keystroke (`shownText`-only) changes.
**Deferred at the time to M5/M6 (per §02):** Search, Sort controls + persistence, two
distinct empty-state messages, Storage Monitor — all now delivered in M6.
**Verified:** `typecheck` + `test` (`snippet` duplicate factory,
`SnippetStore` rename/comment/duplicate, a `SnippetLibrary` render test guarding the
auto-save effect against a render loop) + `eslint` clean + `build` (PWA, 41 precache
entries).
---
## M5 · Settings + Import/Export ✅ (done)
**Goal:** preferences and whole-workspace backup/transfer.
**Core**
- `settings.ts` — UserSettings shape + defaults + load-with-fallback (§07, §09C);
unknown/missing values fall back silently.
- `import-normalize.ts` — accept envelope / bare array / single snippet / foreign
shapes; field mapping (`content`→spec, `draft`→draftSpec, `createdAt`→created);
tag `"imported"`; merge rules (append, id-collision reassign, dataset-name
auto-suffix, datasets-before-snippets) (§08).
- `export-envelope.ts` — build the `{version, exportedAt, exportedBy, snippets, datasets}` envelope.
**Infrastructure**
- `settings-store.ts` (localStorage): **extend** the minimal M1.5 adapter (which
already persists `ui.theme`) to the full UserSettings record; `ux-prefs` for sort
- panel layout (§09D).
**App**
- **Distributed settings** — not a modal (design review, see spec §07 + arch 10). Each
cluster is a per-pane disclosure popover that applies **live**: Editor settings in the
editor toolbar, render debounce in the preview, date format in the library; theme stays
the header toggle. A shared `SettingsPopover` primitive (gear + non-modal popover, APG
disclosure) backs all three. Wire render-debounce + editor options + date-format through.
- Header **Import**/**Export** (direct file dialog / download, no modal).
- Date formatting util (smart/iso/custom) used by the library list + metadata panel.
**Tests**
- Import normalization across all accepted shapes; merge/collision/rename logic;
quota-overage messaging path. Envelope round-trip (export→import idempotence).
- Settings load-with-fallback for partial/unknown records.
**Manual checks**
- Change theme/debounce/date-format → takes effect; Cancel reverts; Reset confirms.
- Export → reimport into a populated workspace merges without overwrite; renames reported.
**Verified:** `typecheck` + `test` green — `import-normalize` (accepted shapes + merge/
collision/rename), `export-envelope` (round-trip), `settings` (load-with-fallback),
`UserSettingsStore`, `ux-prefs`. Distributed per-pane settings shipped as `SettingsPopover`
disclosures (editor toolbar, preview, library) applying live; header Import/Export wired
through `services/transfer.ts` (→ `normalizeImport` / envelope build), no modal.
---
## M6 · Shell polish & non-functional ✅ (done)
**Goal:** the workspace feels finished and meets §10.
**Scope note — desktop/tablet, not phone.** Astrolabe is a desktop and (at best)
tablet tool; phones are out of scope. So the touch/installable surface we target is
**iPad add-to-home-screen**, not iPhone — which is why the one PNG icon is a 180×180
`apple-touch-icon` and we don't chase phone-specific viewport/layout work.
- **Panes:** ~~drag-resize handles with min widths; widths persist~~ ✅ (pulled
forward after M2). ~~Per-pane show/hide **toggle strip** + visibility persist +
proportional redistribution on hide (§01A, §09D)~~ ✅.
- **Routing:** ~~URL hash view-state (`#snippet-<id>`, `#datasets/...`) with Back/Forward;
restore on load (§01E)~~ ✅.
- **Shortcuts:** ~~Cmd/Ctrl+Shift+N / +K / +S / +, / Esc via a single key router
(§01D)~~ ✅.
- **Toasts:** ~~success/error/warning/info, stacking, auto-dismiss, reduced-motion;
appear/disappear with a brief fade (§01F)~~ ✅ (fade-out two-phase dismiss landed last).
- **Library search / sort / empty states** (§02, §09D): ~~live search across
name/comment/draft spec; Sort by Modified/Created/Name/Size with a disclosure +
flip-on-reselect, persisted to `astrolabe:ux-prefs`; the two distinct empty states~~ ✅
(council-guided — see [arch 10](architecture/10-interaction-and-feedback.md)).
- **Storage monitor** for the snippet tier ~~(§02)~~ ✅ (`role="meter"` fill bar,
escalating ok/warning/critical at 0.8/0.95).
- **Live-preview busy indicator** (§04, §10): ~~non-blocking overlay + `aria-busy` for
renders past ~1s~~ ✅.
- **Import atomicity** (§08): ~~roll back on storage-quota failure so no partial import is
committed; actionable error~~ ✅ (effective at the service boundary; true cross-record
IDB-transaction atomicity would require exposing a raw transaction from `db.ts` — see
[arch 02](architecture/02-persistence.md)).
- **A11y:** modal focus trap + return, labelled icon buttons, contrast in both themes (§10) — ✅ in place.
- **About** and **Support** modals ~~(§01)~~ ✅. The project solicits nothing for
itself — **Support** offers feedback to the author and redirects donations to Ukraine's
defense (`savelife.in.ua`, the Come Back Alive foundation), where the author forwards any
project donations anyway.
- **Offline/installable:** the manifest ships a full SVG icon set (favicon / maskable /
monochrome) + a 180×180 `apple-touch-icon.png` (iPad add-to-home-screen) + `theme_color`,
and the SW precaches the shell — the app is **installable**. ✅ Manual verification in a
running/installed app passed (checklist: [manual-verification.md](manual-verification.md)).
- **Council** — ~~seat **web.dev** for the PWA/offline/storage surfaces none of the seated
members cover: the service-worker **update-available** prompt (`registerType: 'prompt'`),
storage **persistence** (`navigator.storage.persist()`), and the quota **estimate**
(`StorageManager.estimate()`)~~ ✅ seated + backfilled (update-prompt toast + `persist()`
request; estimate already wired). ~~**⏳ Remaining gap:** manifest ships no icons → not yet
installable~~ ✅ SVG icon set added + wired (favicon / maskable / monochrome). See
[`/council`](../.claude/skills/council/SKILL.md) and
[arch 10](architecture/10-interaction-and-feedback.md).
**Manual checks:** ✅ keyboard-only run-through; reload restores view from URL;
offline reload works; install as standalone; reduced-motion honored — all verified in a
running/installed app, plus visual verification of the library/monitor/modals/busy-indicator
surfaces.
--- ---
## Cross-cutting, do-as-you-go ## Cross-cutting, do-as-you-go
- **Build to the design language:** the foundation lands in M1.5; from M2 on, every - **Build to the design language:** the foundation landed in M1.5; every new component uses the
new component uses the [Architecture 09](architecture/09-visual-design.md) tokens [Architecture 09](architecture/09-visual-design.md) tokens and conventions — no placeholder
and conventions — no placeholder styling, no raw hues. Staying on it is the styling, no raw hues. Staying on it is the do-as-you-go part.
do-as-you-go part.
- **i18n** (optional, deferred): if translation is wanted, split a portable i18n - **i18n** (optional, deferred): if translation is wanted, split a portable i18n
registry (no React) from the app-layer bindings, mirroring the `core` ↔ `app` registry (no React) from the app-layer bindings, mirroring the `core` ↔ `app`
boundary. M1–M6 can ship English-only with date formatting locale-aware (§10). boundary. The app ships English-only with date formatting locale-aware (§10).
Don't retrofit later if avoidable — keep user-facing strings centralized from M1. Keep user-facing strings centralized so a later retrofit stays cheap.
- **Versioning:** simplified semver `0.x.y`, `package.json` → `__APP_VERSION__` - **Versioning:** simplified semver `0.x.y`, `package.json` → `__APP_VERSION__`
(already wired). **Not yet released publicly** — the working version stays pre-1.0 through (already wired). **Not yet released publicly** — the working version stays pre-1.0; the
M0–M6; the **first public release will be `1.0.0`**, cut on the maintainer's signal (don't **first public release will be `1.0.0`**, cut on the maintainer's signal (don't auto-bump in
auto-bump in the meantime). the meantime).
- **Docs trio:** keep `SOUL.md` / `AGENTS.md` / `CLAUDE.md` current as the app grows. - **Docs trio:** keep `SOUL.md` / `AGENTS.md` / `CLAUDE.md` current as the app grows.
--- ---
## Open items (carried from the exploration memos)
Deferred features whose reasoning lives in `docs/exploration/`; pulled here so the backlog
is in the maintained plan, not the archive.
**Chart theming** (`exploration/chart-theming-scope.md`):
- **Google Fonts opt-in CDN tier** — keyless catalog, opt-in only.
- **Theme↔font pairing metadata** — a suggestion nicety.
- **Built-in expressive theme preset gallery** — e.g. "Editorial", "Terminal", "Sketch".
- **Color panel swatch reorder** — the remaining slice-4b control (reorder a materialized
scheme's swatches).
**Chart Builder** (`exploration/chart-builder-enhancement-scope.md`):
- ~~**Open-in-builder (3C, strict hydration)**~~ ✅ shipped (2026-06-18): an editor-toolbar
**Open in builder** action reopens a builder-representable snippet to **edit it in place**
(`parseChartSpec` is the strict inverse of `buildChartSpec`, gated by re-assemble +
deep-compare). Only dataset-referencing specs hydrate (the builder's data model). See the
scope doc status log.
- **Builder starter examples (3B)** — a small set of curated starters, one per covered FT
intent, **authored in the builder dialect so they reopen via 3C**. Reshaped by 3C's
data-model edge: a builder-openable starter must reference a dataset, so 3B ships paired
sample datasets (or is reframed) — decide its shape now that the gate is live. Distinct from
the shipped onboarding gallery (`core/examples.ts` → `Onboarding.tsx`), which seeds an
inline-data snippet straight into the editor (Monaco-only, never the builder).
- ~~**Transform-aware data inspector** — show resolved post-transform rows~~ ✅ shipped: an
Input | Resolved data inspector below the Live Preview and Chart Builder charts, with a
draggable height divider (spec §04; arch 05 → "data inspector rides the boundary").
- **Field-chip drag-and-drop** — click/keyboard-first shipped; drag deferred.
- **Calculated-field autocomplete popup** — Monaco-style completion for expressions.
---
## Architecture reference ## Architecture reference
The **how** behind each milestone is documented self-containedly in The **how** behind each milestone is documented self-containedly in
@@ -551,3 +129,4 @@ The **how** behind each milestone is documented self-containedly in
| Unique names + import auto-suffix, snippet↔dataset links, rename propagation | [07 · Naming & Relationships](architecture/07-naming-and-relationships.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) | | 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) | | 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) |