From 887de7412ec6d1b9bc18da70c99cbcab3e183b14 Mon Sep 17 00:00:00 2001 From: Oleh Omelchenko Date: Fri, 12 Jun 2026 18:16:34 +0300 Subject: [PATCH] Docs: new-entity persistence stack, modal size tiers, spec anchor stability, test harness notes --- AGENTS.md | 6 ++++++ docs/architecture/03-modal-system.md | 14 +++++++++----- docs/spec/README.md | 1 + 3 files changed, 16 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ac2053f..49f4743 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -131,3 +131,9 @@ source of truth is `version` in `package.json`, injected as `__APP_VERSION__`. High coverage on `src/core/` (parsing, detection, profiling, reference resolution, fit transforms, import normalization). Lighter on components. Extract testable logic out of components into core/stores where practical. + +Component tests (happy-dom) share a harness shape: `createRoot` + `act` with +`IS_REACT_ACT_ENVIRONMENT = true` set at module level, stores reset in `beforeEach`, and +`vi.mock('../services/chart-renderer', …)` for anything that embeds a chart (vega-embed is +integration-heavy; a resolved no-op handle suffices) — see any `components/*.test.tsx`. +Infrastructure tests that touch IndexedDB run against `fake-indexeddb`. diff --git a/docs/architecture/03-modal-system.md b/docs/architecture/03-modal-system.md index cfdbf0f..6a4e81b 100644 --- a/docs/architecture/03-modal-system.md +++ b/docs/architecture/03-modal-system.md @@ -610,12 +610,16 @@ share the open/close/snapshot/URL logic rather than reimplementing it. 1. Add the name to the `ModalName` union. 2. Add one `MODAL_REGISTRY` entry (title, component; `getState`/`hasError`/ - `getError` if it edits; `isUrlNavigable` + `init(arg)` if navigable). + `getError` if it edits; `isUrlNavigable` + `init(arg)` if navigable; + `dismissOnBackdrop: false` if it holds in-progress work). 3. Write the body component; it reads/writes its feature store (e.g. `useDatasetStore`, `useChartBuilderStore`) via a narrow selector. -4. If navigable, add its hash form to the URL sync and restore logic. -5. If it has a keyboard shortcut or workflow trigger, wire that to +4. If it isn't a small form, add its name to the **size-tier mapping in + `ModalShell`** (`isLarge`/`isXLarge`) — the one shell edit a new modal can + need; without it the modal renders at the small-form size. +5. If navigable, add its hash form to the URL sync and restore logic. +6. If it has a keyboard shortcut or workflow trigger, wire that to `openModal(name, arg)` — never to `activeModal` directly. -No edits to the shell render, the close logic, or the change-detection code are -needed: those are generic and driven entirely by the registry. +The shell render, close logic, and change detection need no edits: those are +generic and driven entirely by the registry. diff --git a/docs/spec/README.md b/docs/spec/README.md index efcceee..5ec08de 100644 --- a/docs/spec/README.md +++ b/docs/spec/README.md @@ -7,6 +7,7 @@ A UX/behavioral specification of **Astrolabe**, a browser-based snippet manager - Start with [00 · Product Overview](00-product-overview.md) for orientation and the glossary. - Each subsequent file is one feature area and can be read on its own; they cross-reference each other by title. - Every section describes intended behavior plus testable acceptance points ("The user can…", "When X, the system…"). +- Section numbers and lettered headings (e.g. `§03G`, `§09B`) are **stable anchors** — code comments reference them. Extend by appending the next letter/number; never renumber existing ones. ## What this spec deliberately omits