@happyvertical/smrt-svelte 0.55.23 → 0.56.0

package/AGENTS.md

@@ -15,12 +15,12 @@ subpath you are editing. This file keeps what holds in every module.
 | `src/test-support/` + `__tests__/` | the golden-test harness and pattern for Svelte component tests | [agents/testing.md](agents/testing.md) |
 | `src/components/import-export/` (`./import-export`) | `ImportExport` CSV/TSV import (column mapping, validation preview, error report) and export (column selection) driven by collection definitions + resolved field policy, over a pure Node-tested CSV layer (#3715) | [agents/import-export.md](agents/import-export.md) |
 | `src/components/settings/` (`./settings`) | `SettingsCatalog`, `paginateSettingsCatalog`, and the summary-vs-detail scalability contract | [agents/settings.md](agents/settings.md) |
-| `src/components/screens/` (`./screens`) | `RecipeScreens` / `ListScreen` / `DetailScreen` / `EditForm`: list, view, create and edit derived from a generated web definition plus resolved field policy; pure `deriveScreenFields` selection, minor-unit money handling, transport-neutral source (#3718) | [agents/screens.md](agents/screens.md) |
+| `src/components/screens/` (`./screens`) | `RecipeScreens` / `ListScreen` / `RecordScreen` / `DetailScreen` / `EditForm`: list, view, create and edit derived from a generated web definition plus resolved field policy; pure `deriveScreenFields` selection, `deriveFieldRoles` (title / identifier / status / money / totals roles) and `deriveScreenRelations` (children / items / reference); the record page's header (identifier, status, key facts, overflow Delete), details card and overview, select / derived fields and an items slot in inline (desktop) or sheet (phone) editing; minor-unit money handling, transport-neutral source (#3718) | [agents/screens.md](agents/screens.md) |
 | `src/components/app/` (`./app`) | `AppShell` (Provider + ThemeProvider + theme CSS + AdminShell + nav/dock slots), `OwnerSetupForm` (props-driven first-run owner form), `ShellSettingsPage`, `RuntimeDiagnosticsWebMcp`. Browser-only; no `$app/*` or server imports | [agents/workspace.md](agents/workspace.md#app-shell-and-owner-setup-app) |
 | `src/components/workspace/` (`./workspace` + `./web`) | the AdminShell family and its principles, the legacy ToolsDock surface, the `./web` activity-feed and `updateAvailable` adapters, and server-side dock gates | [agents/workspace.md](agents/workspace.md) |
 | `src/components/command-palette/` (`./command-palette`) | `CommandPalette` trigger + dialog, `PaletteProvider` contract, nav and manifest providers (#3713) | [agents/command-palette.md](agents/command-palette.md) |
 | `src/components/cookbook/` (`./cookbook` + `./cookbook/server`) | cookbook-driven app shell: pure `buildCookbookShell` (cookbook + recipe catalog to `AppShell` sections, entries, layout, theme, section overviews, recipe surfaces), `CookbookApp` / `CookbookSectionPage`, and the server `loadCookbookApp` (file + installed manifests + validation); ported from smrt-planner (#3749) | [agents/cookbook-shell.md](agents/cookbook-shell.md) |
-| `src/components/overview/` (`./overview` + `./overview/server`) | customizable overview surfaces: `OverviewGrid` flow grid (span 1-4, keyboard reorder/resize) joined to the shell's layout edit mode, host-owned `createOverview` controller, widget registry with versioned option schemas validated on save and load, the server `load(options, ctx)` contract (`loadOverview`), the metric/chart/records/shortcuts/note core widgets, and `registerRecipeWidgets` (recipe `widget` surfaces to registry registrations, injected module resolver) (#3727); production persistence is `@happyvertical/smrt-preferences` (kind `overview`) | [agents/overview-surfaces.md](agents/overview-surfaces.md) |
+| `src/components/overview/` (`./overview` + `./overview/server`) | customizable overview surfaces: `OverviewGrid` flow grid (span 1-4, keyboard reorder/resize) joined to the shell's layout edit mode, host-owned `createOverview` controller, widget registry with versioned option schemas validated on save and load, the server `load(options, ctx)` contract (`loadOverview`), the metric/chart/records/shortcuts/note core widgets (records as a role-column table with a `DataTable` summaries footer), the record-page `related` (tabbed) and `line-items` (totals block) widgets, and `registerRecipeWidgets` (recipe `widget` surfaces to registry registrations, injected module resolver) (#3727); production persistence is `@happyvertical/smrt-preferences` (kind `overview`) | [agents/overview-surfaces.md](agents/overview-surfaces.md) |
 | `src/web/remote-query.svelte.ts` | Svelte 5 binding for query-shaped remote pages: rows, page, totals, loading/refreshing/stale/error, retry, last-updated, and query-scoped live subscriptions (#2445) | — |
 | `src/web/list-data-surface.svelte.ts` (`mountListDataSurface`) | Registers an existing non-`DataTable` list (mirroring a `DataTableController`) as a mounted `DataSurfaceDescriptor`; a same-behavior port of `registerContentListDataSurface`, not yet unified behind smrt-ui (#2917). The module doc comment is the authoritative list of divergences (#2906) | — |
 | `src/web/webmcp-provider.ts` | Provider config for generated data/model WebMCP tools: definitions, effect policy, namespace, budget, legacy/canonical filters, and fetcher seams (#2520) | — |

package/README.md

@@ -708,13 +708,13 @@ importable, even if it appears in `dist/`.
 | `@happyvertical/smrt-svelte/forms` | Form inputs (TextInput, Select, MoneyInput, DateTimeInput, Toggle, etc.) |
 | `@happyvertical/smrt-svelte/import-export` | `ImportExport` (CSV/TSV import with column mapping, validation preview and error report; export with column selection), `createCollectionImportExport`, `fieldsFromCollectionDefinition`, and the pure CSV layer |
 | `@happyvertical/smrt-svelte/settings` | Server-paged settings search, selection, and list/detail layout (`SettingsCatalog`, `paginateSettingsCatalog`) |
-| `@happyvertical/smrt-svelte/screens` | List, view, create and edit screens derived from a generated web definition and resolved field policy (`RecipeScreens`, `ListScreen`, `DetailScreen`, `EditForm`) |
+| `@happyvertical/smrt-svelte/screens` | List, view, create and edit screens derived from a generated web definition and resolved field policy (`RecipeScreens`, `ListScreen`, `RecordScreen`, `DetailScreen`, `EditForm`); `RecordScreen` is the record view with a customizable related-records overview and inline (desktop) or sheet (phone) editing, `deriveScreenRelations` its relation rule |
 | `@happyvertical/smrt-svelte/workspace` | AdminShell, ShellState, tenant nav, focus tools, settings, activities, and system/app panels |
 | `@happyvertical/smrt-svelte/app` | `AppShell` (Provider + themes + AdminShell + nav/dock slots, `dockToggles` buttons and host `slots` for the header/footer/sidebar regions), `OwnerSetupForm` (first-run owner setup), `ShellSettingsPage`, `RuntimeDiagnosticsWebMcp` |
 | `@happyvertical/smrt-svelte/app/runtime-diagnostics` | Svelte-free diagnostics WebMCP registration and its tool name/endpoint constants, importable from server routes |
 | `@happyvertical/smrt-svelte/command-palette` | Global search and command palette: `CommandPalette` (shell-slot trigger plus dialog), `createCommandPalette`, the provider contract, and the navigation and manifest-driven model providers |
 | `@happyvertical/smrt-svelte/overview` | Customizable overview surfaces: `OverviewGrid` (flow grid with keyboard reorder and resize), `createOverview` (host-owned controller), the widget registry (`registerWidget`), `registerCoreWidgets` (metric, chart, record list, shortcuts, note) and `shortcutsFromNav` |
-| `@happyvertical/smrt-svelte/overview/server` | Svelte-free half of the overview surface: the data model (`resolveOverview`, `checkOverviewOverride`), option-schema validation, `WidgetRegistry`, and `loadOverview` for a page's server load |
+| `@happyvertical/smrt-svelte/overview/server` | Svelte-free half of the overview surface: the data model (`resolveOverview`, `checkOverviewOverride`), option-schema validation, `WidgetRegistry`, and `loadOverview` for a page's server load; `recordOverview` / `recordOverviewId` (the record view's default overview, per model kind) |
 | `@happyvertical/smrt-svelte/workspace/legacy` | Opt-in ToolsDock compatibility surface for applications migrating to AdminShell |
 | `@happyvertical/smrt-svelte/workspace/server` | Server-side workspace helpers (Node only) |
 | `@happyvertical/smrt-svelte/workspace/live` | `systemFeed` — the AdminShell system scope (jobs/schedules/dispatch) polled from an app status endpoint; deliberately carries no `smrt-web` dependency |

package/agents/overview-surfaces.md

@@ -22,6 +22,11 @@ assistant operations with Undo ("Assistant operations").
 | `./overview/server` (`server.ts`) | Svelte-free: types, `validateWidgetOptions`, the model (`resolveOverview`, `checkOverviewOverride`, `applyOverviewOverride`, `diffOverview`, `sanitizeOverview`, ...), `WidgetRegistry` / `registerWidget`, `loadOverview`, the operations (`planOverviewOperations`, `describeOverview`) and `createOverviewAssistantSurface`. Safe in a `+page.server.ts` or a save endpoint. |
 | `./overview` (`index.ts`) | Everything above plus `OverviewGrid`, `createOverview` (controller), `WidgetOptionsForm`, the core widgets and `registerCoreWidgets`, `shortcutsFromNav`, `formatWidgetValue`, `parseMarkdown` / `safeHref`, `createOverviewAssistant` / `useOverviewAssistantTools` / `OverviewAssistantUndo`. |
 
+`ChartWidget` delegates to `@happyvertical/smrt-ui/charts` so domain packages
+can reuse the same renderer without depending on this integration package.
+`formatWidgetValue` remains a compatibility re-export of the Svelte-free
+`@happyvertical/smrt-ui/charts/format` entry. Existing translation keys stay stable.
+
 ## Data model (`types.ts`, `model.ts`)
 
 A saved overview is data, never code:
@@ -113,10 +118,26 @@ return { overview };   // LoadedOverview: JSON, serializable
 
 - A widget's `load(options, ctx)` receives **validated options only** and a
   `WidgetLoadContext` the host built from the request principal: `overviewId`, an
-  abort `signal`, `locale`, and any host capabilities (index keys). It must
+  abort `signal`, `locale`, the optional core `record` key (below), and any host
+  capabilities (index keys). It must
   authorize through `ctx` (the user's permissions and tenant filters), never
   through option values. Reports-backed chart loaders call the runtime-report
   compiler with this context; this package does not depend on it.
+- **`ctx.record = { model, id }`** is a core capability key: the record a
+  record overview is rendered on (`RecordScreen` sets it from the screen's
+  definition `objectRef` and the record's id; a host's server load sets it the
+  same way for a record page). With it comes the **parent-filter vocabulary**
+  of the core `records` and `metric` loaders: `filter: 'parent'` plus `field`
+  (the FK field on `options.model`) mean "rows of `model` whose `field` equals
+  `ctx.record.id`" — a count for `metric`, the newest rows for `records`
+  (`sort` / `direction` / `limit` as usual). A `metric` with `parentField`
+  uses that as the FK and measures `field` (`measure: 'sum'`, `field:
+  'totalAmount'`, `parentField: 'customerId'`: the record's order total). A
+  `records` load may carry `columns` (comma-separated keys; fill each row's
+  `cells`). A loader given `filter: 'parent'`
+  without `ctx.record` or `field` must return an empty result, never the
+  unfiltered model. The shell's own loaders need no data access: hosts
+  implement it, the same way they implement every other named filter.
 - Loads run in parallel with a per-widget timeout (default 8 s; the signal
   aborts). A thrown error, a timeout or non-serializable / oversized data
   (default 256 KB of JSON) becomes a per-widget error tile
@@ -197,9 +218,9 @@ shape. Data shapes are in `widgets/data.ts`.
 
 | Type | Options | Data |
 |---|---|---|
-| `metric` | `title`, `model`*, `measure`, `field`, `filter` | `{ value, format?, currency?, label?, change?, href? }` (money = integer minor units) |
+| `metric` | `title`, `model`*, `measure`, `field`, `filter`, `parentField` | `{ value, format?, currency?, label?, change?, href? }` (money = integer minor units) |
 | `chart` | `title`, `model`*, `groupBy`, `measure`, `field`, `period`, `style` (bar/line/table/pie/stat), `filter` | `{ points: [{ label, value }], format?, currency?, href?, delta? }`, one measure of a runtime report |
-| `records` | `title`, `model`*, `sort`, `direction`, `limit`, `filter` | `{ rows: [{ id, title, subtitle?, meta?, href? }], total?, href? }`; the loader chooses the title field and the visible records |
+| `records` | `title`, `model`*, `sort`, `field`, `direction`, `limit`, `filter`, `columns`, `summaries` | `{ rows: [{ id, title, subtitle?, meta?, href?, cells? }], total?, href?, columns?, currency?, timeZone?, summaries? }`; the loader chooses the title field and the visible records; `field` is the FK for `filter: 'parent'`; with columns (the option, else `data.columns`) the rows are a table — see "Records tables" |
 | `shortcuts` | `title`, `section` | `{ items: [{ id, label, href, icon?, description?, count? }] }` (`count` draws as "N records"; widgets also receive the grid's `presentation` and the shortcuts widget drops its entry frame under `plain`); `shortcutsFromNav(sections, sectionId)` maps `resolveShellNavModel` / `useShellLayout().sections` (visible entries, user renames) |
 | `note` | `title`, `body` (Markdown) | none |
 
@@ -219,6 +240,64 @@ else derived from the last two points). Motion honours `prefers-reduced-motion`.
 The chart option schema is **version 2**: v1 (`style` bar or line, or no version)
 migrates by identity (`migrateChartOptions`), so saved overviews keep validating.
 
+## Records tables (`widgets/RecordTable.svelte`, `widgets/record-table.ts`)
+
+The `records` widget with columns, each `related` tab and `line-items` render
+one internal `RecordTable`: smrt-ui `DataTable` (dense, `phoneLayout="cards"`)
+with cells by `RecordListColumn.role` — `identifier` monospace, `status` a
+`Badge` (`statusTone`), `date` date-only in `data.timeZone` (default UTC, so
+SSR and the browser agree; a non-ISO string is shown as sent), `money` from
+integer minor units in `data.currency`, `quantity` a number — and the first
+column linking to the row's `href`. The footer is `DataTable`'s `summaries`
+(no per-widget footer code): the count (`total`, else the rows) in the first
+column and the sum of every `money` / `quantity` column unless
+`summarize: false` (a unit price). **A partial page is never summed**: when
+`total` exceeds the rows, a sum cell is empty unless the loader sent
+`summaries` (totals over every matching record, money in minor units). The
+`columns` option is a comma-separated list because options are flat JSON
+primitives (`parseColumnsOption` / `formatColumnsOption`, at most 6 keys);
+labels and roles come from `data.columns`, else a humanized key. Pure,
+Node-tested helpers: `formatRecordCell`, `statusTone` /
+`DEFAULT_STATUS_TONES`, `statusLabel`, `resolveRecordColumns`,
+`readRecordRows`, `isSummedColumn`.
+
+## Record-page widgets (`related`, `line-items`; `widgets/record-loaders.ts`)
+
+Built from the record's relations, so they register per record view —
+`registerRecordWidgets(registry, { relations, records, viewAllHref?,
+totals?, currency? })`; `RecordScreen` does it on its own registry when
+`loaders.records` is given. **Loader contract: no new loader.** Each tab /
+the lines are one call of the host's core `records` loader with the
+parent-filter vocabulary (`model`, `field`, `filter: 'parent'`, `sort`,
+`direction`, `limit`, `columns`), so a host that implements parent-filtered
+`records` implements both. Loaders are Svelte-free on both entries
+(`createRelatedLoader`, `createLineItemsLoader`, `relatedRelations`,
+`relatedTabOptions`, `lineItemsRelation`, `lineItemsOptions`).
+
+| Type | Options | Data |
+|---|---|---|
+| `related` | `title`, `relations` (relation keys `Order-customerId`, comma-separated; empty = every `children` relation, at most 20), `limit` (5) | `{ tabs: [{ key, label, rows, total?, columns, href?, currency?, timeZone?, summaries? }] }` |
+| `line-items` | `title`, `relation` (an `items` relation key; empty = the first), `limit` (50, the max) | `{ rows, columns, total?, totals?: { subtotal?, discount?, tax?, total? }, currency?, summaries?, href? }` |
+
+- `related`: one tab per relation with the count in the tab ("Orders 6"),
+  each a records table with a totals footer and that tab's one "View all"
+  (`viewAllHref`, else the loaded `href`). Relations with no rows are hidden;
+  all empty is one empty state. A failing tab is dropped; all failing fails
+  the widget. Never lists `items` relations.
+- `line-items` (the contract's `lineItems`; widget type ids are lowercase
+  kebab): the lines in `sort` order, then the totals block
+  (`lineItemTotals`, pure). The record's own subtotal / discount / tax /
+  total are authoritative and shown as they are; one it lacks is computed
+  from the lines (subtotal = sum of the line amounts, total = subtotal -
+  discount + tax) and marked "(from the lines)"; discount and tax show when
+  present and non-zero. When the record's subtotal (or, without one, its
+  total) disagrees with the lines, a visible flag says "Lines add up to $X."
+  beside the recorded figure — never a silent override. A partial page of
+  lines is not compared.
+- Tests: `__tests__/record-table.test.ts`, `__tests__/record-widgets.test.ts`,
+  `__tests__/line-items.test.ts` (axe on both components), the records cases
+  in `__tests__/widgets.test.ts`.
+
 ## Recipe widgets (`recipe-widgets.ts`)
 
 A package contributes a widget with a `widget` surface on a recipe
@@ -232,6 +311,7 @@ turns the manifest's widget surfaces into `registry.register(...)` calls:
 | `type`, `label`, `description`, `icon`, `version` | `type`, `title`, `description`, `icon`, `version` |
 | `options` | `options` (plain JSON; `registry.register` re-validates the schema) |
 | `export` | `loadComponent` (lazy; the export may be a component or a `{ default }` module) |
+| `optionsEditor` | `loadOptionsEditor` (lazy; lets dependent choices use a package-owned editor without importing UI on the server) |
 | `data.load` | `load` (resolved on first use; a missing or non-function loader is that widget's error tile) |
 | `migrate` | `migrate`, **resolved eagerly** because the registry's `migrate` is synchronous |
 | `allowedIn`, `defaultSpan`, `minSpan`, `maxSpan` | same names |
@@ -240,8 +320,9 @@ turns the manifest's widget surfaces into `registry.register(...)` calls:
 - **The module resolver is injected.** `resolveExport(specifier, exportName)` is
   the host's: a static map of dynamic imports in a bundled app, a stub in tests.
   Nothing is imported when the manifest is read, and the registration itself
-  imports nothing except `migrate` exports. Relative or absolute specifiers
-  are refused.
+  imports nothing except `migrate` exports. UI hosts resolve lazy components
+  with `resolveWidgetComponents(...)` and custom editors with
+  `resolveWidgetOptionsEditors(...)`. Relative or absolute specifiers are refused.
 - **Never throws for a bad surface.** The result is `{ registered, skipped,
   dispose }`; a skip carries `reason` `duplicate_type` (a core widget or another
   recipe owns the type; `replace` overrides), `invalid` (the registry refused the
@@ -250,7 +331,8 @@ turns the manifest's widget surfaces into `registry.register(...)` calls:
 - **`enabled(recipeId)`** keeps widgets of recipes that are off out of the add
   list. Call the helper again (after `dispose()`) when the set changes.
 - Widget types share one registry namespace with the core widgets
-  (`metric`, `chart`, `records`, `shortcuts`, `note`). Pages still confine what
+  (`metric`, `chart`, `records`, `shortcuts`, `note`) and the record-page
+  widgets (`related`, `line-items`). Pages still confine what
   can appear with `defineOverview({ allowed })`, and a widget with `allowedIn`
   only validates inside those overview ids.
 - `src/components/overview/__tests__/recipe-widgets.test.ts` covers lazy
@@ -374,6 +456,35 @@ and the person can undo the change.
   `createOverviewStore(...).save` as shown there.
 - **Not built:** the activity widget (Track B, #3710) and agenda.
 
+## Record overviews (`record.ts`)
+
+`recordOverview(definition, relations, { id?, metrics?, maxMetrics?,
+related? })` (both entries) is the default overview of a record page:
+
+1. **Summary strip** (`metrics`, default on): `metric` tiles of span 1, a
+   count per `children` relation (`field` = the FK) and, where its columns
+   have a money column, the sum of it (`measure: 'sum'`, `field` = the
+   amount, `parentField` = the FK), at most `maxMetrics`
+   (`RECORD_OVERVIEW_MAX_METRICS` = 4). Ordinary widgets: removable.
+2. **`line-items`** (span 4) for the first `items` relation.
+3. **`related`** (span 4, id `related`) over the `children` relations;
+   `related: 'panels'` instead declares one `records` panel per relation
+   (span `RECORD_OVERVIEW_PANEL_SPAN` = 2, newest five, `columns` from the
+   relation) — the previous default.
+
+Default widget ids come from the relation (`count-Order-customerId`,
+`sum-...`, `items-OrderLine-orderId`, `records-...`; a `-2` suffix tells apart
+two that fold alike), not their position, so a host that narrows the defaults
+keeps every id, and added widgets (`w<n>`) never collide with a hidden
+default; `models` confines added widgets to the child models and `allowed` is
+`RECORD_OVERVIEW_ALLOWED` (`related`, `line-items`, `records`, `metric`,
+`chart`, `note`). The id defaults to `recordOverviewId(definition.objectRef)`
+— `detail:<model>` with `@`, `/` and `:` folded to dots
+(`detail:acme.shop.Customer`), because a qualified model id is not a valid
+overview id — so the layout persists **per model kind**, not per record.
+`RecordScreen` renders it with `presentation="plain"` and extends the widget
+context with `record`.
+
 ## Host section presentation
 
 `OverviewGrid` defaults to framed cards. Pass `presentation="plain"` for

package/agents/screens.md

@@ -8,8 +8,9 @@ invariants, and the traps that apply before editing anything live in
 
 `RecipeScreens` is the default screen set for a package that ships models but no
 consumer UI (tags, facts, secrets, profiles, reports, prompts). It composes
-`ListScreen`, `DetailScreen` and `EditForm`, each of which can also be used on
-its own. Every screen takes a generated web `definition`
+`ListScreen`, `RecordScreen` (the record view, which itself composes
+`DetailScreen`, `OverviewGrid` and `EditForm`) and `EditForm` (create), each of
+which can also be used on its own. Every screen takes a generated web `definition`
 (`ScreenCollectionDefinition`, structurally a `SmrtWebCollectionDefinition`) and
 an optional resolved `policy` (`ScreenPolicy`, structurally smrt-fields'
 `ResolvedObjectFieldPolicy`). The module imports neither package: smrt-svelte
@@ -34,14 +35,25 @@ stays below the domain layer, and the app passes both in as props.
   policy default (an explicit `null` included) beats the manifest default.
   `locked` governs who may change the POLICY, never the record value, so it is
   not applied here.
-- **Values are `values.ts`**: money (`ui.widget: 'currency'` on an INTEGER field
-  only) is integer minor units end to end. Editing shows major units but converts
+- **Values are `values.ts`**: money (an INTEGER field with the `money` role —
+  `ui.format: 'money'`, the legacy `ui.widget: 'currency'`, an explicit role,
+  or a money name; see "Field roles") is integer minor units end to end. Editing shows major units but converts
   with exact string math (`majorStringToMinorUnits`), never `* 100`; integers are
   rejected unless JavaScript-safe; datetimes go out as ISO strings (an unchanged datetime keeps the
   loaded record's full precision via `parseDraft`'s `record` context; the control
-  only shows minutes); JSON as parsed values. Empty optional text becomes `null` when the field is nullable and `''`
+  only shows minutes); JSON as parsed values. For display an empty JSON
+  object/array (or one whose values are all blank) formats as `''`, the
+  "Not set" placeholder, and `DetailScreen` lists a non-empty object as
+  key/value rows (`jsonScreenEntries`). Empty optional text becomes `null` when the field is nullable and `''`
   otherwise (unset text persists as `''`); every other empty optional field is
   `null`. Errors are codes, mapped to messages by the component via `useI18n`.
+- **Reference fields link (`relations`, `hrefFor`, `labels`).** `DetailScreen`
+  renders a `foreignKey` / `crossPackageRef` value as `<a href={hrefFor(field,
+  id)}>{labels[model](id)}</a>`; without an href the label alone, without a
+  label a shortened id (`shortScreenId`: first eight characters and `…`) in
+  `<code>` with the full id as its tooltip, inside the link when there is one. `labels` is keyed by the **target model id**,
+  which the screen finds through the `reference` relations (below), so pass
+  `relations` whenever you pass `labels`.
 - **Transport-neutral.** `RecipeScreens` drives a `RecipeScreensSource`
   (`list` / `get` / `create` / `update` / `delete`); an operation the source lacks
   (or `can` turns off) is simply not offered, so a read-only source is a
@@ -49,6 +61,13 @@ stays below the domain layer, and the app passes both in as props.
   fires on every user navigation, so an app can mirror them into its router.
   `EditForm.onsubmit` throws to report a failed save or returns `{ fieldErrors }`.
   Remount `EditForm` with `{#key}` when switching records (`RecipeScreens` does).
+- **`view` and `edit` are `RecordScreen`** (below); `create` stays the bare
+  `EditForm`. `onnavigate` is unchanged (`edit` is still a view of its own, so
+  a router maps it to `.../<id>/edit`). Pass `definitions` (every exposed
+  collection, keyed by name) for the related-records panels and `record`
+  (loaders, widget context, overview override and its `onoverviewchange`,
+  `hrefFor`, `labels`, `viewAllHref`) for the rest of the record view; without
+  `definitions` there are no relations and the view is the detail alone.
 - **Not the policy-editing surface.** The policy gear, field-usage telemetry and
   the per-field renderer registry live in `ObjectForm`
   (`@happyvertical/smrt-fields/svelte`); `EditForm` is the dependency-light
@@ -60,3 +79,150 @@ stays below the domain layer, and the app passes both in as props.
   `collectionDefinitions[<collection>]` from `@smrt/web` and the source is the
   model's `/api/<collection>` route (see [cookbook-shell.md](cookbook-shell.md)).
   A model the API does not expose has neither, so the entry page shows its notice.
+
+## Field roles (`roles.ts`)
+
+`deriveFieldRoles(definition)` is the pure, Node-tested rule for what a field
+MEANS on a record page: `FieldRole` = `title | identifier | status | money |
+quantity | date | party | subtotal | tax | discount | total`, several per field
+(`totalAmount` -> `['money', 'total']`), one key per declared field. Sources in
+order:
+
+1. Explicit metadata on `ScreenFieldDefinition`: `role` (authoritative — name
+   heuristics never add to it), `format` (`money | date | datetime | percent`,
+   wins over `ui.format`), `display: true` (the `title`), `enum`.
+2. Manifest hints: `ui.format`, and `ui.widget: 'currency'` on an INTEGER (on
+   a text field it is the currency-code picker, never money;
+   `currencyCodeField` finds it, and `RecordScreen` formats amounts in the
+   record's own currency).
+3. Name heuristics: `*Amount|*Total|price|cost` -> money on integers only;
+   `subtotal|tax|discount|total` (not `*Rate`); `status|state` WITH an enum;
+   `number|reference|code` but not `phoneNumber` / `postalCode` /
+   `currencyCode`; `*At|*Date|*On|*Until` datetimes; `quantity|qty`; an FK
+   whose name or target collection is party-like (customer, vendor, profile,
+   ...). Without a `display` field the first text `name|title|label|
+   displayName` is the title.
+
+`deriveScreenFields` uses them: a text field with an `enum` is kind `select`
+(`options`), money comes from the roles, and every `ScreenField` carries
+`roles`. `formatScreenValue` shows `format: 'date'` without a time and
+`format: 'percent'` as a percentage. Helpers: `fieldsWithRole`,
+`fieldWithRole`, `isDocumentLike` (identifier plus party or total),
+`hasLineItemRoles` (quantity plus money). Columns by role are
+`screens/columns.ts`: `relatedColumns` (identifier or title, status, lead
+date, party, amount) and `lineItemColumns` (item, quantity, unit price —
+`summarize: false` —, amount).
+
+## Relations (`relations.ts`)
+
+`deriveScreenRelations(definitions, model)` is the pure, Node-tested rule for
+what a record view shows around a record. `definitions` is every exposed
+collection definition keyed by collection name (`collectionDefinitions` from
+`@smrt/web`); `model` is a qualified `objectRef` (or a key of the map). It
+reads the generated `relationships` edges (`ScreenRelationshipDefinition`:
+`field`, `kind`, `relatedCollection` — a collection **name**, resolved by map
+key, then by `name`), so a definition without `relationships` has no
+relations. A `ScreenRelation` is `{ model, field, label, kind, columns?, sort? }`
+(`relationKey(relation)` = `Order-customerId`):
+
+| `kind` | Meaning | `model` | `field` | `label` |
+|---|---|---|---|---|
+| `children` | another collection with a `foreignKey` / `crossPackageRef` edge targeting this model | the child's `objectRef` | the FK on the child | the child's plural title; two FKs to the same parent disambiguate as `Orders (Approver)` |
+| `items` | a `children` edge marked `relationships[].role: 'items'` (core `@foreignKey(T, { role: 'items' })`), or a child with line-item roles and one FK here | as `children` | as `children` | as `children` |
+| `reference` | one of this model's own FK edges | the target's `objectRef` | the FK on this model | the field label (`ownerId` -> `Owner`) |
+
+`items` come first, then `children`, each sorted by label, then `reference`
+in declaration order. `children` carry `relatedColumns`, `items`
+`lineItemColumns` and a line `sort` (`sortOrder`, `position`, `lineNumber`,
+`sequence`, else `createdAt`).
+Edges whose target or source is not in `definitions` are skipped (an unexposed
+model has no route to link to), as are `oneToMany` / `manyToMany` edges and
+edges whose field the definition does not carry.
+
+## RecordScreen (`RecordScreen.svelte`, `./screens`)
+
+The record page: a header, a details card, a customizable `OverviewGrid`
+below, and the edit form as a **mode** of the same screen. Props are
+`RecordScreenProps` in `types.ts`.
+
+- **Header anatomy (`RecordHeader.svelte`, model `deriveRecordHeader` in
+  `record-header.ts`).** A small back link above the title; the heading is
+  `title`, else a document's kind and identifier ("Order GRA-3159",
+  identifier monospace — never the party), else the title-role field, else
+  the identifier, else the class name; a non-document's identifier shows as
+  a monospace chip; the status is a `Badge` toned by value (`statusTones`,
+  else `DEFAULT_STATUS_TONES`, else neutral); two to four key facts by role
+  (party link, lead date shown date-only, total money, then email / phone).
+  It reads only the view fields, so a field the policy omits never reaches
+  the header. Actions: Edit is the one primary button (hidden while
+  editing); a "More actions" popover holds `extraActions` and Delete, which
+  still confirms.
+- **Details card.** `DetailScreen` with `variant="card"`, `hideEmpty` (empty
+  fields behind "Show empty fields (n)") and `exclude`: what the header
+  shows, the currency-code field, and — when the model has an `items`
+  relation — the subtotal / discount / tax / total role fields, which the
+  line-items totals block shows instead. `children` render inside the card.
+- **Body = `recordOverview(definition, relations)`** unless an `overview` is
+  passed: the summary strip, `line-items`, then `related` (see
+  [overview-surfaces.md](overview-surfaces.md#record-overviews-recordts)),
+  persisted **per model kind** under `recordOverviewId(objectRef)`
+  (`detail:acme.shop.Customer`). The grid renders `presentation="plain"`,
+  follows the shell's layout editor unless `layoutEditing` is passed, and
+  offers the child models in its add dialog. `override` / `onoverviewchange`
+  are the host-owned persistence pair of `createOverview`
+  (`@happyvertical/smrt-preferences`, kind `overview`, in production); omit
+  `override` to keep edits in memory. With `loaders.records` the screen also
+  registers `related` and `line-items` (`registerRecordWidgets`) with the
+  record's totals (`recordTotals`) and currency.
+- **Loaders run in the browser with the record context.** `loaders`
+  (`CoreWidgetLoaders`) are registered on a registry of the screen's own
+  (or pass `registry` with recipe widgets on it); each `load` receives
+  `widgetContext` extended with `overviewId`, the `signal`, `locale` and
+  `record: { model: definition.objectRef, id }`, and honours `filter:
+  'parent'` + `field` as overview-surfaces.md describes. A widget without a
+  loader is not registered, so a default needing it is dropped (reported,
+  never an error); without `loaders` the grid is empty. A record change
+  reloads every panel; the registry and overview are fixed at mount, so
+  remount (`{#key}`) to change the model kind — `RecipeScreens` keys on
+  `definition.objectRef`.
+- **One heading per related panel.** A `records` widget whose `model` +
+  `field` + `filter: 'parent'` match a `children` relation (user-added ones
+  included) is headed `Orders · 3` (the loader's `total`, else its row count)
+  with the panel's only "View all": `viewAllHref(relation)`, else the loaded
+  `href`. The screen strips `total` / `href` from that widget's data, so the
+  body never repeats them. A `metric` widget keeps the plain title and no
+  link (its number links when its data has an `href`).
+- **Edit form.** `EditForm` edits a `select` field with a smrt-ui `Select`
+  (humanized choices, "Not set" unless required, an out-of-list stored value
+  kept). `derivedFields` render read-only and formatted with "Worked out
+  from the line items." and are never in the payload; `RecordScreen` passes
+  its `derivedFields` prop, else the totals role fields when an `items`
+  relation exists. `items?: Snippet` (the host's line-items editor) renders
+  under the form, in the edit column on desktop and inside the edit sheet on
+  phones.
+- **`mode: 'edit'`** keeps the detail rendered and adds `EditForm`
+  (`showHeader={false}`, keyed by record id, `fieldErrors` / `error` /
+  `submitting` / `onsave` as `EditFormProps`): on desktop (`min-width: 48rem`,
+  a `matchMedia` the screen watches; the server renders desktop) a sticky
+  `<aside>` in a `minmax(0, 1fr) minmax(20rem, 28rem)` grid beside the header,
+  sliding in with `--smrt-duration-medium1` / `--smrt-easing-standard` and
+  still under `prefers-reduced-motion`; on phones a `PhoneSheet
+  variant="page"` in a fixed full-screen `<section>` the screen owns (an
+  `AdminShell`'s `overlays` snippet is a shell prop a screen cannot reach, so
+  the screen stacks its own at `--smrt-z-index-modal`). The sheet stays
+  mounted while closed so it animates open; the form inside mounts only in
+  edit mode, so Cancel never keeps a stale draft. Cancel, the sheet's close
+  button and Escape all call `oncancel`; the detail's Edit action hides while
+  editing. `RecipeScreens` maps `onedit` to `navigate('edit', id)` and
+  `oncancel` / a saved `onsave` back to `view`.
+- Strings: `ui.screens.view_all`, `ui.screens.related`, `more_actions`,
+  `details`, `show_empty`, `derived_hint`, `select_none`, `items`, and the
+  existing `ui.screens.edit_title` for the aside and sheet heading.
+- Tests: `__tests__/roles.test.ts`, `__tests__/record-header.test.ts`,
+  `__tests__/relations.test.ts`, `__tests__/RecordScreen.test.ts` (header
+  anatomy, overflow Delete, details exclusions, line items and the mismatch
+  flag, derived fields and the items slot on both layouts, axe
+  in view and both edit layouts, the record context reaching every loader,
+  "View all" hrefs, host-owned override edits, record change reload) and the
+  link cases in `__tests__/DetailScreen.test.ts`; `overview/__tests__/record.test.ts`
+  and the parent-context case in `overview/__tests__/load.test.ts`.

package/dist/components/command-palette/CommandPaletteDialog.svelte

@@ -306,7 +306,7 @@ const inputLabel = $derived(label ?? t(M['ui.command_palette.input_label']));
     display: flex;
     align-items: center;
     gap: 0.75rem;
-    min-block-size: max(2.5rem, var(--smrt-control-target-min, 0px));
+    min-block-size: max(2.5rem, var(--smrt-control-target-min));
     padding: 0.375rem 0.75rem;
     border-radius: var(--smrt-radius-medium, 0.5rem);
     color: var(--smrt-color-on-surface);

package/dist/components/overview/OverviewGrid.svelte

@@ -33,12 +33,17 @@ import type { OverviewOpResult } from './controller.svelte.js';
 import type { OverviewGridProps } from './grid-types.js';
 import { spanFromKey, spanFromPointer } from './resize.js';
 import { defaultWidgetOptions } from './schema.js';
-import type { OverviewOptions, OverviewWidget } from './types.js';
+import type {
+  OverviewOptions,
+  OverviewWidget,
+  WidgetOptionIssue,
+} from './types.js';
 import WidgetOptionsForm from './WidgetOptionsForm.svelte';
 
 let {
   controller,
   components,
+  optionEditors,
   editing: editingProp,
   label,
   headingLevel = 2,
@@ -299,9 +304,7 @@ function chooseType(type: string): void {
   }
 }
 
-function saveOptions(
-  options: OverviewOptions,
-): { key: string; code: string }[] | null {
+function saveOptions(options: OverviewOptions): WidgetOptionIssue[] | null {
   const current = configure;
   if (!current) return null;
   const result: OverviewOpResult =
@@ -531,6 +534,7 @@ const headingTag = $derived(`h${headingLevel}`);
           definition={configureDef}
           initial={configure.initial}
           {models}
+          optionsEditor={optionEditors?.get(configure.type) ?? configureDef.optionsEditor}
           onsave={saveOptions}
           oncancel={() => (configure = null)}
         />

package/dist/components/overview/OverviewGrid.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OverviewGrid.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/overview/OverviewGrid.svelte.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AA6bzD,QAAA,MAAM,YAAY,uDAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}
+{"version":3,"file":"OverviewGrid.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/overview/OverviewGrid.svelte.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAgczD,QAAA,MAAM,YAAY,uDAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}

package/dist/components/overview/WidgetOptionsForm.svelte

@@ -23,8 +23,14 @@ import { M } from '../../i18n/strings.overview.js';
 import type { WidgetOptionsFormProps } from './grid-types.js';
 import type { OverviewOptions, WidgetOptionField } from './types.js';
 
-let { definition, initial, models, onsave, oncancel }: WidgetOptionsFormProps =
-  $props();
+let {
+  definition,
+  initial,
+  models,
+  onsave,
+  oncancel,
+  optionsEditor,
+}: WidgetOptionsFormProps = $props();
 
 const { t } = useI18n();
 
@@ -108,8 +114,12 @@ const optionalChoice = (field: WidgetOptionField): boolean =>
 const modelValues = $derived(
   new Set((models ?? []).map((model) => model.value)),
 );
+const CustomEditor = $derived(optionsEditor ?? definition.optionsEditor);
 </script>
 
+{#if CustomEditor}
+  <CustomEditor {definition} {initial} {models} {onsave} {oncancel} />
+{:else}
 <Form onsubmit={submit} novalidate>
   {#if failed}
     <Alert variant="error">{t(M['ui.overview.options_failed'])}</Alert>
@@ -184,6 +194,7 @@ const modelValues = $derived(
     </Button>
   </FormActionBar>
 </Form>
+{/if}
 
 <style>
 @layer smrt.reset, smrt.structure, smrt.theme;

package/dist/components/overview/WidgetOptionsForm.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WidgetOptionsForm.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/overview/WidgetOptionsForm.svelte.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AA8J9D,QAAA,MAAM,iBAAiB,4DAAwC,CAAC;AAChE,KAAK,iBAAiB,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC9D,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"WidgetOptionsForm.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/overview/WidgetOptionsForm.svelte.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAyK9D,QAAA,MAAM,iBAAiB,4DAAwC,CAAC;AAChE,KAAK,iBAAiB,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC9D,eAAe,iBAAiB,CAAC"}

package/dist/components/overview/format.d.ts

@@ -1,13 +1,4 @@
-export type WidgetValueFormat = 'integer' | 'decimal' | 'percent' | 'money';
-export interface FormatWidgetValueOptions {
-    format?: WidgetValueFormat;
-    /** ISO 4217 code for `money` (default USD). */
-    currency?: string;
-    locale: string;
-}
-/**
- * Format a metric value. `money` takes integer minor units, `percent` takes a
- * fraction (0.25 is 25%). Non-finite input renders as an en dash.
- */
-export declare function formatWidgetValue(value: unknown, { format, currency, locale }: FormatWidgetValueOptions): string;
+/** Shared number formatting; money values are integer minor units. */
+export type { FormatWidgetValueOptions, WidgetValueFormat, } from '@happyvertical/smrt-ui/charts/format';
+export { formatWidgetValue } from '@happyvertical/smrt-ui/charts/format';
 //# sourceMappingURL=format.d.ts.map

package/dist/components/overview/format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/components/overview/format.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAE5E,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAYD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,EAAE,MAAkB,EAAE,QAAgB,EAAE,MAAM,EAAE,EAAE,wBAAwB,GACzE,MAAM,CA4BR"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/components/overview/format.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,YAAY,EACV,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC"}

package/dist/components/overview/format.js

@@ -1,45 +1,2 @@
-/**
- * Number formatting for overview widgets (#3727). Deterministic for a given
- * locale so a server render and the client hydrate to the same text. Money is
- * integer minor units end to end (never a decimal in data).
- */
-import { currencyMinorDigits } from '../screens/values.js';
-const EN_DASH = '–';
-function safeLocale(locale) {
-    try {
-        return Intl.getCanonicalLocales(locale)[0] ?? 'en';
-    }
-    catch {
-        return 'en';
-    }
-}
-/**
- * Format a metric value. `money` takes integer minor units, `percent` takes a
- * fraction (0.25 is 25%). Non-finite input renders as an en dash.
- */
-export function formatWidgetValue(value, { format = 'integer', currency = 'USD', locale }) {
-    if (typeof value !== 'number' || !Number.isFinite(value))
-        return EN_DASH;
-    const tag = safeLocale(locale);
-    switch (format) {
-        case 'money': {
-            const code = /^[A-Za-z]{3}$/.test(currency)
-                ? currency.toUpperCase()
-                : 'USD';
-            const digits = currencyMinorDigits(code);
-            return new Intl.NumberFormat(tag, {
-                style: 'currency',
-                currency: code,
-            }).format(value / 10 ** digits);
-        }
-        case 'percent':
-            return new Intl.NumberFormat(tag, {
-                style: 'percent',
-                maximumFractionDigits: 1,
-            }).format(value);
-        case 'decimal':
-            return new Intl.NumberFormat(tag, { maximumFractionDigits: 2 }).format(value);
-        default:
-            return new Intl.NumberFormat(tag, { maximumFractionDigits: 0 }).format(value);
-    }
-}
+/** Shared number formatting; money values are integer minor units. */
+export { formatWidgetValue } from '@happyvertical/smrt-ui/charts/format';