@mulmoclaude/core 0.1.0

package/dist/collection/core/deriveAll.d.ts

@@ -0,0 +1,38 @@
+import { FormulaContext } from './derivedFormula';
+/** Minimal field shape the derive loop needs — accepts both the client
+ *  FieldSpec and the server CollectionFieldSpec. */
+export interface DerivableFieldSpec {
+    type: string;
+    /** When type === "ref": slug of the target collection. */
+    to?: string;
+    /** When type === "derived": formula evaluated against the record. */
+    formula?: string;
+}
+/** Minimal schema shape: just the ordered field map. */
+export interface DerivableSchema {
+    fields: Record<string, DerivableFieldSpec>;
+}
+export type DerivableRecord = Record<string, unknown>;
+/** Per-target-collection cache of loaded referenced records:
+ *  target collection slug → item slug → full record. Mirrors the
+ *  client's `RefRecordCache` / the server's enrichment loader. */
+export type DeriveRefRecords = Record<string, Record<string, DerivableRecord>>;
+/** Map each `ref` field's stored slug to its loaded target record (or
+ *  null when dangling / not loaded), keyed by the LOCAL field name —
+ *  the shape `evaluateDerived` reads for `<field>.<col>` derefs. */
+export declare function resolveRowRefs(schema: DerivableSchema, record: DerivableRecord, refRecords: DeriveRefRecords): NonNullable<FormulaContext["refs"]>;
+/** Evaluate every `derived` field against `base`, saturating so a
+ *  derived field can read another derived field computed in an earlier
+ *  pass (`subtotal → tax → total` converges in ≤ field-count passes).
+ *  Cycles can't loop forever — passes are bounded by the number of
+ *  derived fields and the loop breaks as soon as a pass changes
+ *  nothing. Failed formulas stay ABSENT (the UI renders them as
+ *  em-dash). Returns a copy; `base` is never mutated.
+ *
+ *  Derived keys already present in `base` are stripped before
+ *  evaluation: computed output is host-truth, never persisted-input
+ *  fallback. A record JSON can carry a stale (or forged) derived value
+ *  — raw Write/Edit, legacy data — and without the strip, a failing
+ *  formula would silently surface that value as if the host computed
+ *  it. */
+export declare function deriveAll(schema: DerivableSchema, base: DerivableRecord, refRecords: DeriveRefRecords): DerivableRecord;

package/dist/collection/core/derivedFormula.d.ts

@@ -0,0 +1,18 @@
+export interface FormulaContext {
+    /** The record being evaluated. For derived fields in the form,
+     *  this is the live draft (text + table both converted via the
+     *  same `draftToRecord` pipeline). For the main table cell,
+     *  this is the persisted item. */
+    record: Record<string, unknown>;
+    /** Resolved ref-target records for THIS row, keyed by the local
+     *  `ref` field name. The caller (which has the schema + the linked
+     *  collection's items loaded) maps each ref field's stored slug to
+     *  the full target record and passes it here, so a `<field>.<col>`
+     *  formula can read a numeric column off the referenced record
+     *  (e.g. `shares * ticker.price`). A missing key or `null` value
+     *  (unknown field / dangling slug) makes that deref evaluate to
+     *  NaN → the whole formula returns `null` → em-dash, consistent
+     *  with every other failure mode. Absent ⇒ no refs available. */
+    refs?: Record<string, Record<string, unknown> | null>;
+}
+export declare function evaluateDerived(formula: string, ctx: FormulaContext): number | null;

package/dist/collection/core/draft.d.ts

@@ -0,0 +1,18 @@
+import { CollectionFieldSpec as FieldSpec, CollectionItem, CollectionSchema } from './schema';
+import { EditState, TableRowDraft } from './uiTypes';
+/** A fresh, empty row draft for a `table` field's sub-schema. */
+export declare function emptyRow(subFields: Record<string, FieldSpec>): TableRowDraft;
+/** Build a row draft from an existing persisted row. */
+export declare function rowFromItem(item: Record<string, unknown>, subFields: Record<string, FieldSpec>): TableRowDraft;
+/** Convert a full edit draft to the record to persist. */
+export declare function draftToRecord(state: EditState, schema: CollectionSchema): CollectionItem;
+/** Normalise a raw inline-edit input (table-cell checkbox/select) to its
+ *  persisted form. Mirrors `draftToRecord`'s boolean strictness; an empty
+ *  enum selection (the placeholder option) clears the field via `undefined`. */
+export declare function coerceInlineValue(field: FieldSpec, raw: boolean | string): unknown;
+/** Build the full record to PUT for a single-cell inline edit, without
+ *  mutating `item`. A `undefined` value omits the key (enum cleared),
+ *  matching `draftToRecord`'s omission semantics. */
+export declare function buildUpdatedRecord(item: CollectionItem, key: string, value: unknown): CollectionItem;
+/** Human-readable label of the first missing required field, or null. */
+export declare function firstMissingRequiredField(draft: EditState, schema: CollectionSchema): string | null;

package/dist/collection/core/enumColors.d.ts

@@ -0,0 +1,33 @@
+import { CollectionSchema } from './schema';
+export interface EnumColorClasses {
+    /** Stat-card style: border + fill + text + hover. */
+    card: string;
+    /** Small status dot (kanban column header). */
+    dot: string;
+    /** Pill / badge / inline `<select>` fill + text (no border width). */
+    badge: string;
+    /** Border colour, paired with a `border` width class by the caller. */
+    border: string;
+}
+/** Neutral styling for the empty / Uncategorized bucket — never a palette
+ *  colour, so an unset or unknown value reads grey across every surface. */
+export declare const ENUM_NEUTRAL: EnumColorClasses;
+/** The urgent notification colour (red), matching the bell's `urgent`
+ *  severity. The first value a schema's `notifyWhen` flags reads this. */
+export declare const ENUM_ALERT: EnumColorClasses;
+/** The nudge notification colour (amber), matching the bell's `nudge`
+ *  severity. Flagged `notifyWhen` values after the first read this. */
+export declare const ENUM_NUDGE: EnumColorClasses;
+/** Classes for the enum value at `index` in its field's `values` array. A
+ *  negative index (value unset or not among the declared values) reads
+ *  neutral. */
+export declare function enumColorClasses(index: number): EnumColorClasses;
+/** Index of `value` within an enum field's declared `values`, or -1 when the
+ *  value is empty / unknown (→ neutral). */
+export declare function enumValueIndex(values: readonly string[] | undefined, value: unknown): number;
+/** Resolve a value's colour for enum field `fieldKey`:
+ *  - Notification enum (`notifyWhen` targets it): the first flagged value (in
+ *    `notifyWhen.in` order, the most urgent) reads notification red, the rest
+ *    amber, and every non-flagged value neutral grey.
+ *  - Any other enum: the standard palette by the value's declared index. */
+export declare function resolveEnumColor(schema: CollectionSchema, fieldKey: string, value: unknown): EnumColorClasses;

package/dist/collection/core/errorMessage.d.ts

@@ -0,0 +1,4 @@
+/** Normalise an unknown thrown value to a display string. The view layer's host
+ *  capabilities already return normalised `{ ok: false, error }` results, so this
+ *  only backs the defensive `catch` around an unexpected throw. */
+export declare function errorMessage(err: unknown): string;

package/dist/collection/core/itemLabel.d.ts

@@ -0,0 +1,12 @@
+import { CollectionItem, CollectionSchema } from './schema';
+/** Which field labels a record: the schema's explicit `displayField`, else the
+ *  first non-primary text-like field (so a collection without a displayField
+ *  shows e.g. the title rather than the opaque primaryKey), else null → the
+ *  caller falls back to the primary-key value. */
+export declare function labelFieldFor(schema: CollectionSchema): string | null;
+/** A record's primary-key value as a string. */
+export declare function itemIdOf(item: CollectionItem, schema: CollectionSchema): string;
+/** A record's display label: the resolved `labelField` value, else the
+ *  primary key. Pass the result of `labelFieldFor(schema)` as `labelField`
+ *  (compute it once per render rather than per item). */
+export declare function itemLabelOf(item: CollectionItem, schema: CollectionSchema, labelField: string | null): string;

package/dist/collection/core/presentCollection.d.ts

@@ -0,0 +1,13 @@
+import { ToolContext, ToolDefinition, ToolResult } from 'gui-chat-protocol';
+export declare const TOOL_NAME = "presentCollection";
+/** Render payload carried in the tool result's `data` field; the View mounts
+ *  off these. Same shape as the tool args. */
+export interface PresentCollectionData {
+    /** Slug of the collection to display (e.g. "clients", "invoices"). */
+    collectionSlug: string;
+    /** Optional primary-key value of a single item to open on mount. */
+    itemId?: string;
+}
+export type PresentCollectionArgs = PresentCollectionData;
+export declare const TOOL_DEFINITION: ToolDefinition;
+export declare const executePresentCollection: (_context: ToolContext, args: PresentCollectionArgs) => Promise<ToolResult<PresentCollectionData, PresentCollectionData>>;

package/dist/collection/core/promptSafety.d.ts

@@ -0,0 +1 @@
+export declare function defangForPrompt(value: string): string;

package/dist/collection/core/schema.d.ts

@@ -0,0 +1,355 @@
+/** Minimal "this collection is a feed" descriptor carried on the schema.
+ *  Deliberately narrow — the canonical collection contract stays
+ *  independent of the host's feeds subsystem. The host's richer retrieval
+ *  spec (`IngestSpec` in `server/workspace/feeds/ingestTypes.ts`)
+ *  `extends CollectionIngest`, so feed code reads the extra fields by
+ *  typing feed schemas with that subtype; collection rendering only needs
+ *  these three + the presence check. */
+export interface CollectionIngest {
+    kind: string;
+    url: string;
+    schedule: string;
+}
+/** Retriever kinds a Feed's `ingest.kind` may declare. The host's feeds engine
+ *  dispatches on these; they live here (with the schema contract) so the schema
+ *  validator can enforce them. The host re-exports these from
+ *  `server/workspace/feeds/ingestTypes.ts`. */
+export declare const INGEST_KINDS: readonly ["rss", "atom", "http-json"];
+export type IngestKind = (typeof INGEST_KINDS)[number];
+/** Refresh cadences a Feed's `ingest.schedule` may declare. */
+export declare const FEED_SCHEDULES: readonly ["hourly", "daily", "weekly", "on-demand"];
+export type FeedSchedule = (typeof FEED_SCHEDULES)[number];
+export type CollectionFieldType = "string" | "text" | "email" | "number" | "date" | "datetime" | "boolean" | "markdown" | "ref" | "money" | "enum" | "table" | "derived" | "embed" | "image" | "file" | "toggle";
+export type CollectionSource = "user" | "project" | "feed";
+/** Recurrence unit for a `spawn.every` advance. */
+export type CollectionRecurUnit = "day" | "week" | "month" | "year";
+/** How a `spawn` advances the source item's `triggerField` date to
+ *  produce the successor's. All arithmetic is done on the civil
+ *  (year, month, day) triple — never by adding milliseconds — so month
+ *  lengths and leap years are handled correctly. */
+export interface CollectionEvery {
+    unit: CollectionRecurUnit;
+    /** Number of `unit`s to advance (≥ 1). `interval: 3` + `unit: "month"`
+     *  = quarterly; `interval: 1` + `unit: "year"` = annual. */
+    interval: number;
+    /** Day-of-month anchor for `month`/`year` units. The CANONICAL day —
+     *  read from the rule, never re-derived from the prior concrete date,
+     *  so "31st of every month" yields 31 → 28/29 → 31 → 30 … with no
+     *  drift (it is clamped per-month at compute time, not stored
+     *  clamped). `"last"` always means the last day of the target month.
+     *  Omitted ⇒ preserve the source date's day (safe for days ≤ 28).
+     *  Ignored for `day`/`week` units. */
+    dayOfMonth?: number | "last";
+}
+/** Field-driven recurrence: the advance interval is selected PER RECORD by
+ *  the value of an `enum` field (`fromField`), looked up in `map`. Lets one
+ *  collection mix daily / weekly / monthly obligations in a single list — the
+ *  host reads `record[fromField]`, finds the matching `CollectionEvery`, and
+ *  advances by it. `fromField` must point at a top-level `enum` field whose
+ *  `values` the `map` keys exactly cover (validated at discovery), and must
+ *  itself be carried/`set` onto the successor so the chain keeps recurring. */
+export interface CollectionEveryFieldDriven {
+    /** Top-level `enum` field whose value selects the interval. */
+    fromField: string;
+    /** Interval per enum value. Keys exactly cover `fromField`'s `values`;
+     *  each value is a literal {@link CollectionEvery}. */
+    map: Record<string, CollectionEvery>;
+}
+/** The `every` of a `spawn`: either a single literal interval applied to
+ *  every record, or a per-record interval selected by an `enum` field. The
+ *  literal arm is what `advanceTriggerDate` consumes — the field-driven arm
+ *  is resolved down to one of its `map` values before the date math runs. */
+export type CollectionSpawnEvery = CollectionEvery | CollectionEveryFieldDriven;
+/** Narrowing guard: true when `every` is the field-driven arm. */
+export declare function isFieldDrivenEvery(every: CollectionSpawnEvery): every is CollectionEveryFieldDriven;
+/** Host-driven recurrence: when a record satisfies `when`, the host
+ *  creates the next record with a forward-advanced `triggerField` date.
+ *  The successor's id and contents are a pure function of (source
+ *  record, this rule); creation is create-if-absent, so the mechanism
+ *  stays convergent — observing the predicate N times writes one
+ *  successor. Requires the schema to declare `triggerField`. */
+export interface CollectionSpawn {
+    /** Predicate that fires the spawn (a `CollectionWhen`). Defaults to
+     *  "`completionField` value ∈ `completionDoneValues`" (i.e. spawn the
+     *  next instance when this one is done). */
+    when?: CollectionWhen;
+    /** How to advance `triggerField` from the source to the successor —
+     *  either a single literal interval or a per-record, field-driven map. */
+    every: CollectionSpawnEvery;
+    /** Record fields copied verbatim onto the successor. Fields not listed
+     *  here, not in `set`, and not the trigger / primary keys start
+     *  blank. */
+    carry?: string[];
+    /** Fields forced to fixed values on the successor (typically resetting
+     *  the status field to its pending value). */
+    set?: Record<string, unknown>;
+}
+/** The kind of work an action kicks off. v1 ships only `"chat"` —
+ *  start a new chat in a role with a templated seed prompt. The enum
+ *  reserves room for a future `"mutate"` (status transitions) without
+ *  another schema-shape change. */
+export type CollectionActionKind = "chat";
+/** Optional visibility predicate: the target (an action button or a
+ *  field) renders only when the open record's `field` (stringified) is
+ *  one of `in`. Generic and domain-free — the host evaluates it against
+ *  the record with no knowledge of what the field means. Absent ⇒
+ *  always shown. */
+export interface CollectionWhen {
+    /** Top-level record field key whose value gates visibility. */
+    field: string;
+    /** Allowed values; the target shows when `String(record[field])` is
+     *  one of these. Non-empty. */
+    in: string[];
+}
+/** @deprecated Name retained for back-compat; use {@link CollectionWhen}.
+ *  Both actions and fields share the same predicate shape. */
+export type CollectionActionWhen = CollectionWhen;
+/** What a custom view's capability token is allowed to do against the
+ *  collection's data endpoint. `read` returns enriched records (getItems
+ *  semantics); `write` validates-and-stores rows (putItems semantics).
+ *  There is deliberately no `delete` — a view can never do more than the
+ *  agent's own `manageCollection` tool. */
+export type CollectionViewCapability = "read" | "write";
+/** A custom (LLM-authored) HTML view for a collection. The host renders
+ *  `file` in a sandboxed iframe over the collection's records; the view
+ *  reaches its data only through a slug- and capability-scoped token (see
+ *  `server/api/auth/viewToken.ts`). Pure data — the host holds no
+ *  view-specific code; meaning lives in the HTML file + this registration. */
+export interface CollectionCustomView {
+    /** Stable id; the view-mode selector key (`custom:<id>`) and the
+     *  capability-token clamp key. Must be a valid slug. */
+    id: string;
+    /** Button label in the view-mode selector (author-authored, like field
+     *  labels — not run through i18n). */
+    label: string;
+    /** Optional Material-icon name for the selector button. */
+    icon?: string;
+    /** Skill-relative path to the HTML file under `views/` (e.g.
+     *  `views/year.html`). Path-safe, must end in `.html`. */
+    file: string;
+    /** What the view may do with the data endpoint. Defaults to `["read"]`
+     *  (least privilege); declare `["read","write"]` only for views that
+     *  edit records. The mint endpoint clamps any requested caps to this. */
+    capabilities?: CollectionViewCapability[];
+}
+/** A schema-declared, per-record action rendered as a button in the
+ *  read-only detail view. Pure UI/behaviour directive — never stored,
+ *  never validated against record data. All domain specifics (label,
+ *  role, template) live here in the schema / skill folder, so the host
+ *  stays generic. */
+export interface CollectionAction {
+    /** Stable id (used in the dispatch route + testids). */
+    id: string;
+    /** Button text (English, like field labels). */
+    label: string;
+    /** Material-icon name shown on the button. */
+    icon?: string;
+    /** What the action does. v1: `"chat"`. */
+    kind: CollectionActionKind;
+    /** `kind: "chat"`: the role id the new chat runs in. */
+    role: string;
+    /** `kind: "chat"`: skill-relative path to the template file whose
+     *  text becomes the seed prompt body (e.g. `templates/invoice.md`). */
+    template: string;
+    /** Optional visibility predicate; the button renders only when the
+     *  open record matches (see CollectionWhen). Absent ⇒ always
+     *  shown. */
+    when?: CollectionWhen;
+}
+export interface CollectionFieldSpec {
+    type: CollectionFieldType;
+    label: string;
+    /** True for the field whose value is the record's filename (no
+     *  separate auto-id). Exactly one field per schema may set this. */
+    primary?: boolean;
+    required?: boolean;
+    /** When `type === "ref"` or `type === "embed"`: the slug of the
+     *  target collection. For `ref` the record stores the target
+     *  item's primary-key slug and the host renders a clickable link
+     *  + dropdown picker. For `embed` the host pulls a *fixed* record
+     *  (see `id`) from the target and renders its fields read-only in
+     *  the detail view. Required for both; ignored on every other
+     *  type. */
+    to?: string;
+    /** When `type === "embed"`: the primary-key value of the fixed
+     *  record to pull from the `to` collection (e.g. `me` for the
+     *  singleton mc-profile). Nothing is stored on this record — the
+     *  embed is a display-only directive resolved at render time, so
+     *  it never appears in the list table or the edit form. Required
+     *  when type is `embed`; ignored on every other type. */
+    id?: string;
+    /** When `type === "money"` (or `type === "derived"` with
+     *  `display: "money"`): a literal ISO 4217 currency code passed to
+     *  `Intl.NumberFormat` for display — fixed for every record. The
+     *  stored value is always a plain decimal number; currency is
+     *  presentation only. Mutually substitutable with `currencyField`:
+     *  a money field must declare at least one of the two. */
+    currency?: string;
+    /** When `type === "money"` (or `type === "derived"` with
+     *  `display: "money"`): the name of a sibling record field whose
+     *  value holds the ISO 4217 code, letting currency vary per record
+     *  (e.g. an invoice's `currency` enum). The renderer reads
+     *  `record[currencyField]` and falls back to the literal `currency`
+     *  (then "USD") when the field is absent or empty. Resolved against
+     *  the top-level record even for money sub-fields inside a table. */
+    currencyField?: string;
+    /** When `type === "enum"`: the closed set of allowed string
+     *  values. The form renders a `<select>` populated from this
+     *  list; storage is a plain string. Required when type is
+     *  `enum`; ignored on every other type. */
+    values?: readonly string[];
+    /** When `type === "table"`: the sub-schema for each row (a flat
+     *  record of non-table / non-derived field specs). Required when
+     *  type is `table`. v0 disallows nested tables and derived
+     *  columns to keep the editor + evaluator simple. */
+    of?: Record<string, CollectionFieldSpec>;
+    /** When `type === "derived"`: a tiny expression evaluated against
+     *  the record. Supports `+ - * /`, parens, identifier refs to
+     *  top-level fields, `sum(tableField[].col)`, and
+     *  `sum(tableField[].col * tableField[].col)`. See
+     *  `src/utils/collections/derivedFormula.ts`. Required when type
+     *  is `derived`. */
+    formula?: string;
+    /** When `type === "derived"`: an inner field type the computed
+     *  value should be rendered as (e.g. `"money"` so $1,234.56 is
+     *  formatted). Defaults to `"number"`. */
+    display?: CollectionFieldType;
+    /** Optional visibility predicate: this field renders only when the
+     *  record matches (e.g. hide a `rating` field until `visited` is
+     *  `true` via `{ field: "visited", in: ["true"] }`). Applies to the
+     *  list cell (blank when hidden), the edit form (hidden live as the
+     *  gating field changes), and the detail view. Purely presentational
+     *  — a hidden field's stored value is never cleared. `when.field`
+     *  must name another top-level field. Absent ⇒ always shown. Only
+     *  honoured on top-level fields, not inside a `table`'s `of`. */
+    when?: CollectionWhen;
+    /** When `type === "toggle"`: the name of the top-level `enum` field this
+     *  checkbox projects. The toggle stores nothing itself — it reads and
+     *  writes this field. Required when type is `toggle`; ignored otherwise.
+     *  Must name a real `enum` field. */
+    field?: string;
+    /** When `type === "toggle"`: the enum value that means "checked". The
+     *  box is checked when the projected `field` equals this; checking writes
+     *  it. Required when type is `toggle`; must be one of the enum's `values`. */
+    onValue?: string;
+    /** When `type === "toggle"`: the enum value written when the box is
+     *  unchecked. Required when type is `toggle`; must be one of the enum's
+     *  `values`. */
+    offValue?: string;
+}
+export interface CollectionSchema {
+    /** Human-facing collection name (sidebar, header). */
+    title: string;
+    /** Material-icon name shown next to the title. */
+    icon: string;
+    /** Workspace-relative folder holding one-JSON-per-record. Validated
+     *  to live under the workspace root at load time. */
+    dataPath: string;
+    /** Field name whose value doubles as the record's filename. */
+    primaryKey: string;
+    /** When set, the collection is a singleton: at most one record,
+     *  whose primary key is fixed to this value (e.g. `me` for the
+     *  business profile). The host pre-fills + locks the create form's
+     *  primary key and hides Add once the record exists. */
+    singleton?: string;
+    /** Ordered map: insertion order = column order in the table view. */
+    fields: Record<string, CollectionFieldSpec>;
+    /** Optional per-record actions rendered as buttons in the detail
+     *  view (e.g. "Generate PDF"). Order = button order. */
+    actions?: CollectionAction[];
+    /** Optional collection-level actions rendered as buttons in the
+     *  collection header (e.g. "Extend the course"). Unlike `actions`,
+     *  these carry no record context: the seed prompt injects a compact
+     *  progress summary of every record instead. The `when` predicate is
+     *  not evaluated (there is no record to gate on). Order = button order. */
+    collectionActions?: CollectionAction[];
+    /** Name of the field whose value marks an item as "done". When set,
+     *  a notification fires on item create (unless the item is born done)
+     *  and clears when the field's value transitions into
+     *  `completionDoneValues`. Must name a real field in `fields`. */
+    completionField?: string;
+    /** The set of values for `completionField` that count as "done"
+     *  (e.g. `["Done"]` for a todo status field, `["paid"]` for an
+     *  invoice). Non-empty. Compared as strings. */
+    completionDoneValues?: readonly string[];
+    /** Name of the field whose value is shown as the human-readable
+     *  label in a completion notification's title (e.g. a `name` field,
+     *  so the bell reads `Contacts: Jane Doe` instead of the opaque
+     *  primaryKey). Must name a real field in `fields`. When unset — or
+     *  when the record's value for it is empty — the title falls back to
+     *  the record's primaryKey value. Display-only; never stored. */
+    displayField?: string;
+    /** Name of a `date` field that gates this item's completion
+     *  notification: the bell is suppressed until the clock reaches that
+     *  date (compared at day-granularity in the server's local timezone),
+     *  instead of firing on create. Requires `completionField` /
+     *  `completionDoneValues` (the bell still clears via the done value).
+     *  Must name a real `date` field. Absent ⇒ fire on create, as before. */
+    triggerField?: string;
+    /** Lead time in whole days: fire the bell this many days BEFORE
+     *  `triggerField` (so `10` shows the reminder 10 days early). The lead
+     *  is applied at fire time, not stored, so it composes with `spawn` —
+     *  every recurred cycle fires the same number of days before its own
+     *  trigger. Non-negative integer; requires `triggerField`. Default 0
+     *  (fire on the trigger date). */
+    triggerLeadDays?: number;
+    /** Host-driven recurrence. When set, requires `triggerField`. See
+     *  {@link CollectionSpawn}. */
+    spawn?: CollectionSpawn;
+    /** Name of a `date` field that anchors the optional calendar view: a
+     *  month grid where each record lands on the day cell matching this
+     *  field's value. When unset, the calendar toggle still appears if the
+     *  schema has any `date` field (the first one, in declaration order, is
+     *  used by default and is switchable in-view). Set this to pin a specific
+     *  anchor. Must name a real `date` field. */
+    calendarField?: string;
+    /** Name of a second `date` field marking the END of a multi-day span on
+     *  the calendar: the record renders from `calendarField` through this
+     *  date inclusive. Requires `calendarField`. Must name a real `date`
+     *  field. Absent ⇒ single-day placement. */
+    calendarEndField?: string;
+    /** Name of a string field holding a free-form time or time-range
+     *  (e.g. "14:00-17:00", "17:00-", "16:30") that places records on the
+     *  calendar's day (time-allocation) view. Consulted only when the calendar
+     *  date fields are date-only. Requires `calendarField`. */
+    calendarTimeField?: string;
+    /** Name of an `enum` field that groups records into columns on the
+     *  optional Kanban board: each record lands in the column matching its
+     *  value, with empty/unknown values collected in an "Uncategorized"
+     *  column. When unset, the Kanban toggle still appears if the schema has
+     *  any `enum` field (the first one, in declaration order, is used by
+     *  default and is switchable in-view). Set this to pin a specific group
+     *  field. Must name a real `enum` field. */
+    kanbanField?: string;
+    /** Optional custom (LLM-authored) HTML views, each rendered in a
+     *  sandboxed iframe over the records. Absent ⇒ only the built-in
+     *  field-derived views (table / calendar / kanban / dashboard). See
+     *  {@link CollectionCustomView}. */
+    views?: CollectionCustomView[];
+    /** Optional predicate that gates the completion bell: when set, the bell
+     *  fires only for records whose `String(record[notifyWhen.field])` is one
+     *  of `notifyWhen.in` (e.g. notify only `high`/`urgent` priority todos).
+     *  Reuses the `when` predicate shape. Requires `completionField` — it
+     *  narrows that bell rather than introducing a second one. The bell still
+     *  clears on done / delete / when the predicate stops matching. Absent ⇒
+     *  notify for every open record (the prior behaviour). `notifyWhen.field`
+     *  must name a real top-level field. */
+    notifyWhen?: CollectionWhen;
+    /** Optional declarative retrieval config. When present, this collection
+     *  is a "Feed": the host periodically fetches `ingest.url`, maps the
+     *  response into records, and upserts them by `primaryKey`. Only feeds
+     *  discovered from the `<workspace>/feeds/` registry carry this; skill
+     *  collections omit it. The host's feeds subsystem narrows this to its
+     *  richer `IngestSpec` (which `extends CollectionIngest`). */
+    ingest?: CollectionIngest;
+}
+export interface CollectionSummary {
+    slug: string;
+    title: string;
+    icon: string;
+    source: CollectionSource;
+}
+export interface CollectionDetail extends CollectionSummary {
+    schema: CollectionSchema;
+}
+export type CollectionItem = Record<string, unknown>;

package/dist/collection/core/shortHexId.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 8-char hex id — short, slug-safe, and editable. Produces the same id *shape*
+ * as the server's `generateItemId()` (8 hex chars) so a UI-created collection
+ * record looks like one the server would have generated for a form submitted
+ * with a blank primary key. The source of randomness differs (UUID-derived here
+ * vs `randomBytes` on the server); only the shape is intentionally shared.
+ */
+export declare function shortHexId(): string;

package/dist/collection/core/sortItems.d.ts

@@ -0,0 +1,29 @@
+import { CollectionItem, CollectionFieldSpec } from './schema';
+export type SortDirection = "asc" | "desc";
+export interface SortState {
+    /** Field key of the single active sort column. */
+    field: string;
+    direction: SortDirection;
+}
+/** A row's comparable value for the active field. Exactly one of `num` /
+ *  `str` is set when not empty; `empty` rows always sort last. */
+export interface SortValue {
+    empty: boolean;
+    num?: number;
+    str?: string;
+}
+export declare function isSortableField(field: CollectionFieldSpec): boolean;
+/** Cycle one column's state: none → asc → desc → none. */
+export declare function nextSortDirection(current: SortDirection | null): SortDirection | null;
+export declare function numericSortValue(raw: unknown): SortValue;
+export declare function stringSortValue(raw: unknown): SortValue;
+export declare function dateSortValue(raw: unknown): SortValue;
+/** Enum sorts by the value's index in the declared `values` list. A value
+ *  outside the list (or unset) is treated as empty → last. */
+export declare function enumSortValue(values: readonly string[] | undefined, raw: unknown): SortValue;
+/** Boolean / toggle: false < true, never empty (unset reads as false). */
+export declare function boolSortValue(checked: boolean): SortValue;
+export declare function compareSortValues(left: SortValue, right: SortValue): number;
+/** Stable sort of `items` by `valueOf`. Empties always last; ties hold
+ *  source order. Returns a new array (does not mutate `items`). */
+export declare function sortItems(items: readonly CollectionItem[], direction: SortDirection, valueOf: (item: CollectionItem) => SortValue): CollectionItem[];

package/dist/collection/core/uiTypes.d.ts

@@ -0,0 +1,106 @@
+import { CollectionDetail, CollectionItem, CollectionSchema, CollectionSummary } from './schema';
+/** A record file the server couldn't load or that violates the schema —
+ *  silently skipped at read time (mirror of the server `RecordIssue`). */
+export interface CollectionRecordIssue {
+    /** Record filename, e.g. `lesson-003.json`. */
+    file: string;
+    /** Human-readable problem, written to be actionable by the LLM. */
+    problem: string;
+}
+export interface CollectionDetailResponse {
+    collection: CollectionDetail;
+    items: CollectionItem[];
+    /** Record files that failed validation; drives the in-view Repair prompt. */
+    issues?: CollectionRecordIssue[];
+}
+export interface ItemMutationResponse {
+    itemId: string;
+    item: CollectionItem;
+}
+/** One row of a `table`-typed field, in draft form. */
+export interface TableRowDraft {
+    text: Record<string, string>;
+    bool: Record<string, boolean>;
+    boolOriginallyPresent: Record<string, boolean>;
+    boolTouched: Record<string, boolean>;
+}
+export interface EditState {
+    mode: "create" | "edit";
+    text: Record<string, string>;
+    bool: Record<string, boolean>;
+    boolOriginallyPresent: Record<string, boolean>;
+    boolTouched: Record<string, boolean>;
+    table: Record<string, TableRowDraft[]>;
+    /** For edit mode: the original item id pinned to the URL. */
+    originalId: string | null;
+}
+/** Per-target-collection cache: an item's primary-key slug → display label. */
+export type RefDisplayMap = Record<string, string>;
+export type RefCache = Record<string, RefDisplayMap>;
+/** Per-target-collection cache of full referenced records, for `<field>.<col>`
+ *  derefs in derived formulas. */
+export type RefRecordMap = Record<string, CollectionItem>;
+export type RefRecordCache = Record<string, RefRecordMap>;
+/** Per-target cache for `embed` fields: the target collection's schema + items. */
+export interface EmbedTargetData {
+    schema: CollectionSchema;
+    items: CollectionItem[];
+}
+export type EmbedCache = Record<string, EmbedTargetData>;
+/** Option shown in a `ref` field's `<select>` dropdown. */
+export interface RefOption {
+    slug: string;
+    display: string;
+}
+export interface EmbedRow {
+    /** Sub-field key (used for `:key` + testids). */
+    key: string;
+    label: string;
+    /** Sub-field type — the renderer branches on "boolean" / "markdown". */
+    type: string;
+    /** Raw value, used only for the boolean check / em-dash. */
+    value: unknown;
+    /** Pre-formatted string for every non-boolean render path. */
+    display: string;
+}
+export interface EmbedView {
+    /** False when the target collection has no record with the embed's `id`
+     *  (or the target couldn't be loaded) — the renderer shows a "missing"
+     *  message + a link to create it. */
+    found: boolean;
+    rows: EmbedRow[];
+    /** Target collection slug, for the "create it" link + message. */
+    targetSlug: string;
+    /** The fixed record id the embed points at, for the message. */
+    recordId: string;
+}
+/** Active-notification severity for a record, used to accent flagged cards
+ *  (kanban left-stripe, etc.). The host computes these from its notifier and
+ *  passes them in; this is the structural type the view layer accepts. The host's
+ *  own `NotifierSeverity` is the identical union, so its maps pass through. */
+export type CollectionNotifySeverity = "info" | "nudge" | "urgent";
+/** Response of the collections list endpoint (`API_ROUTES.collections.list`). */
+export interface CollectionsListResponse {
+    collections: CollectionSummary[];
+}
+/** A row in the feeds index — a data-source collection from the workspace's
+ *  `feeds/` registry. */
+export interface FeedSummary {
+    slug: string;
+    title: string;
+    icon: string;
+    kind: string;
+    schedule: string;
+    lastFetchedAt: string | null;
+}
+/** Response of the feeds list endpoint (`API_ROUTES.feeds.list`). */
+export interface FeedsListResponse {
+    feeds: FeedSummary[];
+}
+/** The `{slug,title,icon}` triple the index pages reconcile pinned shortcuts
+ *  against (prune dead slugs, refresh stale labels). */
+export interface CollectionShortcutInfo {
+    slug: string;
+    title: string;
+    icon: string;
+}