@lavalogic/scoria 0.40.0 → 0.40.2

package/dist/Components/Table/ARCHITECTURE.md

@@ -1,298 +1,298 @@
-# `<Table>` architecture
-
-Orientation for a new developer opening `src/lib/Components/Table/`. Read this once before changing anything substantive in this subtree. Read it again before reviewing a PR.
-
-For the cross-cutting story of how the current shape came to be, see
-`agent-review/dev-changelog.md` at repo root. For the consumer-facing
-public API, see the Storybook stories under `Table/Table API` and
-`src/stories/Table/*`.
-
----
-
-## What ships out of the front door
-
-Everything in the public surface is re-exported from
-`src/lib/index.ts`. The Table-side of that file is small on purpose:
-
-```ts
-import {
-	createTable,
-	localRows,
-	remoteRows,
-	customRows,
-	Table,
-	type CreateTableOptions,
-	type DisplayModalProps,
-	// …per-kind option types: TextColumnOptions, NumberColumnOptions, …
-} from '@lavalogic/scoria';
-```
-
-Three entry points cover every legitimate use:
-
-1. `createTable<TRow, IdType>({...})` builds a structured `Table`
-   instance. The returned value carries the typed sub-APIs (`selection`,
-   `filtering`, `sorting`, `clipboard`, `columns`, `pagination`,
-   `preferences`, `focus`, `modal`).
-2. `<Table {table} />` mounts the instance.
-3. The column builder closure passed under `columns:` is given a
-   `ColumnFactory<TRow>` parameter; consumers reach for the matching
-   `col.text(...)`, `col.number(...)`, `col.select(...)` and so on.
-
-The Def classes (`TextInputDef`, `DisplayDef`, …) are NOT exported. They
-are constructed inside `ColumnFactory.svelte.ts` and never appear on a
-consumer's import surface. If you need to alter Def behaviour, do it
-through the factory.
-
----
-
-## Folder tour
-
-```
-Table/
-├── Table.svelte                       — top-level component (mounts the grid + chrome)
-├── createTable.svelte.ts              — the consumer-facing entry; builds the TableContext + public Table instance
-├── ColumnFactory.svelte.ts            — closure-based column builder; wraps each Def
-├── ColumnKindRegistry.ts              — kind→category map used by setupDefaultColumnDefs
-├── ColumnKindRegistry.test.ts         — registry contract tests
-├── SubApis.svelte.ts                  — facade constructors for each typed sub-API on the public Table instance
-├── NestedTable.svelte                 — internal Expand-column body
-├── TableHelpers.svelte.ts             — co-located helpers (column-id mint, etc.)
-├── clipboardEscape.ts                 — escapeForSpreadsheet / encapsulate
-│
-├── Body/                              — body-grid layer
-│   ├── TableBody.svelte
-│   ├── QuickSearchCell.svelte         — filter row inputs
-│   └── Rows/Columns/                  — per-kind cell components
-│
-├── Headers/                           — header-row layer
-│   └── TableHead.svelte               — column headers, sort buttons, resize handles
-│
-├── Misc/                              — toolbars, side-panels, footer, filter panels
-│   ├── TableFooter.svelte
-│   ├── TableSidebar.svelte
-│   ├── TableHorizontalBar.svelte
-│   ├── FilterPanel.svelte
-│   ├── FilterInput.svelte             — advanced-filter panel inputs
-│   ├── ColumnPanel.svelte             — column visibility & order panel
-│   └── ToolboxPanel.svelte            — extra tool buttons
-│
-└── Types/                             — all type declarations + state classes
-    ├── Public/                        — every consumer-facing type
-    ├── Context/                       — TableContext (god) + the Phase 6 sub-contexts
-    ├── Columns/                       — Def classes (internal) + Column shape types
-    ├── DataRepository/                — TableDataRepository abstract + BuiltInRemoteRepository
-    ├── Filtering/                     — FilterFn, ColumnFiltersState, FilterMode enums
-    ├── Pagination/                    — PaginationState, PaginationType enum
-    ├── Focus/                         — focus-coordinate helpers
-    ├── Coordinates/                   — CellCoordinates, ColumnIndices brands
-    ├── Layout/                        — layout-related helpers
-    └── Toolbar/                       — ToolbarPosition enum
-```
-
----
-
-## The state graph
-
-`TableContext` is the root state object. It owns the data repo and seven
-sub-contexts:
-
-| Sub-context       | Owns                                                                      |
-| ----------------- | ------------------------------------------------------------------------- |
-| `_sorting`        | Sort comparators + the `sortedData` derived chain                         |
-| `_filtering`      | Filter-fn relays + the `filteredData` derived chain + quick-filter toggle |
-| `_columnLayout`   | Column widths / pinning / visibility / id-index maps                      |
-| `_selection`      | Selected & highlighted maps, key cache, page-wide select helpers          |
-| `_preferences`    | Table settings + layout / filter / view localStorage round-trip           |
-| `_focus`          | Focus-coordinate state + multi-cell selection                             |
-| `_virtualisation` | Row virtualisation window                                                 |
-| `_queryValues`    | Typeahead-echo cache for QuerySelect filter inputs                        |
-
-Each sub-context is a class under `Types/Context/<Name>State.svelte.ts`
-that takes a `deps` object of thunk-returning fields the parent reads
-on demand. The thunks keep reactivity flowing without the sub-context
-holding a parent reference — re-binding `TableContext._sorting` (or
-swapping its parent) is impossible by construction.
-
-The pattern when adding a new sub-context:
-
-1. Drop a `Types/Context/<Name>State.svelte.ts` file using
-   `FilteringState` as the structural template (`<Name>StateDeps`
-   interface, class with `$state` / `$derived` slots, `deps` thunks).
-2. Add a `_name: <Name>State` field on `TableContext` constructed with
-   the deps thunks closed over `this`.
-3. Add public passthrough getters/setters on `TableContext` for any
-   slot consumers reached for through the legacy field name.
-4. Write a `<Name>State.svelte.test.ts` test next to the new class.
-   Cover construction, each writer, and each derived read.
-5. If the sub-context surfaces a typed sub-API on the public `Table`
-   instance, wire a builder in `SubApis.svelte.ts` returning a frozen
-   object literal.
-
----
-
-## The data repo
-
-`TableContext.dataRepo` is the storage layer. Three concrete shapes:
-
-- `LocalDataRepository` — handed a plain array; sorts/filters/paginates
-  in process.
-- `BuiltInRemoteRepository` — fetches pages from a REST endpoint with
-  scoria's built-in query-string format.
-- `CustomDataRepository` — built by `customRows({ fetch, … })` for
-  consumer-shaped query strings. flowms wraps this in
-  `createRemoteRowSource.ts` to map flowms's filter format.
-
-The repo abstract base (`TableDataRepository.svelte.ts`) owns:
-
-- `paginationState` (page index + size, persisted)
-- the per-column `_filterModes` SvelteMap
-- the `forceRefresh` callback hook (use `registerRefreshMethod` to
-  assign without firing; the setter form fires immediately and is
-  `@deprecated`)
-
-If you add a new repo subclass, also extend the runtime discriminator
-on `IDataRepository.paginationType` so existing callers can branch.
-
----
-
-## Adding a new column kind
-
-This is intentionally not a one-file change; the surface area below is
-the irreducible minimum. Pick the four (sometimes five) sites carefully:
-
-1. **Def class** — `Types/Columns/Definitions/{Accessors,Display,…}/<Kind>Def.svelte.ts`.
-   Inherits from the matching category base (`AccessorDef` / `DisplayDef` / etc.).
-2. **Cell renderer** — `Body/Rows/Columns/<Kind>Cell.svelte`. Picked
-   by the dispatch chain in `TableColumn.svelte` (currently an
-   `instanceof` if/else; intentionally not registry-driven — see
-   follow-up F3 in `PROJECT_CONTEXT.md`).
-3. **Public option type** — add to `Types/Public/ColumnOptions.ts`.
-   Discriminated by the kind literal.
-4. **Factory method** — add a method on `ColumnFactory<TRow>` in
-   `ColumnFactory.svelte.ts`. The factory's `makeSpec(kind, def, …)`
-   tags the def with `def.kind = kind` automatically.
-5. **Registry entry** — add to `COLUMN_KIND_REGISTRY` in
-   `ColumnKindRegistry.ts`. Mark `category` and (if applicable) a
-   `defaultFilter` key. The companion test file enforces "every kind
-   has an entry".
-
-A `setupDefaultColumnDefs` change is no longer needed; it now reads
-from the registry.
-
----
-
-## Load-bearing invariants
-
-These each cost real time to discover the first time. Tagged for future
-greppability.
-
-### `def.kind` is the canonical sort key
-
-Every `ColumnDef` produced by the factory carries `def.kind`. Filter
-wiring (`setupDefaultColumnDefs`), debug logs, and the public spec all
-derive from it. A hand-constructed `ColumnDef` (test stub, legacy code)
-without `kind` is tolerated but skips registry-driven defaults — the
-consumer must assign `filterFn` themselves.
-
-### Filter-input `__queryValues` is gone; use `tableContext.queryValues`
-
-The legacy `dataRepo.__queryValues: Map<string, unknown>` shared cache
-has been replaced by the typed `QueryValuesState` sub-context. New
-filter widgets should call `tableContext.queryValues.get(def)` /
-`set(def, value)`. The sub-context keys by `ColumnDef` so the
-historical `def.id` vs `label` keying bug class is structurally
-prevented.
-
-### `reactiveDependencies` for async accessors
-
-`col.display({ value: async (row) => row.foo.value })` will only
-re-render when row identity changes — not when `row.foo.value` mutates,
-because the reactive read happens after the `await` boundary. Pass a
-`reactiveDependencies: (row) => [row.foo.value]` thunk on the column
-options so the cell's `$derived` registers the dep synchronously.
-
-### Dropdowns do NOT move in the DOM
-
-`Helpers/dropdownPortal.ts` flips a Svelecte dropdown to
-`position: fixed` and lifts its stacking-context ancestor; it does NOT
-re-parent the dropdown to `document.body`. Svelte 5's root-level event
-delegation walks the live `parentNode` chain at dispatch time — moving
-the element out of the mount target silently breaks mouse-click option
-selection while keyboard Enter keeps working. See the header comment in
-`dropdownPortal.ts` for the full reasoning.
-
-### Pinned cells skip horizontal scrollIntoView
-
-In `Table.svelte`'s focus-restore effects, the scroll-into-view call
-omits `inline: 'nearest'` for pinned cells. Sticky positioning makes
-them visually always-on-screen, but their layout position is at the
-real (often off-screen) column track; an unconditional inline scroll
-would surface the underlying position and the table would "jump" when
-focus lands on a pinned Actions button.
-
-### Clipboard copy must pass through `escapeForSpreadsheet`
-
-Every path that writes to `navigator.clipboard.writeText` is required
-to neutralise formula-injection prefixes via
-`escapeForSpreadsheet` (or `encapsulate`, which calls it). The single-
-cell `clipboard.copyCell` route and the bulk
-`copyDataToClipboard` / `copyHighlightedRowsToClipboard` paths both
-already use it; new copy paths must too.
-
-### `createTable` is async-effective; consume via reactive readers
-
-`createTable({...})` returns the structured `Table` instance synchronously, but the underlying `TableContext` finishes initialising asynchronously: `setupDefaultColumnDefs` runs unawaited in the constructor, and `_selection`'s pending-changes buffer flushes on `tick()`. Two practical consequences:
-
-- `table.columns.specs` and `table._context.columnDefs` are empty for the first microtask after `createTable` returns. Reactive readers (a `$derived` or `$effect`) re-evaluate when the columns land, so consumer code reads through these without thinking about it.
-- `table.selection.set(rowId, row)` writes into the pending-changes buffer and flushes on `tick()`. `table.selection.size` returns the post-flush value the next time a reactive consumer reads it; a synchronous read on the same call frame returns the pre-flush value.
-
-Direct synchronous read-back of state is therefore only safe inside an `$effect` or after `await tick()`. Unit tests at the public API surface need either a reactive harness or explicit `await tick()` between writes and assertions; that's why scoria's table tests use the `.svelte.test.ts` (browser-project) shape rather than plain server-mode unit tests.
-
-### Custom-row sources must defensively resolve their accessor thunks
-
-A `customRows({ uri, defaultFilters, remoteFilters })` source can have
-its accessor thunks called after the surrounding Svelte component has
-torn down (a debounced fetch landing across a route change). Wrap the
-thunk reads in try/catch and validate the returned shape — see
-`flowms-svelte-web/src/lib/components/base/Table/createRemoteRowSource.ts`
-for the canonical pattern.
-
----
-
-## Testing model
-
-| File pattern                | Project  | What it covers                                                                        |
-| --------------------------- | -------- | ------------------------------------------------------------------------------------- |
-| `*.test.ts` (no `.svelte.`) | `server` | Pure-node unit tests (helpers, type contracts). Runs via `pnpm test`.                 |
-| `*.svelte.test.ts`          | `client` | Tests using `$state` / `$effect` from Svelte 5. Browser mode via Vitest + Playwright. |
-
-The browser-mode runner has a Windows-specific chromium launch issue;
-set `SCORIA_CHROMIUM_EXECUTABLE` to the headless-shell binary to work
-around it (follow-up F1 in `PROJECT_CONTEXT.md`). The server project
-covers the kind-registry contract, clipboard escape behaviour, and the
-co-located decoupling tests.
-
-Add new tests next to the code they cover, not in a global `__tests__`
-folder.
-
----
-
-## Storybook
-
-Stories live under `src/stories/Table/`. Mount via the shared host
-`_helpers/TableHost.svelte` which accepts a `CreateTableOptions` payload
-and runs `createTable` inside instance init (module-scope `createTable`
-would trip `effect_orphan`). The `Table/Table API` MDX page is the
-companion reference; keep it in sync with significant public-API
-changes.
-
----
-
-## Cross-references
-
-- `PROJECT_CONTEXT.md` (repo root) — project state, known issues and
-  follow-ups (Part A), plus the consumer migration guide (Part B).
-- `agent-review/dev-changelog.md` — long-form record of the
-  decomposition phases.
-- `src/lib/Components/Table/Types/Public/index.ts` — barrel for every
-  public type re-exported from `src/lib/index.ts`.
+# `<Table>` architecture
+
+Orientation for a new developer opening `src/lib/Components/Table/`. Read this once before changing anything substantive in this subtree. Read it again before reviewing a PR.
+
+For the cross-cutting story of how the current shape came to be, see
+`agent-review/dev-changelog.md` at repo root. For the consumer-facing
+public API, see the Storybook stories under `Table/Table API` and
+`src/stories/Table/*`.
+
+---
+
+## What ships out of the front door
+
+Everything in the public surface is re-exported from
+`src/lib/index.ts`. The Table-side of that file is small on purpose:
+
+```ts
+import {
+	createTable,
+	localRows,
+	remoteRows,
+	customRows,
+	Table,
+	type CreateTableOptions,
+	type DisplayModalProps,
+	// …per-kind option types: TextColumnOptions, NumberColumnOptions, …
+} from '@lavalogic/scoria';
+```
+
+Three entry points cover every legitimate use:
+
+1. `createTable<TRow, IdType>({...})` builds a structured `Table`
+   instance. The returned value carries the typed sub-APIs (`selection`,
+   `filtering`, `sorting`, `clipboard`, `columns`, `pagination`,
+   `preferences`, `focus`, `modal`).
+2. `<Table {table} />` mounts the instance.
+3. The column builder closure passed under `columns:` is given a
+   `ColumnFactory<TRow>` parameter; consumers reach for the matching
+   `col.text(...)`, `col.number(...)`, `col.select(...)` and so on.
+
+The Def classes (`TextInputDef`, `DisplayDef`, …) are NOT exported. They
+are constructed inside `ColumnFactory.svelte.ts` and never appear on a
+consumer's import surface. If you need to alter Def behaviour, do it
+through the factory.
+
+---
+
+## Folder tour
+
+```
+Table/
+├── Table.svelte                       — top-level component (mounts the grid + chrome)
+├── createTable.svelte.ts              — the consumer-facing entry; builds the TableContext + public Table instance
+├── ColumnFactory.svelte.ts            — closure-based column builder; wraps each Def
+├── ColumnKindRegistry.ts              — kind→category map used by setupDefaultColumnDefs
+├── ColumnKindRegistry.test.ts         — registry contract tests
+├── SubApis.svelte.ts                  — facade constructors for each typed sub-API on the public Table instance
+├── NestedTable.svelte                 — internal Expand-column body
+├── TableHelpers.svelte.ts             — co-located helpers (column-id mint, etc.)
+├── clipboardEscape.ts                 — escapeForSpreadsheet / encapsulate
+│
+├── Body/                              — body-grid layer
+│   ├── TableBody.svelte
+│   ├── QuickSearchCell.svelte         — filter row inputs
+│   └── Rows/Columns/                  — per-kind cell components
+│
+├── Headers/                           — header-row layer
+│   └── TableHead.svelte               — column headers, sort buttons, resize handles
+│
+├── Misc/                              — toolbars, side-panels, footer, filter panels
+│   ├── TableFooter.svelte
+│   ├── TableSidebar.svelte
+│   ├── TableHorizontalBar.svelte
+│   ├── FilterPanel.svelte
+│   ├── FilterInput.svelte             — advanced-filter panel inputs
+│   ├── ColumnPanel.svelte             — column visibility & order panel
+│   └── ToolboxPanel.svelte            — extra tool buttons
+│
+└── Types/                             — all type declarations + state classes
+    ├── Public/                        — every consumer-facing type
+    ├── Context/                       — TableContext (god) + the Phase 6 sub-contexts
+    ├── Columns/                       — Def classes (internal) + Column shape types
+    ├── DataRepository/                — TableDataRepository abstract + BuiltInRemoteRepository
+    ├── Filtering/                     — FilterFn, ColumnFiltersState, FilterMode enums
+    ├── Pagination/                    — PaginationState, PaginationType enum
+    ├── Focus/                         — focus-coordinate helpers
+    ├── Coordinates/                   — CellCoordinates, ColumnIndices brands
+    ├── Layout/                        — layout-related helpers
+    └── Toolbar/                       — ToolbarPosition enum
+```
+
+---
+
+## The state graph
+
+`TableContext` is the root state object. It owns the data repo and seven
+sub-contexts:
+
+| Sub-context       | Owns                                                                      |
+| ----------------- | ------------------------------------------------------------------------- |
+| `_sorting`        | Sort comparators + the `sortedData` derived chain                         |
+| `_filtering`      | Filter-fn relays + the `filteredData` derived chain + quick-filter toggle |
+| `_columnLayout`   | Column widths / pinning / visibility / id-index maps                      |
+| `_selection`      | Selected & highlighted maps, key cache, page-wide select helpers          |
+| `_preferences`    | Table settings + layout / filter / view localStorage round-trip           |
+| `_focus`          | Focus-coordinate state + multi-cell selection                             |
+| `_virtualisation` | Row virtualisation window                                                 |
+| `_queryValues`    | Typeahead-echo cache for QuerySelect filter inputs                        |
+
+Each sub-context is a class under `Types/Context/<Name>State.svelte.ts`
+that takes a `deps` object of thunk-returning fields the parent reads
+on demand. The thunks keep reactivity flowing without the sub-context
+holding a parent reference — re-binding `TableContext._sorting` (or
+swapping its parent) is impossible by construction.
+
+The pattern when adding a new sub-context:
+
+1. Drop a `Types/Context/<Name>State.svelte.ts` file using
+   `FilteringState` as the structural template (`<Name>StateDeps`
+   interface, class with `$state` / `$derived` slots, `deps` thunks).
+2. Add a `_name: <Name>State` field on `TableContext` constructed with
+   the deps thunks closed over `this`.
+3. Add public passthrough getters/setters on `TableContext` for any
+   slot consumers reached for through the legacy field name.
+4. Write a `<Name>State.svelte.test.ts` test next to the new class.
+   Cover construction, each writer, and each derived read.
+5. If the sub-context surfaces a typed sub-API on the public `Table`
+   instance, wire a builder in `SubApis.svelte.ts` returning a frozen
+   object literal.
+
+---
+
+## The data repo
+
+`TableContext.dataRepo` is the storage layer. Three concrete shapes:
+
+- `LocalDataRepository` — handed a plain array; sorts/filters/paginates
+  in process.
+- `BuiltInRemoteRepository` — fetches pages from a REST endpoint with
+  scoria's built-in query-string format.
+- `CustomDataRepository` — built by `customRows({ fetch, … })` for
+  consumer-shaped query strings. flowms wraps this in
+  `createRemoteRowSource.ts` to map flowms's filter format.
+
+The repo abstract base (`TableDataRepository.svelte.ts`) owns:
+
+- `paginationState` (page index + size, persisted)
+- the per-column `_filterModes` SvelteMap
+- the `forceRefresh` callback hook (use `registerRefreshMethod` to
+  assign without firing; the setter form fires immediately and is
+  `@deprecated`)
+
+If you add a new repo subclass, also extend the runtime discriminator
+on `IDataRepository.paginationType` so existing callers can branch.
+
+---
+
+## Adding a new column kind
+
+This is intentionally not a one-file change; the surface area below is
+the irreducible minimum. Pick the four (sometimes five) sites carefully:
+
+1. **Def class** — `Types/Columns/Definitions/{Accessors,Display,…}/<Kind>Def.svelte.ts`.
+   Inherits from the matching category base (`AccessorDef` / `DisplayDef` / etc.).
+2. **Cell renderer** — `Body/Rows/Columns/<Kind>Cell.svelte`. Picked
+   by the dispatch chain in `TableColumn.svelte` (currently an
+   `instanceof` if/else; intentionally not registry-driven — see
+   follow-up F3 in `PROJECT_CONTEXT.md`).
+3. **Public option type** — add to `Types/Public/ColumnOptions.ts`.
+   Discriminated by the kind literal.
+4. **Factory method** — add a method on `ColumnFactory<TRow>` in
+   `ColumnFactory.svelte.ts`. The factory's `makeSpec(kind, def, …)`
+   tags the def with `def.kind = kind` automatically.
+5. **Registry entry** — add to `COLUMN_KIND_REGISTRY` in
+   `ColumnKindRegistry.ts`. Mark `category` and (if applicable) a
+   `defaultFilter` key. The companion test file enforces "every kind
+   has an entry".
+
+A `setupDefaultColumnDefs` change is no longer needed; it now reads
+from the registry.
+
+---
+
+## Load-bearing invariants
+
+These each cost real time to discover the first time. Tagged for future
+greppability.
+
+### `def.kind` is the canonical sort key
+
+Every `ColumnDef` produced by the factory carries `def.kind`. Filter
+wiring (`setupDefaultColumnDefs`), debug logs, and the public spec all
+derive from it. A hand-constructed `ColumnDef` (test stub, legacy code)
+without `kind` is tolerated but skips registry-driven defaults — the
+consumer must assign `filterFn` themselves.
+
+### Filter-input `__queryValues` is gone; use `tableContext.queryValues`
+
+The legacy `dataRepo.__queryValues: Map<string, unknown>` shared cache
+has been replaced by the typed `QueryValuesState` sub-context. New
+filter widgets should call `tableContext.queryValues.get(def)` /
+`set(def, value)`. The sub-context keys by `ColumnDef` so the
+historical `def.id` vs `label` keying bug class is structurally
+prevented.
+
+### `reactiveDependencies` for async accessors
+
+`col.display({ value: async (row) => row.foo.value })` will only
+re-render when row identity changes — not when `row.foo.value` mutates,
+because the reactive read happens after the `await` boundary. Pass a
+`reactiveDependencies: (row) => [row.foo.value]` thunk on the column
+options so the cell's `$derived` registers the dep synchronously.
+
+### Dropdowns do NOT move in the DOM
+
+`Helpers/dropdownPortal.ts` flips a Svelecte dropdown to
+`position: fixed` and lifts its stacking-context ancestor; it does NOT
+re-parent the dropdown to `document.body`. Svelte 5's root-level event
+delegation walks the live `parentNode` chain at dispatch time — moving
+the element out of the mount target silently breaks mouse-click option
+selection while keyboard Enter keeps working. See the header comment in
+`dropdownPortal.ts` for the full reasoning.
+
+### Pinned cells skip horizontal scrollIntoView
+
+In `Table.svelte`'s focus-restore effects, the scroll-into-view call
+omits `inline: 'nearest'` for pinned cells. Sticky positioning makes
+them visually always-on-screen, but their layout position is at the
+real (often off-screen) column track; an unconditional inline scroll
+would surface the underlying position and the table would "jump" when
+focus lands on a pinned Actions button.
+
+### Clipboard copy must pass through `escapeForSpreadsheet`
+
+Every path that writes to `navigator.clipboard.writeText` is required
+to neutralise formula-injection prefixes via
+`escapeForSpreadsheet` (or `encapsulate`, which calls it). The single-
+cell `clipboard.copyCell` route and the bulk
+`copyDataToClipboard` / `copyHighlightedRowsToClipboard` paths both
+already use it; new copy paths must too.
+
+### `createTable` is async-effective; consume via reactive readers
+
+`createTable({...})` returns the structured `Table` instance synchronously, but the underlying `TableContext` finishes initialising asynchronously: `setupDefaultColumnDefs` runs unawaited in the constructor, and `_selection`'s pending-changes buffer flushes on `tick()`. Two practical consequences:
+
+- `table.columns.specs` and `table._context.columnDefs` are empty for the first microtask after `createTable` returns. Reactive readers (a `$derived` or `$effect`) re-evaluate when the columns land, so consumer code reads through these without thinking about it.
+- `table.selection.set(rowId, row)` writes into the pending-changes buffer and flushes on `tick()`. `table.selection.size` returns the post-flush value the next time a reactive consumer reads it; a synchronous read on the same call frame returns the pre-flush value.
+
+Direct synchronous read-back of state is therefore only safe inside an `$effect` or after `await tick()`. Unit tests at the public API surface need either a reactive harness or explicit `await tick()` between writes and assertions; that's why scoria's table tests use the `.svelte.test.ts` (browser-project) shape rather than plain server-mode unit tests.
+
+### Custom-row sources must defensively resolve their accessor thunks
+
+A `customRows({ uri, defaultFilters, remoteFilters })` source can have
+its accessor thunks called after the surrounding Svelte component has
+torn down (a debounced fetch landing across a route change). Wrap the
+thunk reads in try/catch and validate the returned shape — see
+`flowms-svelte-web/src/lib/components/base/Table/createRemoteRowSource.ts`
+for the canonical pattern.
+
+---
+
+## Testing model
+
+| File pattern                | Project  | What it covers                                                                        |
+| --------------------------- | -------- | ------------------------------------------------------------------------------------- |
+| `*.test.ts` (no `.svelte.`) | `server` | Pure-node unit tests (helpers, type contracts). Runs via `pnpm test`.                 |
+| `*.svelte.test.ts`          | `client` | Tests using `$state` / `$effect` from Svelte 5. Browser mode via Vitest + Playwright. |
+
+The browser-mode runner has a Windows-specific chromium launch issue;
+set `SCORIA_CHROMIUM_EXECUTABLE` to the headless-shell binary to work
+around it (follow-up F1 in `PROJECT_CONTEXT.md`). The server project
+covers the kind-registry contract, clipboard escape behaviour, and the
+co-located decoupling tests.
+
+Add new tests next to the code they cover, not in a global `__tests__`
+folder.
+
+---
+
+## Storybook
+
+Stories live under `src/stories/Table/`. Mount via the shared host
+`_helpers/TableHost.svelte` which accepts a `CreateTableOptions` payload
+and runs `createTable` inside instance init (module-scope `createTable`
+would trip `effect_orphan`). The `Table/Table API` MDX page is the
+companion reference; keep it in sync with significant public-API
+changes.
+
+---
+
+## Cross-references
+
+- `PROJECT_CONTEXT.md` (repo root) — project state, known issues and
+  follow-ups (Part A), plus the consumer migration guide (Part B).
+- `agent-review/dev-changelog.md` — long-form record of the
+  decomposition phases.
+- `src/lib/Components/Table/Types/Public/index.ts` — barrel for every
+  public type re-exported from `src/lib/index.ts`.