@ai-matrx/records-ui 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Changelog — @ai-matrx/records-ui
+
+## 0.3.1
+
+Ships the canonical `TablesHome`, `TablePage`, `RecordsMount`, and table-creation helpers
+that were added after 0.3.0 was tagged. The real-store demo now shares the package-wide
+verification lock, and the packed-artifact canary verifies `@ai-matrx/records-ui` itself
+instead of accidentally re-verifying the headless `@ai-matrx/records` package.
+
+**Consumer action:** replace temporary workspace or source references with
+`@ai-matrx/records-ui@latest`; no API rename is required.
+
+## 0.3.0
+
+**The last eight, and the package is complete at thirty-one components.**
+
+`RecordChat` (SCR-26) reuses the platform's ONE chat surface instead of shipping
+a second: it builds the context — the record through the read door, each value
+carrying its Field's unit and format, the masked fields named, the `secret` and
+`on_demand` ones held back with the reason — and hands it to a new `chat` port
+that matrx-frontend fills with `AgentConversationColumn`.
+
+`EnrichPanel` (SCR-27) drives per-field AI fill off the Fields' own
+`source = agent` and `review_interval_days`, dates each value from its own
+envelope rather than the row, shows VAL-8 provenance on every value (including
+which person an agent acted for), and sends the fill through the server's
+`records` tool via a new `enrich` port — because a browser stamping itself
+`agent` would be a browser claiming to be one.
+
+`ChecklistRunner` (SCR-28) instantiates a declarative template as REAL RECORDS
+in one act. `BookingSlots` (SCR-29) holds the slot before it takes the details
+and lets the database decide a double-booking. `CaptureSheet` (SCR-30) is the
+offline capture contract: the client mints the id before the first attempt and
+`custom.anon_capture` deduplicates every replay onto the same record.
+
+`PortalShell` (SCR-23), `PublicViewPage` (SCR-24) and `EmbedFrame` (SCR-25) are
+the outsider's three surfaces, over `iam`'s external principal and publish
+binding and over the embed token handshake.
+
+New host ports: `chat`, `enrich`, `captureQueue`. Requires
+`@ai-matrx/records` 0.3.0.
+
+**A RACE EVERY SEED-TAKING COMPONENT HAD, closed as a class.** `DocTemplate`,
+`ViewBar`, `FormBuilder`, `DashboardCanvas` and `ActionInbox` all read what
+exists, worked out what was missing, and wrote it — from a loader whose identity
+changes when its inputs settle. Against a slower store the second run read a
+list the first was still writing into, and seeded the same thing twice: two
+identical "Agreement" templates, two buttons with one name. A check against the
+server's list is not a lock. `useSeedGuard` claims each seed name once per
+mount, and all five now use it.
+
+**Four more defects this wave found and closed.** `FormRunner` told every person that
+a public form's link was "pending" for a door named `custom.anon_record_write`
+that never existed, while the real anonymous lane had shipped — it now names
+`custom.anon_write` and tells a person the true next step (issue an embed). And
+the demo harness read a rehearsal copy that was missing a third of the doors
+this package now calls; it reads the one live store, and stands its own table,
+fields and records up rather than depending on rows somebody typed once. The
+two vocabulary drifts behind `RecordChat`'s context rules — a Field's
+sensitivity words and its context-policy words — were corrected in
+`@ai-matrx/records` 0.3.0; `RecordChat` holds back `confidential` and
+`restricted` values and FLD-12's `exclude` and `on_request` fields, and names
+every one of them rather than letting an agent answer around a gap.
+
+## 0.2.0
+
+`DocTemplate`, `DocRender` and `SignBlock` (SCR-20/21/22): a template is saved
+through `custom.doc_template_save`, a render is frozen once and printed through
+`@ai-matrx/print`, and a signature is checked against the exact bytes that were
+signed (`custom.doc_signature_intact`). A token the Table cannot answer is named
+before anything is rendered.
+
+Every component now reads through `@ai-matrx/records` 0.2.0's read door, so a
+row is the store's masked document and a masked field is present-and-null with
+its own reason. `useRecordVersion` reads the edited record's version from
+`custom.io_revisions`, and `useSystemTable` adds Fields a package Table grew to
+organizations that already hold a copy.
+
+One store defect was found by wiring this and fixed on the main database:
+`custom.read_record` refused records `custom.read_records` had just listed,
+because the one-record door asked a narrower question than its own list sibling.
+It now asks `iam.has_access_for`, the platform's one access question
+(`matrx-frontend/migrations/campaign/w6_ui_the_read_door_asks_the_one_access_question.sql`).
+
+## 0.1.0
+
+First release: `Grid`, `RecordForm`, `FieldEditor`, `TableSettings`,
+`RelationPicker`, `Peek`, `ImportWizard`, `ExportMenu` and
+`CustomFieldsSection`, plus the `RecordsUiProvider` rights port and the shared
+refusal surface. Every one of them is proven headlessly against the rehearsal
+branch by `pnpm test`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Matrix Engine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+# @ai-matrx/records-ui
+
+THE canonical screens of the AI Matrx record store. Every component here reads
+and writes ONLY through [`@ai-matrx/records`](../records/README.md), renders
+with `@ai-matrx/design-system`'s own primitives and data table, and carries
+`@ai-matrx/alchemy`'s menu where a person reaches for one.
+
+There is no bespoke per-feature record UI in this platform. A feature that needs
+a grid, a form, a picker or a peek mounts one of these — and any one usage is a
+few lines.
+
+## Bind once
+
+```tsx
+import { RecordsProvider } from "@ai-matrx/records/react";
+import { RecordsUiProvider } from "@ai-matrx/records-ui";
+import "@ai-matrx/design-system/styles.css";
+
+<RecordsProvider config={{ dataSource: supabase, organizationId, actor: { actor: "user", user_id } }}>
+  <RecordsUiProvider value={{ rights: (table) => myRights(table), density: "condensed" }}>
+    {children}
+  </RecordsUiProvider>
+</RecordsProvider>;
+```
+
+`rights` is the port that decides whether a person sees the administering
+controls. Unbound, it answers "no" WITH A REASON, and every such control is
+ABSENT — this package ships no disabled variant of any of them.
+
+## Then, a few lines each
+
+```tsx
+import {
+  Grid, RecordForm, FieldEditor, TableSettings, RelationPicker,
+  Peek, ImportWizard, ExportMenu, CustomFieldsSection,
+} from "@ai-matrx/records-ui";
+
+<Grid tableId={id} onOpenRecord={setPeeking} onAddField={openSettings} />           // records as rows, fields as columns
+<RecordForm tableId={id} />                                                          // create, generated from the Field records
+<RecordForm tableId={id} recordId={recordId} />                                      // edit, with the conflict shown when someone wins
+<Peek tableId={id} recordId={recordId} onClose={close} />                            // any custom table's record, no per-table code
+<TableSettings tableId={id} />                                                       // rename · reorder · retype · delete
+<FieldEditor tableId={id} field={field} />                                           // one Field's type, rules and sensitivity
+<ImportWizard tableId={id} onProposeField={propose} />                               // map columns, preview rows, propose the rest
+<ExportMenu tableId={id} label="Deals" />                                            // CSV · XLSX · Alchemy
+<CustomFieldsSection tableId={entityTableId} recordId={record.id} />                 // THE one line a standard entity page adds
+```
+
+`RelationPicker` is used by `RecordForm` automatically for any `relation` field;
+mount it directly when a screen needs just the picker.
+
+## Views, the queue, history and comments
+
+```tsx
+<ViewBar tableId={id} onActiveView={setView} seed={[{ name: "By stage", subject: id, layout: "kanban", groupField: "stage" }]} />
+<ViewSwitcher view={view} />                                                         // grid · kanban · calendar · gallery, one membership Rule
+<ActionInbox tableId={id} seed={[...]} />                                            // approvals, assignments and agent proposals, one queue
+<HistoryPanel tableId={id} recordId={recordId} />                                    // the timeline IS the record; undo is the store's soft delete
+<CommentThread tableId={id} recordId={recordId} />                                   // a comment is a record
+<FormBuilder tableId={id} seed={[form]} />  <FormRunner form={form} />               // a form is a view on a real Table
+<DashboardCanvas tableId={id} seed={[dashboard]} />  <ChartBlock spec={chart} />     // every block is one `record_aggregate`
+<NotifyRuleEditor tableId={id} />                                                    // a subscription is a Rule record over a saved view
+<DocTemplate tableId={id} seed={[tpl]} />  <DocRender templateId={t} recordId={r} /> // tokens resolved by the store
+<SignBlock tableId={id} recordId={r} render={render} />                              // the signature is checked against the exact bytes
+```
+
+## Talking to a record, and letting an agent keep it filled
+
+```tsx
+<RecordChat tableId={id} recordId={recordId} />                                      // the HOST's chat surface, this record as its context
+<EnrichPanel tableId={id} recordId={recordId} />                                     // per-field AI fill, freshness and provenance
+```
+
+`RecordChat` ships **no chat UI**. AI Matrx has exactly one — matrx-frontend's
+`AgentConversationColumn` — and it reads that app's Redux store, so a package
+that imported it would stop being a package and a second one here would drift
+within a month. `RecordChat` builds the part only the record store can build:
+the record read through the read door, each value carrying its Field's unit and
+format (the agent is given `$48,000`, never a bare `48000`), the fields the
+store MASKED named out loud, and the `secret` and `on_demand` ones held back
+with the reason. Then it hands that to the `chat` port:
+
+```tsx
+<RecordsUiProvider value={{
+  chat: (ctx) => {
+    const { conversationId } = useAgentLauncher(agentId, {
+      surfaceKey: ctx.surfaceKey,
+      runtime: { context: Object.fromEntries(ctx.entries.map((e) => [e.key, e.value])) },
+    });
+    return <AgentConversationColumn conversationId={conversationId} surfaceKey={ctx.surfaceKey} />;
+  },
+}}>
+```
+
+Resolve the agent through a **Mandate**, never a pinned UUID. Unbound, the panel
+is absent with its reason and draws no composer.
+
+`EnrichPanel` reads which Fields an agent keeps filled from the Fields
+themselves (`source = agent`) and how often from `review_interval_days`, and
+dates each value off its own envelope — never off the row's `updated_at`, which
+would call every field stale because one of them changed. The fill itself goes
+through the **server's `records` tool**, because a write stamped actor `agent`
+on behalf of a person can only honestly be made by the server:
+
+```tsx
+<RecordsUiProvider value={{
+  enrich: (ask) => fetch("/api/ai/tools/execute", { method: "POST", body: JSON.stringify({
+    tool_name: "records", surface: "records-ui:enrich",
+    arguments: { action: "record_write", record_id: ask.recordId, values: {/* the agent's answers */} },
+  })}).then((r) => r.json()).then((r) => ({ ok: r.ok, message: r.output })),
+}}>
+```
+
+Two live switches sit in front of that call today and the panel names both
+rather than spinning: the knob `custom/code_paths_enabled` resolves false, and
+the `records` row in `tool.binding` is `is_active = false`.
+
+## Work: checklists, bookings and a phone with no signal
+
+```tsx
+<ChecklistRunner tableId={id} seed={[{ name: "Onboarding", subject: id, steps: [{ title: "Confirm the address" }] }]} />
+<BookingSlots tableId={id} form={bookingForm} availability={{ fromHour: 9, toHour: 17, everyMinutes: 60, days: 5 }} />
+<CaptureSheet tableId={id} readingField="amount" noteField="title" />
+```
+
+`ChecklistRunner` makes every step a **real record** — assignable, commentable,
+exportable, historied — and the whole graph is created in ONE act
+(`custom.work_template_instantiate` judges it before writing any of it), so a
+half-made checklist is not a state this store can be in. The states and the
+moves offered come from `custom.work_states()`; a move the store does not list
+as next is not shown greyed out, it is not there.
+
+`BookingSlots` holds the slot **first** and takes the details second — taking
+details first is how two people fill in a form and one of them finds out at the
+end. One hold per slot is a UNIQUE INDEX in the database, not a check this
+screen makes, so the loser of a race reads the database's own sentence naming
+the index that refused it. Holds live in a slots Table the component declares
+through `custom.work_slots_declare`; if the store cannot build that index it
+refuses, and this screen shows the refusal rather than a picker that would sell
+the same hour twice.
+
+`CaptureSheet` is the offline capture contract, and both halves matter: the
+**client mints the id** the moment a person hits Capture — offline, before the
+first attempt, never re-minted on retry — and **the store dedupes on it**, so a
+reconnecting phone that fires the same capture thirty times writes one record
+and gets the same id back every time. Bind `captureQueue` to keep the queue
+across a reload; unbound, it is in memory for the life of the page and says so.
+
+## Outsiders: a portal, a public page, an embed
+
+```tsx
+<PortalShell tableId={id} form={intakeForm} />                                       // their list, their record, their form
+<PublicViewPage slug={params.slug} />                                                // a signed-out visitor's page
+<EmbedFrame tableId={id} formId={formId} embedUrl="https://app.example/embed" />     // issue the token
+const { binding, error } = useEmbedHandshake({ secret, requiredMode: "read" });       // and verify it, inside the iframe
+```
+
+`PortalShell` asks `iam` who the person is rather than deciding for itself:
+"external" means no membership of a **non-personal** organization, because
+signup mints everyone a personal one and the other reading makes nobody
+external. What they reach is `iam.external_principal_reach` — exactly the
+resource ids Visibility handed them, one at a time, never "their
+organization's records".
+
+`PublicViewPage` renders a publish binding, and **a share is not a publish**: an
+address nobody made, one that was revoked, and one whose lane closed all resolve
+to the same nothing, because an address that answered differently for a revoked
+binding would be an existence oracle. Every read carries the store's
+"not scanned" note (D-15) — one function, so the page, the API and the admission
+row cannot drift into three different admissions. Reaching the published happy
+path needs a claimed namespace **and a verified publisher**, which is a person
+standing behind what goes on the open internet, not something a screen may forge.
+
+`EmbedFrame` mints a token through `custom.anon_token_issue`, shows the secret
+**once** (only its digest is stored), and states the rules before the refusal: a
+token carries one decision — read or write, never both — and its origin list is
+required and matched exactly, so `example.com.evil.test` fails a check a suffix
+match would pass.
+
+## What every one of them does the same way
+
+- **The store's own sentence.** A refusal is never re-worded. "Someone else
+  changed this record while you were working on it" is what the person reads,
+  because it is what the store said, and the conflict comes with it field by
+  field.
+- **Absent, never dead.** A control a person may not use is not rendered. There
+  is no disabled "+" and no greyed settings panel anywhere in this package.
+- **A Field decides its editor.** The thirteen parity types come from the store
+  (`custom.parity_field_types()`), generated into `@ai-matrx/records`. The unit
+  and the format are on the Field because they change what the value MEANS.
+- **Nothing is dropped quietly.** An unmapped import column is shown and
+  offered as a field proposal; a list that is not live says so; a door that does
+  not exist yet is named, with the lane that owes it.
+- **Dense, one-row headers, light and dark, iOS-safe**, through the design
+  system's own tokens — this package sets no colours of its own.
+
+## The demo
+
+`pnpm demo` runs every component against **the one live store**, headless, on
+this lane's own port (127.0.0.1:3005), and stands its own table, fields and
+records up the first time it runs. Its data seam is the server lane the platform
+uses today, in one transaction per request that opens the product switch, acts
+as the test identity (`test@test.com`) through the store's own doors, and sets
+every switch back before committing — so no other session ever observes one
+open. `pnpm test` renders those same pages in jsdom against that server and
+asserts what a person would see.
+
+It reads the live store deliberately: `custom.anon_*`, the embed token, the
+external principal and the publish binding exist only there, and a demo pointed
+at a rehearsal copy would answer `door_absent` for a third of this package and
+call it a finding.
+
+## The thirty-one components
+
+| | | |
+|---|---|---|
+| `Grid` | `RecordForm` | `FieldEditor` |
+| `TableSettings` | `RelationPicker` | `Peek` |
+| `ViewSwitcher` | `ViewBar` | `ImportWizard` |
+| `ExportMenu` | `CustomFieldsSection` | `ActionInbox` |
+| `ProposalRow` | `HistoryPanel` | `CommentThread` |
+| `FormBuilder` | `FormRunner` | `ChartBlock` |
+| `DashboardCanvas` | `NotifyRuleEditor` | `DocTemplate` |
+| `DocRender` | `SignBlock` | `RecordChat` |
+| `EnrichPanel` | `ChecklistRunner` | `BookingSlots` |
+| `CaptureSheet` | `PortalShell` | `PublicViewPage` |
+| `EmbedFrame` | | |
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `pnpm demo` | Every component, live on the rehearsal branch, headless |
+| `pnpm test` | The demo pages asserted headlessly |
+| `pnpm build` | tsup → `dist` (esm + cjs + d.ts), then the client boundary stamp |
+| `pnpm check:package` | build · exports agreement · publint · tarball canary |