@happyvertical/smrt-svelte 0.55.22 → 0.55.24

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

@@ -113,10 +113,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 +213,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 +235,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
@@ -250,7 +324,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 +449,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/overview/index.d.ts

@@ -18,9 +18,12 @@ export * from './server.js';
 export { default as WidgetOptionsForm } from './WidgetOptionsForm.svelte';
 export { default as ChartWidget } from './widgets/ChartWidget.svelte';
 export { type CoreWidgetLoaders, createChartWidget, createMetricWidget, createNoteWidget, createRecordListWidget, createShortcutsWidget, registerCoreWidgets, } from './widgets/core.js';
-export { type ChartWidgetData, type MetricWidgetData, type RecordListWidgetData, type ShortcutEntry, type ShortcutNavSection, type ShortcutsWidgetData, shortcutsFromNav, } from './widgets/data.js';
+export { type ChartWidgetData, type LineItemsWidgetData, type MetricWidgetData, type RecordListColumn, type RecordListRow, type RecordListWidgetData, type RecordStatusTone, type RelatedWidgetData, type RelatedWidgetTab, type ShortcutEntry, type ShortcutNavSection, type ShortcutsWidgetData, shortcutsFromNav, } from './widgets/data.js';
+export { default as LineItemsWidget } from './widgets/LineItemsWidget.svelte';
 export { default as MetricWidget } from './widgets/MetricWidget.svelte';
 export { default as NoteWidget } from './widgets/NoteWidget.svelte';
 export { default as RecordListWidget } from './widgets/RecordListWidget.svelte';
+export { default as RelatedWidget } from './widgets/RelatedWidget.svelte';
+export { createLineItemsWidget, createRelatedWidget, registerRecordWidgets, } from './widgets/record-widgets.js';
 export { default as ShortcutsWidget } from './widgets/ShortcutsWidget.svelte';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/overview/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,KAAK,4BAA4B,EACjC,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,GACzB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,KAAK,wBAAwB,EAC7B,iBAAiB,EACjB,KAAK,iBAAiB,GACvB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,SAAS,EACd,KAAK,UAAU,EACf,aAAa,EACb,QAAQ,GACT,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,OAAO,IAAI,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAClF,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC3D,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,OAAO,IAAI,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC1E,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,EACL,KAAK,iBAAiB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAChF,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/overview/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,KAAK,4BAA4B,EACjC,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,GACzB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,KAAK,wBAAwB,EAC7B,iBAAiB,EACjB,KAAK,iBAAiB,GACvB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,SAAS,EACd,KAAK,UAAU,EACf,aAAa,EACb,QAAQ,GACT,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,OAAO,IAAI,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAClF,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC3D,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,OAAO,IAAI,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC1E,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,EACL,KAAK,iBAAiB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAC9E,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAChF,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC1E,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,kCAAkC,CAAC"}

package/dist/components/overview/index.js

@@ -18,7 +18,10 @@ export { default as WidgetOptionsForm } from './WidgetOptionsForm.svelte';
 export { default as ChartWidget } from './widgets/ChartWidget.svelte';
 export { createChartWidget, createMetricWidget, createNoteWidget, createRecordListWidget, createShortcutsWidget, registerCoreWidgets, } from './widgets/core.js';
 export { shortcutsFromNav, } from './widgets/data.js';
+export { default as LineItemsWidget } from './widgets/LineItemsWidget.svelte';
 export { default as MetricWidget } from './widgets/MetricWidget.svelte';
 export { default as NoteWidget } from './widgets/NoteWidget.svelte';
 export { default as RecordListWidget } from './widgets/RecordListWidget.svelte';
+export { default as RelatedWidget } from './widgets/RelatedWidget.svelte';
+export { createLineItemsWidget, createRelatedWidget, registerRecordWidgets, } from './widgets/record-widgets.js';
 export { default as ShortcutsWidget } from './widgets/ShortcutsWidget.svelte';

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

@@ -0,0 +1,51 @@
+/**
+ * The default overview of a record view (#3718 record page), persisted per
+ * model kind under `detail:<model>`: a summary strip of `metric` tiles
+ * (a count per related relation, and the sum of its money column where it
+ * has one), then the `line-items` table and totals when the model has an
+ * `items` relation, then one tabbed `related` widget over the `children`
+ * relations. Every piece is an ordinary widget, so a person can remove,
+ * move or replace it from the layout editor; `related: 'panels'` keeps the
+ * earlier one `records` panel per relation.
+ *
+ * Svelte-free. The widgets use the parent-filter vocabulary: `filter:
+ * 'parent'` plus the FK on the child (`field` for a count or a records
+ * panel; `parentField` when `field` is the measured one) confine the
+ * host's query to rows that point at `ctx.record.id`. `related` and
+ * `line-items` load through the host's `records` loader
+ * (`registerRecordWidgets`), so the shell's own loaders need no data access.
+ */
+import type { ScreenRelation } from '../screens/relations.js';
+import type { ScreenCollectionDefinition } from '../screens/types.js';
+import type { OverviewDefinition } from './types.js';
+export interface RecordOverviewOptions {
+    /** Overview id; defaults to `recordOverviewId(definition.objectRef)`. */
+    id?: string;
+    /** The summary strip of `metric` tiles (default on). */
+    metrics?: boolean;
+    /** Most tiles in the strip (default {@link RECORD_OVERVIEW_MAX_METRICS}). */
+    maxMetrics?: number;
+    /**
+     * `tabs` (default): one `related` widget with a tab per relation.
+     * `panels`: one `records` panel per relation, with role-chosen columns.
+     */
+    related?: 'tabs' | 'panels';
+}
+/** Widget types a record overview offers by default. */
+export declare const RECORD_OVERVIEW_ALLOWED: readonly string[];
+/** Tiles in the default summary strip. */
+export declare const RECORD_OVERVIEW_MAX_METRICS = 4;
+/** Rows a default `records` panel shows. */
+export declare const RECORD_OVERVIEW_LIMIT = 5;
+/**
+ * `detail:<model>` as an overview id. A qualified model id
+ * (`@acme/shop:Customer`) carries characters an overview id cannot
+ * (`OVERVIEW_PAGE_ID_PATTERN`), so `@`, `/` and `:` fold to dots:
+ * `detail:acme.shop.Customer`. Stable per model kind.
+ */
+export declare function recordOverviewId(model: string): string;
+/** Span of a default `records` panel: two side by side on a wide page. */
+export declare const RECORD_OVERVIEW_PANEL_SPAN = 2;
+/** The default record overview of `definition` for its relations. */
+export declare function recordOverview(definition: ScreenCollectionDefinition, relations: readonly ScreenRelation[], options?: RecordOverviewOptions): OverviewDefinition;
+//# sourceMappingURL=record.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../../src/components/overview/record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAEtE,OAAO,KAAK,EAAE,kBAAkB,EAAkB,MAAM,YAAY,CAAC;AAGrE,MAAM,WAAW,qBAAqB;IACpC,yEAAyE;IACzE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,wDAAwD;IACxD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;CAC7B;AAED,wDAAwD;AACxD,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAOpD,CAAC;AAEF,0CAA0C;AAC1C,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,4CAA4C;AAC5C,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOtD;AAwBD,0EAA0E;AAC1E,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C,qEAAqE;AACrE,wBAAgB,cAAc,CAC5B,UAAU,EAAE,0BAA0B,EACtC,SAAS,EAAE,SAAS,cAAc,EAAE,EACpC,OAAO,GAAE,qBAA0B,GAClC,kBAAkB,CAgGpB"}