@coffer-org/plugin-webchat 6.0.0 → 7.0.1

package/dist/runtime/send.js

@@ -1,37 +1,52 @@
 import { randomUUID } from 'node:crypto';
 import { handleIncoming, liveAgentId } from '@coffer-org/server/orchestrator';
-import { chatIdFor, recordUser, buildChain, history, readSelectionForTurn } from "./chain-store.js";
+import { beginTurn } from '@coffer-org/server/turn-gate';
+import { HttpError } from '@coffer-org/server/plugin-hooks';
+import { openConversation, recordUser, buildChain, history, readSelectionForTurn, setSelection, userTurnCount, } from "./chain-store.js";
 import { policy } from "./config.js";
 import { makeStreamingConnector } from "./connector.js";
+import { broadcast } from "./channel-registry.js";
 import { webChannelSystem } from "./format.js";
 import { loadReasoningDisplay } from "./settings.js";
+import { getLogger } from '@coffer-org/sdk/logger';
+const log = getLogger('webchat');
+export const CAPABILITIES = {
+    events: ['delta', 'reasoning', 'segment', 'suggestions', 'title'],
+    privateChats: true,
+};
 export function pageContext(ctx) {
     if (typeof ctx !== 'object' || ctx === null)
-        return '';
+        return [];
     const c = ctx;
     const path = typeof c['path'] === 'string' ? c['path'] : '';
     if (!path)
-        return '';
+        return [];
     const library = typeof c['library'] === 'string' ? c['library'] : '';
-    const type = typeof c['type'] === 'string' ? c['type'] : '';
+    const shelf = typeof c['type'] === 'string' ? c['type'] : '';
     const id = typeof c['id'] === 'string' ? c['id'] : '';
-    const where = library && type && id ? `record ${library}/${type}/${id}` : library && type ? `the ${library}/${type} list` : path;
-    return `CURRENT PAGE — the user is looking at ${where} (SPA path ${path}). When they say "this", "here", or "this record", they most likely mean it. Do not mention this note unless it is relevant.`;
+    const title = typeof c['title'] === 'string' ? c['title'] : '';
+    if (library && shelf && id)
+        return [{ name: 'record', value: title, attrs: { library, shelf, id } }];
+    if (library && shelf)
+        return [{ name: 'page', value: '', attrs: { library, shelf } }];
+    return [{ name: 'page', value: path }];
 }
-export async function sendAction(body, ctx, deps = {}) {
+export async function sendAction(body, caller, deps = {}) {
     const doHandle = deps.handleIncoming ?? handleIncoming;
     const convId = typeof body['convId'] === 'string' ? body['convId'] : '';
     const text = typeof body['text'] === 'string' ? body['text'] : '';
-    if (!convId) {
-        ctx.emit('error', { message: 'missing required field: convId' });
-        return;
+    if (!convId)
+        throw new HttpError(400, 'missing required field: convId');
+    if (!text.trim())
+        throw new HttpError(400, 'missing required field: text');
+    const chatId = await openConversation(convId, caller.id, 'write');
+    if (chatId === null) {
+        return { msgId: null, botMsgId: null };
     }
-    if (!text.trim()) {
-        ctx.emit('error', { message: 'missing required field: text' });
-        return;
-    }
-    const chatId = chatIdFor(ctx.caller.id, convId);
     const selection = await readSelectionForTurn(chatId);
+    if (selection.owner === null) {
+        await setSelection(chatId, { owner: caller.id });
+    }
     const agentId = liveAgentId(selection.agentId);
     const msgId = randomUUID();
     const botMsgId = randomUUID();
@@ -39,27 +54,44 @@ export async function sendAction(body, ctx, deps = {}) {
     const attachments = parseAttachments(body['attachments']);
     const explicitReplyTo = typeof body['replyTo'] === 'string' && body['replyTo'] ? body['replyTo'] : null;
     const replyTo = explicitReplyTo ?? (await history(chatId, 1)).at(-1)?.msgId ?? null;
-    await recordUser({ chatId, msgId, sender: ctx.caller.id, text, attachments, ts: nowSec, replyToId: replyTo });
+    await recordUser({ chatId, msgId, sender: caller.id, text, attachments, ts: nowSec, replyToId: replyTo });
+    broadcast(chatId, 'user', { msgId, text, ts: nowSec, ...(attachments?.length ? { attachments } : {}) });
     const messages = await buildChain(msgId, { chatId });
+    const userTurns = await userTurnCount(chatId);
     const { connector, recorded, suggestions } = makeStreamingConnector({
         chatId,
         botMsgId,
-        emit: ctx.emit,
         display: await loadReasoningDisplay(),
     });
     const turnContext = pageContext(body['context']);
-    await doHandle(connector, {
-        connectorId: 'webchat',
-        channelSystem: await webChannelSystem(),
-        ...(turnContext ? { turnContext } : {}),
-        ...(agentId ? { agentId } : {}),
-        ...(selection.presetId ? { presetId: selection.presetId } : {}),
-        chatId,
-        sender: { id: ctx.caller.id },
-        messages,
-        supportsSuggestions: true,
-    }, { policy: policy() });
-    ctx.emit('done', { msgId: recorded(), parentMsgId: msgId, suggestions: suggestions() });
+    const gate = await beginTurn('webchat', chatId, { supersede: true });
+    void (async () => {
+        try {
+            await doHandle(connector, {
+                envelope: { connectorId: 'webchat', chatId, turnId: msgId },
+                body: {
+                    systemPrompt: { channel: [await webChannelSystem()] },
+                    messages,
+                    capabilities: CAPABILITIES,
+                    userTurns,
+                },
+                ...(turnContext.length ? { turnContext } : {}),
+                ...(agentId ? { agentId } : {}),
+                ...(selection.presetId ? { presetId: selection.presetId } : {}),
+                sender: { id: caller.id, idKind: 'coffer-user' },
+                signal: gate.signal,
+            }, { policy: policy() });
+            broadcast(chatId, 'done', { msgId: recorded(), parentMsgId: msgId, suggestions: suggestions() });
+        }
+        catch (err) {
+            log.error(`sendAction: handleIncoming threw for chat ${chatId}: ${err instanceof Error ? err.message : String(err)}`);
+            broadcast(chatId, 'error', { message: null, parentMsgId: msgId });
+        }
+        finally {
+            gate.end();
+        }
+    })();
+    return { msgId, botMsgId };
 }
 function parseAttachments(value) {
     if (!Array.isArray(value))

package/dist/schema.js

@@ -4368,6 +4368,13 @@ function wrapKey(key, opts, meta) {
 			span: opts.span
 		}
 	};
+	if (opts.faces !== void 0) m = {
+		...m,
+		hints: {
+			...m.hints,
+			faces: opts.faces
+		}
+	};
 	if (opts.default !== void 0) m = {
 		...m,
 		default: opts.default
@@ -4795,6 +4802,7 @@ function normalizeOpts(rawIn) {
 		...v.valueLabel !== void 0 ? { valueLabel: v.valueLabel } : {},
 		compareWith: v.compareWith,
 		span: v.span,
+		faces: v.faces,
 		emphasis: v.emphasis,
 		noLabel: v.noLabel,
 		role: v.role,
@@ -5107,6 +5115,63 @@ registerPreset("slug", "string", {}, {
 		};
 	}
 });
+/**
+* Identifier — a code printed for a machine and read back by one: a serial number, an order
+* number, a policy number, an IMEI. What a person actually DOES with one is copy it, which is
+* why this is a type of its own and not `f.string({ ui: { voice: 'data' } })`: the machine face
+* is one word on any string now, but the click that copies belongs to the kind.
+*
+* Deliberately unvalidated beyond a length: an identifier's format belongs to whoever issued
+* it, and a pattern here would reject the next manufacturer's.
+*
+* @layer   preset
+* @base    string
+* @prim    text
+* @widget  identifier
+* @example f.identifier({ label: 'mod.fields.serialNumber' })
+*/
+function identifier(o) {
+	return declare("identifier", o);
+}
+registerPreset("identifier", "string", {}, {
+	kind: "identifier",
+	widget: "identifier",
+	build() {
+		return {
+			column: "text",
+			zod: string$1(),
+			hints: {}
+		};
+	}
+});
+/**
+* The machine-readable zone of a travel document — the identifier taken to its limit: printed
+* for a scanner, not for a person. Fixed pitch, chevrons kept as the filler they are, and the
+* line breaks preserved, because an MRZ's line structure is part of what it encodes.
+*
+* Unvalidated on purpose, like `identifier`: the ICAO line formats differ by document type, and
+* a strip transcribed from a real document is worth storing even when it does not check out.
+*
+* @layer   preset
+* @base    string
+* @prim    text
+* @widget  mrz
+* @example f.mrz({ label: 'documents.personal_document.fields.mrz' })
+*/
+function mrz(o) {
+	return declare("mrz", o);
+}
+registerPreset("mrz", "string", {}, {
+	kind: "mrz",
+	widget: "mrz",
+	build() {
+		return {
+			column: "text",
+			zod: string$1(),
+			hints: {}
+		};
+	}
+});
 var COLOR_RE = /^#[0-9a-fA-F]{6}$/;
 /**
 * Hex color — kind 'color', `#rrggbb` + swatch widget.
@@ -5391,6 +5456,38 @@ registerPreset("tag", "string", {}, {
 	}
 });
 /**
+* A location written the way it is said aloud: workshop › shelf 2 › box. A `string` fixed to
+* `multiple`, exactly as `f.tags` is, because a place inside a place inside a place IS a
+* sequence — the plurality is the type, not a modifier someone remembered to add.
+*
+* Distinct from `f.tags`, which stores the same shape: tags are an unordered SET, and a path is
+* an ordered CHAIN where each step is inside the one before it. Drawn as chips, that
+* containment — the only thing the value actually carries — is lost.
+*
+* @layer   preset
+* @base    string
+* @prim    text
+* @widget  path
+* @example f.path({ label: 'things.storage_location.fields.path' })
+*/
+function path(o) {
+	return declare("path", {
+		...o,
+		multiple: true
+	});
+}
+registerPreset("path", "string", {}, {
+	kind: "path",
+	widget: "path",
+	build() {
+		return {
+			column: "text",
+			zod: string$1(),
+			hints: {}
+		};
+	}
+});
+/**
 * Tags — `tag({ multiple: true })`.
 *
 * @layer   preset
@@ -5583,6 +5680,56 @@ registerPreset("reminder", "date", { lead: 30 }, {
 		};
 	}
 });
+/** Timetable — a set of times of day, read as a schedule rather than as a bag of values.
+* kind 'timetable', prim 'time', always `multiple`.
+*
+* Same shape as `f.reminder`/`f.age` over `date`: a semantic type whose renderer knows what
+* the values MEAN. Everything it shows beyond the times themselves — when the service starts
+* and ends, how many runs there are, which one is next — is derived from the values at render
+* time, never stored: a "next departure" is wrong the moment it is written down, exactly the
+* argument `f.age` already makes for an age.
+*
+* Storage is a plain multiple `time`, so a field can be switched to this from
+* `f.time({ multiple: true })` and back with no migration.
+*
+* @layer   preset
+* @base    time
+* @prim    time
+* @widget  timetable
+* @example f.timetable({ label: 'mod.fields.weekdays' })
+*/
+function timetable(o) {
+	return declare("timetable", {
+		...o,
+		multiple: true
+	});
+}
+registerPreset("timetable", "time", {}, {
+	kind: "timetable",
+	widget: "timetable"
+});
+/** Age — date whose whole-year age (as of today) renders alongside it, e.g. a birth date.
+* kind 'age', prim 'date'. The age itself is computed at RENDER time, never stored: unlike a
+* `mutate`-driven computed field, it must be right on every day that passes, not only the day
+* the record was last written, so this is display metadata over `date`, the same shape as
+* `f.reminder`'s own relative-to-today note.
+*
+* @layer   preset
+* @base    date
+* @prim    date
+* @widget  age
+* @example f.age({ label: 'mod.fields.birthDate' })
+*/
+function age(o) {
+	return declare("age", o);
+}
+registerPreset("age", "date", {}, {
+	kind: "age",
+	widget: "age",
+	build(o, parts) {
+		return typeOf("date").build(o, parts);
+	}
+});
 /**
 * Percentage 0..100 — real with rules:{min:0,max:100}.
 *
@@ -5775,6 +5922,9 @@ var presets = {
 	email,
 	tel,
 	slug,
+	path,
+	identifier,
+	mrz,
 	color,
 	colorname,
 	title,
@@ -5788,6 +5938,8 @@ var presets = {
 	rating,
 	duration,
 	reminder,
+	age,
+	timetable,
 	percent,
 	year,
 	weight,
@@ -6445,26 +6597,38 @@ function identity(opts) {
 		}
 	};
 }
-/** A scored value out of an optional max, with an optional verdict.
+/** One measure out of an optional max, from ONE OR MORE named sources, with an optional verdict.
+*
+* `source` takes several entries for the same reason `f.identity`'s `channels` does — it is a
+* role that holds a LIST, so `view.source` is an ordered list of names rather than one name.
+* Two ratings of the same film out of ten are one measure read twice, and drawing them apart is
+* what makes them incomparable: the eye has to carry the scale between two figures instead of
+* reading them against a shared one. `media/title` had exactly that, two `f.score` blocks of
+* `max: 10` held apart inside an `f.compare`, until this took the restriction off.
+*
+* NOT `multiple`. A multiple field is an anonymous array; these are NAMED sources, and the name
+* is what says which reading came from where. The two are different shapes and the block wants
+* this one.
 *
 * @layer   block
 * @base    group
 * @prim    —
 * @widget  score
-* @example f.score({ source: { value: f.real({ label: '…' }) }, max: 100, verdict: { verdict: f.string({ label: '…' }) } })
+* @example f.score({ source: { imdb: f.real({ label: '…' }), tmdb: f.real({ label: '…' }) }, max: 10 })
 */
 function score(opts) {
-	const source = slot("score", "source", opts.source);
+	const names = Object.keys(opts.source ?? {});
+	if (names.length === 0) throw new Error(`[field.score] slot 'source' expects at least one entry, got 0`);
 	const verdict = opts.verdict !== void 0 ? slot("score", "verdict", opts.verdict) : void 0;
 	return {
 		...group({
 			label: opts.label,
-			fields: merge("score", source, verdict),
+			fields: merge("score", opts.source, verdict),
 			ui: { kind: "score" }
 		}),
 		view: {
 			kind: "score",
-			source: Object.keys(source)[0],
+			source: names,
 			max: opts.max,
 			verdict: verdict && Object.keys(verdict)[0]
 		}
@@ -6496,11 +6660,20 @@ function status(opts) {
 }
 /** A gauge value between an optional min and max, with an optional "of" total.
 *
+* `direction` is opt-in: when given, the gauge decides in plain JavaScript whether its own
+* value crossed the bound that matters (`meterTone`, `blocks/meter.tsx`) and reaches for the
+* tone palette — the fill, the value text and the `of` companion all move together, never
+* colour alone (a glyph rides along, see the renderer's own comment). Omit it and nothing
+* about the gauge changes from today. A `'ceiling'` gauge with no declared `max` (config or
+* the source field's own hints) resolves it from `of`'s own value instead — a budget's cap is
+* a per-record field, never a compile-time constant.
+*
 * @layer   block
 * @base    group
 * @prim    —
 * @widget  meter
 * @example f.meter({ source: { used: f.real({ label: '…' }) }, min: 0, max: 100 })
+* @example f.meter({ source: { spent: f.real({ label: '…' }) }, of: { budget: f.real({ label: '…' }) }, direction: 'ceiling' })
 */
 function meter(opts) {
 	const source = slot("meter", "source", opts.source);
@@ -6516,7 +6689,8 @@ function meter(opts) {
 			source: Object.keys(source)[0],
 			min: opts.min,
 			max: opts.max,
-			of: of && Object.keys(of)[0]
+			of: of && Object.keys(of)[0],
+			direction: opts.direction
 		}
 	};
 }
@@ -6576,6 +6750,11 @@ function balance(opts) {
 * @base    group
 * @prim    —
 * @widget  route
+* A `stub` is the part of the ticket that is TORN OFF and kept — a seat, a gate, a booking
+* reference. Declaring one makes the block a ticket rather than a line: the two halves are
+* separated by a perforation, and the fields in the stub sit below it. Without one the block
+* is exactly what it was, a route from here to there, so no existing call changes.
+*
 * @example f.route({ from: { from: f.string({ label: '…' }) }, to: { to: f.string({ label: '…' }) } })
 */
 function route(opts) {
@@ -6584,9 +6763,10 @@ function route(opts) {
 	const depart = opts.depart !== void 0 ? slot("route", "depart", opts.depart) : void 0;
 	const arrive = opts.arrive !== void 0 ? slot("route", "arrive", opts.arrive) : void 0;
 	const duration = opts.duration !== void 0 ? slot("route", "duration", opts.duration) : void 0;
+	const stub = opts.stub ?? {};
 	return {
 		...group({
-			fields: merge("route", from, to, depart, arrive, duration),
+			fields: merge("route", from, to, depart, arrive, duration, stub),
 			ui: { kind: "route" }
 		}),
 		view: {
@@ -6595,7 +6775,8 @@ function route(opts) {
 			to: Object.keys(to)[0],
 			depart: depart && Object.keys(depart)[0],
 			arrive: arrive && Object.keys(arrive)[0],
-			duration: duration && Object.keys(duration)[0]
+			duration: duration && Object.keys(duration)[0],
+			stub: Object.keys(stub)
 		}
 	};
 }
@@ -6773,6 +6954,81 @@ function specimen(opts) {
 	};
 }
 /**
+* Measurements against the range they were supposed to fall in, rendered from a single
+* collection source — see `stampCollection`. `analyte`, `value`, `unit`, `low` and `high` are
+* part KEYS inside each collection row, NOT `LayoutEl` positions — the same reasoning as
+* `manifest`'s `quantity`/`item`.
+*
+* The point is the COMPARISON. A `f.table` over the same rows prints the bounds as two more
+* columns and leaves the reader to do it; here each value sits on its own band with the
+* reference span marked on it, so "outside the range" is seen rather than worked out. That is
+* also the only thing on the row worth a colour — it is what the reader has to act on.
+*
+* `unit`, `low` and `high` are optional: a measurement with no published range (a culture, a
+* description) still belongs in the same list and simply gets no band.
+*
+* @layer   block
+* @base    group
+* @prim    —
+* @widget  assay
+* @example f.assay({ source: { results: f.group({ scope: 'nest', multiple: true, fields: { analyte: f.string({ label: '…' }), value: f.real({ label: '…' }) } }) }, analyte: 'analyte', value: 'value' })
+*/
+function assay(opts) {
+	return stampCollection("assay", opts.source, opts.label, {
+		kind: "assay",
+		analyte: opts.analyte,
+		value: opts.value,
+		...opts.unit ? { unit: opts.unit } : {},
+		...opts.low ? { low: opts.low } : {},
+		...opts.high ? { high: opts.high } : {}
+	});
+}
+/**
+* Value moving from one place to another, where the MOVEMENT is the subject — not one more
+* labelled row among the record's fields. The sum is set large in the machine voice, and the two
+* ends read as a path beneath it.
+*
+*   amount — what moved. The one required role, and the reason the block exists
+*   from   — where it left. Absent on money that only arrived
+*   to     — where it arrived. Absent on money that only left
+*   meta   — the record's own remaining fields, under a rule: date, category, reference
+*
+* An absent end is not drawn, and that is the whole reading: money that left an account and
+* arrived nowhere IS an expense. It is read off which ends the record actually has, never
+* guessed from the shape of a value. What the movement MEANS beyond that — whether this
+* particular kind of transfer is good news — is carried by the classifier's own option `tone`,
+* the same declaration every other coloured value in the product uses.
+*
+* Distinct from `f.route`, which also has two ends: there the journey is the subject and the
+* ends are places, so it carries times and a duration; here the ends are accounts and the
+* subject is the quantity.
+*
+* @layer   block
+* @base    group
+* @prim    —
+* @widget  flow
+* @example f.flow({ amount: { amount: f.money({ label: '…' }) }, from: { source: f.relation({ label: '…' }) } })
+*/
+function flow(opts) {
+	const amount = slot("flow", "amount", opts.amount);
+	const from = opts.from !== void 0 ? slot("flow", "from", opts.from) : void 0;
+	const to = opts.to !== void 0 ? slot("flow", "to", opts.to) : void 0;
+	return {
+		...group({
+			label: opts.label,
+			fields: merge("flow", amount, from, to, opts.meta),
+			ui: { kind: "flow" }
+		}),
+		view: {
+			kind: "flow",
+			amount: Object.keys(amount)[0],
+			from: from && Object.keys(from)[0],
+			to: to && Object.keys(to)[0],
+			meta: Object.keys(opts.meta ?? {})
+		}
+	};
+}
+/**
 * A packing/cargo manifest rendered from a single collection source — see `stampCollection`.
 * `quantity` and `item` are part KEYS inside each collection row, NOT `LayoutEl` positions —
 * the same reasoning as `journal`'s `date`/`text`.
@@ -6819,13 +7075,25 @@ function table(opts) {
 		} : {},
 		...opts.groupBy ? { groupBy: opts.groupBy } : {},
 		...opts.totals ? { totals: opts.totals } : {},
+		...opts.summary ? { summary: opts.summary } : {},
 		...opts.numbered ? { numbered: true } : {}
 	});
 }
 /**
-* An ID-card header: an optional overline, a prominent number, and trailing meta fields.
-* `view` names each role (Task 5) — see `masthead`'s own doc comment for what `meta` means
-* as an ordered name list.
+* An identity document, drawn as the card it is: a caption and its number across the top, a
+* portrait beside the holder's own fields, the issuing details under a rule, and the
+* machine-readable strip at the foot. `view` names each role (Task 5) — see `masthead`'s own
+* doc comment for what an ordered name list means.
+*
+*   overline — the caption at the top left ("PASSPORT", "DRIVING LICENCE")
+*   number   — the document's number, set apart at the top right
+*   photo    — the portrait. One field, rendered in a portrait frame beside the body
+*   meta     — the card's OWN fields, labelled, at each field's declared span
+*   footer   — the fields below the rule: issued, authority, record number
+*   mrz      — the machine-readable strip, set in monospace at the foot
+*
+* Every role is optional but `number`: a bank card has no `mrz`, a library card no `photo`,
+* and the card simply omits the part it was given nothing for.
 *
 * @layer   block
 * @base    group
@@ -6836,16 +7104,21 @@ function table(opts) {
 function idcard(opts) {
 	const overline = opts.overline !== void 0 ? slot("idcard", "overline", opts.overline) : void 0;
 	const number = slot("idcard", "number", opts.number);
+	const photo = opts.photo !== void 0 ? slot("idcard", "photo", opts.photo) : void 0;
+	const mrz = opts.mrz !== void 0 ? slot("idcard", "mrz", opts.mrz) : void 0;
 	return {
 		...group({
-			fields: merge("idcard", overline, number, opts.meta),
+			fields: merge("idcard", overline, number, photo, opts.meta, opts.footer, mrz),
 			ui: { kind: "idcard" }
 		}),
 		view: {
 			kind: "idcard",
 			overline: overline && Object.keys(overline)[0],
 			number: Object.keys(number)[0],
-			meta: Object.keys(opts.meta ?? {})
+			photo: photo && Object.keys(photo)[0],
+			meta: Object.keys(opts.meta ?? {}),
+			footer: Object.keys(opts.footer ?? {}),
+			mrz: mrz && Object.keys(mrz)[0]
 		}
 	};
 }
@@ -6930,6 +7203,8 @@ var blocks = {
 	nutrition,
 	specimen,
 	manifest,
+	assay,
+	flow,
 	table,
 	idcard,
 	properties,
@@ -7777,6 +8052,11 @@ function group(o) {
 		for (const f of fields) if (!("key" in f && f.key !== void 0) && !hasChildren(f)) throw new Error(`[field.group] a 'nest' group's children must be fields or groups, not layout elements`);
 		for (const k of r.unique ?? []) if (!fields.some((f) => "key" in f && f.key === k)) throw new Error(`[field.group] unique key '${k}' is not a subfield`);
 	} else if (o.value !== void 0) throw new Error(`[field.group] value requires scope 'nest' — a hoist group owns no children to write`);
+	const title = v.title ?? [];
+	if (title.length > 0) {
+		if (!o.multiple) throw new Error(`[field.group] ui.title heads a collection's ROWS — it needs multiple: true`);
+		for (const name of title) if (!fields.some((f) => "key" in f && f.key === name)) throw new Error(`[field.group] ui.title '${name}' is not one of its fields`);
+	}
 	return {
 		el: "group",
 		scope,
@@ -7789,6 +8069,7 @@ function group(o) {
 		display: v.display ?? "wrap",
 		kind: v.kind,
 		fixed: r.fixed,
+		view: title.length > 0 ? { title } : void 0,
 		fields
 	};
 }
@@ -7937,6 +8218,12 @@ function divider(o) {
 /**
 * Reference markdown block by i18n key.
 *
+* The key is resolved WITH the variables of the running instance, so the locale string
+* may name facts that are not constants: `{{origin}}` is this instance's own address
+* (`https://coffer.example`), which is how a block documents an endpoint without
+* freezing a developer's `localhost` into every translation. The set is fixed and
+* ambient — the block declares only its key. See `web-ui/src/render/info-text.ts`.
+*
 * @layer   primitive
 * @prim    —
 * @widget  info
@@ -7949,6 +8236,31 @@ function info(textKey) {
 	};
 }
 /**
+* What else points AT this record — the inverse of a relation, which is often the more useful
+* direction on a record page: a box is more usefully "what is in it" than "what it is in".
+*
+* Stores NOTHING and has no column: it declares where to look, and the server answers by asking
+* the pointing shelf. That is why it is a pseudo-element beside `divider` and `info` rather than
+* a field — there is no value here to validate or save.
+*
+* `from` names the pointing side explicitly (which shelf, and WHICH of its fields), never
+* "everything that happens to point here": a shelf may point at the same target through two
+* fields — a transaction has a source account and a destination account — and a panel that
+* merged them would answer a question nobody asked.
+*
+* @layer   primitive
+* @prim    —
+* @widget  backrefs
+* @example f.backrefs({ label: 'mod.fields.storedHere', from: { library: 'things', shelf: 'item', field: 'location' } })
+*/
+function backrefs(o) {
+	return {
+		el: "backrefs",
+		label: o.label,
+		from: o.from
+	};
+}
+/**
 * Action button: invokes the handler registered in actionRegistry under the key `value`.
 *
 * @layer   primitive
@@ -8273,20 +8585,22 @@ registerType("time", {
 	prim: "time",
 	widget: "time",
 	build(o) {
-		const granularity = o.config?.granularity ?? "second";
+		const granularity = o.config?.granularity ?? "minute";
+		const s = string$1(reqErr()).regex({
+			hour: /^([01]\d|2[0-3])$/,
+			minute: /^([01]\d|2[0-3]):[0-5]\d(?::[0-5]\d)?$/,
+			second: /^([01]\d|2[0-3]):[0-5]\d:[0-5]\d$/
+		}[granularity], { message: vmsg("time_format") });
 		return {
 			column: "time",
-			zod: string$1(reqErr()).regex({
-				hour: /^([01]\d|2[0-3])$/,
-				minute: /^([01]\d|2[0-3]):[0-5]\d$/,
-				second: /^([01]\d|2[0-3]):[0-5]\d:[0-5]\d$/
-			}[granularity], { message: vmsg("time_format") }),
+			zod: granularity === "minute" ? s.transform((v) => v.slice(0, 5)) : s,
 			hints: { granularity }
 		};
 	}
 });
 /**
-* Time-of-day value with configurable granularity ('hour' | 'minute' | 'second', default 'second').
+* Time-of-day value with configurable granularity ('hour' | 'minute' | 'second', default
+* 'minute' — the same default `f.datetime` has always had).
 *
 * @layer   primitive
 * @prim    time
@@ -9531,7 +9845,8 @@ var PRIMITIVES = {
 	url,
 	divider,
 	info,
-	button
+	button,
+	backrefs
 };
 /** Assembles `f`, guaranteeing no preset/block shadows a primitive. */
 function composeF(presets, blocks) {