@coffer-org/plugin-webchat 7.0.0 → 7.1.0

package/dist/schema.js

@@ -24,6 +24,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#region ../sdk/src/plugin.ts
 function definePlugin(p) {
 	if (!p.id) throw new Error("[plugin] missing id");
+	if (!p.label) throw new Error(`[plugin] ${p.id}: missing label`);
+	if (!p.description) throw new Error(`[plugin] ${p.id}: missing description`);
 	if (!p.version) console.warn(`[plugin] ${p.id}: missing version`);
 	return p;
 }
@@ -4134,16 +4136,18 @@ function jsonRefined(inner, code) {
 		});
 	});
 }
-function optionalize(schema, required) {
-	const req = required === true;
-	const pre = (v) => v === "" || v === null ? void 0 : v;
-	if (!req) return preprocess(pre, schema.optional());
-	return preprocess(pre, unknown().superRefine((v, ctx) => {
-		if (v === void 0) ctx.addIssue({
-			code: ZodIssueCode.custom,
-			message: vmsg("required")
-		});
-	}).pipe(schema));
+/**
+* An empty value is no value: `''` and `null` become `undefined`, and the field's own schema
+* never sees them. Every field is optional, so this is the ONLY shape — a field cannot demand
+* a value, and the rules it carries judge what was entered rather than whether anything was.
+*
+* This used to have a second branch, for `required` fields, which turned the same emptiness
+* into a `required` issue through a `z.unknown()` guard piped into the schema. That branch is
+* why a `.min(1)` on a required string was unreachable: the empty string had already been
+* converted to the issue before the string schema ran.
+*/
+function optionalize(schema) {
+	return preprocess((v) => v === "" || v === null ? void 0 : v, schema.optional());
 }
 //#endregion
 //#region ../sdk/src/fields/meta.ts
@@ -4225,7 +4229,7 @@ function applyMultiple(base, multiple) {
 			multiple: true
 		},
 		json: true,
-		zod: optionalize(s, base.required)
+		zod: optionalize(s)
 	};
 }
 /** Inline option entry → OptionItem (plain string = value and label at once). */
@@ -4340,13 +4344,6 @@ function wrapKey(key, opts, meta) {
 			noLabel: true
 		}
 	};
-	if (opts.role) m = {
-		...m,
-		hints: {
-			...m.hints,
-			role: opts.role
-		}
-	};
 	if (opts.editor) m = {
 		...m,
 		hints: {
@@ -4368,6 +4365,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,9 +4799,9 @@ 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,
 		editor: v.editor,
 		activate: v.activate
 	};
@@ -4960,13 +4964,10 @@ function email(o) {
 registerPreset("email", "string", {}, {
 	kind: "email",
 	widget: "email",
-	build(o) {
-		const required = o.required ?? false;
-		let s = string$1().email({ message: vmsg("email") });
-		if (required) s = s.min(1, { message: vmsg("min_length", { min: 1 }) });
+	build() {
 		return {
 			column: "text",
-			zod: s,
+			zod: string$1().email({ message: vmsg("email") }),
 			hints: {
 				format: "email",
 				inputType: "email"
@@ -4989,12 +4990,10 @@ function tel(o) {
 registerPreset("tel", "string", {}, {
 	kind: "tel",
 	widget: "tel",
-	build(o) {
-		const required = o.required ?? false;
-		const base_z = string$1().regex(TEL_RE, { message: vmsg("pattern", { messageKey: "core.presets.tel" }) });
+	build() {
 		return {
 			column: "text",
-			zod: required ? base_z.min(1, { message: vmsg("min_length", { min: 1 }) }) : base_z,
+			zod: string$1().regex(TEL_RE, { message: vmsg("pattern", { messageKey: "core.presets.tel" }) }),
 			hints: {
 				format: "tel",
 				inputType: "tel"
@@ -5018,10 +5017,10 @@ registerPreset("password", "string", {}, {
 	kind: "password",
 	widget: "password",
 	selfManages: /* @__PURE__ */ new Set(["multiple"]),
-	build(o) {
+	build() {
 		return {
 			column: "text",
-			zod: o.required ?? false ? string$1().min(1, { message: vmsg("min_length", { min: 1 }) }) : string$1(),
+			zod: string$1(),
 			hints: {
 				format: "password",
 				inputType: "password"
@@ -5083,6 +5082,31 @@ function internalOauthGrants(o) {
 		}
 	});
 }
+/**
+* The account page's linked-accounts section. Same trick as `internalApiToken`: a container
+* with a custom `ui.kind`, drawn by its own renderer, which reads `/api/auth/links` itself.
+* The declared children are what one ROW holds — the renderer reads them through the slot
+* contract, so this is a declaration, not a layout.
+*
+* @layer preset
+* @base group
+* @prim —
+* @widget internalIdentityLinks
+* @example f.internalIdentityLinks({ label: 'auth.linksTitle' })
+*/
+function internalIdentityLinks(o) {
+	return group({
+		scope: "nest",
+		label: o.label,
+		multiple: true,
+		ui: { kind: "internalIdentityLinks" },
+		fields: {
+			provider: string({}),
+			externalId: string({}),
+			linkedAt: string({})
+		}
+	});
+}
 var SLUG_RE = /^[a-z0-9-]+$/;
 /**
 * Slug — kind 'slug', `^[a-z0-9-]+$`.
@@ -5107,6 +5131,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.
@@ -5146,10 +5227,10 @@ function colorname(o) {
 registerPreset("colorname", "string", {}, {
 	kind: "colorname",
 	widget: "colorname",
-	build(o) {
+	build() {
 		return {
 			column: "text",
-			zod: (o.required ?? false ? string$1().min(1, { message: vmsg("min_length", { min: 1 }) }) : string$1()).refine((v) => CSS_COLOR_NAMES.has(v.toLowerCase()), { message: vmsg("colorname") }),
+			zod: string$1().refine((v) => CSS_COLOR_NAMES.has(v.toLowerCase()), { message: vmsg("colorname") }),
 			hints: {}
 		};
 	}
@@ -5169,10 +5250,10 @@ function title(o) {
 registerPreset("title", "string", {}, {
 	kind: "title",
 	widget: "title",
-	build(o) {
+	build() {
 		return {
 			column: "text",
-			zod: o.required ?? false ? string$1().min(1, { message: vmsg("min_length", { min: 1 }) }) : string$1(),
+			zod: string$1(),
 			hints: {}
 		};
 	}
@@ -5193,12 +5274,10 @@ function link(o) {
 registerPreset("link", "string", {}, {
 	kind: "link",
 	widget: "link",
-	build(o) {
-		const required = o.required ?? false;
-		const base_z = string$1().regex(LINK_RE, { message: vmsg("pattern", { messageKey: "core.presets.link" }) });
+	build() {
 		return {
 			column: "text",
-			zod: required ? base_z.min(1, { message: vmsg("min_length", { min: 1 }) }) : base_z,
+			zod: string$1().regex(LINK_RE, { message: vmsg("pattern", { messageKey: "core.presets.link" }) }),
 			hints: {
 				format: "url",
 				inputType: "url"
@@ -5391,6 +5470,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 +5694,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 +5936,9 @@ var presets = {
 	email,
 	tel,
 	slug,
+	path,
+	identifier,
+	mrz,
 	color,
 	colorname,
 	title,
@@ -5788,6 +5952,8 @@ var presets = {
 	rating,
 	duration,
 	reminder,
+	age,
+	timetable,
 	percent,
 	year,
 	weight,
@@ -5796,6 +5962,7 @@ var presets = {
 	currency,
 	money,
 	internalApiToken,
+	internalIdentityLinks,
 	internalOauthGrants
 };
 //#endregion
@@ -6445,26 +6612,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 +6675,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 +6704,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 +6765,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 +6778,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 +6790,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 +6969,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 +7090,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 +7119,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 +7218,8 @@ var blocks = {
 	nutrition,
 	specimen,
 	manifest,
+	assay,
+	flow,
 	table,
 	idcard,
 	properties,
@@ -7777,18 +8067,23 @@ 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,
 		multiple: o.multiple,
 		compute: o.value,
-		required: o.required,
 		unique: r.unique,
 		label: o.label,
 		icon: o.icon,
 		display: v.display ?? "wrap",
 		kind: v.kind,
 		fixed: r.fixed,
+		view: title.length > 0 ? { title } : void 0,
 		fields
 	};
 }
@@ -7814,7 +8109,6 @@ function row(o) {
 		icon: o.icon,
 		fields: o.fields,
 		multiple: o.multiple,
-		required: o.required,
 		rules: o.rules,
 		ui: { display: "scroll" }
 	});
@@ -7862,7 +8156,6 @@ function url(o) {
 	return group({
 		scope: "nest",
 		label: o.label,
-		required: o.required,
 		ui: { kind: "url" },
 		fields: {
 			scheme: string({}),
@@ -7914,7 +8207,6 @@ function keyed(o) {
 		}),
 		scope: "nest",
 		multiple: true,
-		required: o.required,
 		unique: o.unique ?? [role],
 		fixed: o.fixed,
 		view: { by: role }
@@ -7955,6 +8247,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
@@ -8010,7 +8327,7 @@ registerType("string", {
 	widget: "text",
 	build(o) {
 		const cfg = o.config ?? {};
-		const min = cfg.min ?? (o.required === true ? 1 : 0);
+		const min = cfg.min ?? 0;
 		return {
 			column: "text",
 			zod: stringContent((str) => {
@@ -8038,9 +8355,9 @@ registerType("string", {
 function string(o) {
 	return declare("string", o);
 }
-/** Shared by localDir/localFile's build(): a server path, min-length-1 when required. */
-function pathZod(o) {
-	return stringContent((s) => o.required === true ? s.min(1, { message: vmsg("min_length", { min: 1 }) }) : s);
+/** Shared by localDir/localFile's build(): a server path, judged only when one was entered. */
+function pathZod(_o) {
+	return stringContent((s) => s);
 }
 registerType("localDir", {
 	kind: "localDir",
@@ -8279,20 +8596,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
@@ -8697,10 +9016,9 @@ var MEASURED_ROLES = (opts) => {
 		accepts: ENUMERATED,
 		normalize: (d) => {
 			if (d && accepts(unitRole, d)) return d;
-			const { label, required, value } = d?.opts ?? {};
+			const { label, value } = d?.opts ?? {};
 			return declare("string", {
 				label,
-				required,
 				value,
 				noSearch: d?.opts.noSearch,
 				ui: uiOf(d?.opts),
@@ -8859,7 +9177,7 @@ registerType("geo", {
 		label: string$1().nullish()
 	}),
 	structureCode: "geo_structure",
-	absenceRoles: ["lat", "lng"]
+	acceptsEmptyRow: true
 });
 /**
 * Geographic point composite {lat, lng, label?}; lat/lng validated to valid coordinate
@@ -8937,7 +9255,7 @@ registerType("illustrated", {
 	roles: ILLUSTRATED_ROLES,
 	roleZod: () => defaultRoleZod(ILLUSTRATED_ROLES),
 	structureCode: "illustrated_structure",
-	absenceRoles: ["text", "image"],
+	acceptsEmptyRow: true,
 	collectionView: "illustratedList",
 	hints: (o) => o.config ? { config: o.config } : {}
 });
@@ -8981,7 +9299,7 @@ registerType("attachment", {
 	roles: ATTACHMENT_ROLES,
 	roleZod: () => defaultRoleZod(ATTACHMENT_ROLES),
 	structureCode: "attachment_structure",
-	absenceRoles: ["file"],
+	acceptsEmptyRow: true,
 	collectionView: "attachmentList"
 });
 /**
@@ -9082,11 +9400,10 @@ function periodRole(key, label, mkSubDecl) {
 			if (d && accepts(def, d)) return d;
 			const canonical = mkSubDecl(label);
 			if (!d) return canonical;
-			const { label: l, required, value } = d.opts;
+			const { label: l, value } = d.opts;
 			return declare(canonical.factory, {
 				...canonical.opts,
 				label: l ?? canonical.opts.label,
-				required,
 				value,
 				noSearch: d.opts.noSearch,
 				ui: uiOf(d.opts)
@@ -9370,8 +9687,7 @@ function keyValue(raw) {
 				type: valueType
 			}
 		},
-		by: "key",
-		required: o.required
+		by: "key"
 	});
 }
 /** Roles of a range: the two endpoints, integer or real depending on `isInt`. */
@@ -9537,7 +9853,8 @@ var PRIMITIVES = {
 	url,
 	divider,
 	info,
-	button
+	button,
+	backrefs
 };
 /** Assembles `f`, guaranteeing no preset/block shadows a primitive. */
 function composeF(presets, blocks) {
@@ -9557,12 +9874,11 @@ var field = new Proxy({}, {
 	has: (_t, k) => k in composedField()
 });
 function toClient(field) {
-	const { kind, label, agent, required, prim, hints, options, strict, relation, json, hidden, derived, parts, cache } = field;
+	const { kind, label, agent, prim, hints, options, strict, relation, json, hidden, derived, parts, cache } = field;
 	return {
 		kind,
 		label,
 		...agent !== void 0 && { agent },
-		required,
 		prim,
 		hints,
 		options,
@@ -9640,7 +9956,7 @@ function accepts(def, d) {
 }
 /**
 * The correction every role gets for free: keep what the author said ABOUT the field
-* (`label`, `required`, `ui`, `value` — a constant or a ComputeFn), replace the type, and
+* (`label`, `ui`, `value` — a constant or a ComputeFn), replace the type, and
 * drop what belonged to the OLD type (`rules` — a number's min/max mean nothing to a
 * picture — and `multiple`, because a composite role owns exactly one column). A role whose
 * own default needs more than a bare factory (`measured`'s unit, `period`'s endpoints)
@@ -9648,10 +9964,9 @@ function accepts(def, d) {
 */
 function retypeTo(factory) {
 	return (d) => {
-		const { label, required, value } = d?.opts ?? {};
+		const { label, value } = d?.opts ?? {};
 		return declare(factory, {
 			label,
-			required,
 			value,
 			noSearch: d?.opts.noSearch,
 			ui: uiOf(d?.opts)
@@ -9837,13 +10152,69 @@ function partColumns(parts) {
 	}
 	return cols;
 }
-function partsRowShape(shape, parts, tolerance = "strict") {
+/**
+* A composite's write-time row shape, DERIVED from its resolved parts. `shape` carries
+* the composite's DEFAULT schema per role — the literal the factory writes by hand
+* (`{ value: numSchema, unit: z.string().refine(…) }`) — and each part decides which
+* schema guards its (role-named) key:
+*
+*  - a plain STORED part is keyed by its role name, matching the value object and the
+*    column `<field>__<role>` that `flattenEmbeddedAt`/`nestEmbeddedAt` read. A role left
+*    to its default filling keeps the default schema — byte-identical to the hand-written
+*    literal, so every existing structure/unit/range code and message is preserved.
+*  - an OVERRIDDEN stored part is validated by its OWN zod (`meta.zod`) instead of the
+*    default schema for that role. This is what makes a RETYPED filling real: an
+*    `f.int({})` magnitude rejects 5.5 (its own `int` check) and gets an integer column,
+*    and an `f.relation({…})` currency accepts a record id instead of being measured
+*    against an ISO-4217 string rule it was never meant to satisfy. The filling also
+*    brings its own optionality and its own min/max — an author replacing a filling
+*    takes over that role's constraints, so `f.real({ rules: { min: 0 } })` is how a
+*    replaced magnitude keeps a bound.
+*  - a COMPUTED-AND-STORED part ('computedStored') is keyed by its role name like any
+*    other part, but its schema is `z.unknown().optional()`: the SERVER owns the value, so
+*    whatever the client sends there is ignored — `stripServerOwnedParts` deletes it a
+*    moment later and the write path recomputes the column. It is stripped rather than
+*    `z.never()`-rejected because a read hands the client that key (it is a real column,
+*    present in every response), so rejecting it would break a read → PATCH-the-whole-object
+*    round trip.
+*  - a CLIENT-OWNED stored part of a composite also accepts
+*    an explicit `null` (`tolerateNull`), which is what closes the read → write round trip
+*    for a PARTIALLY FILLED composite. A SELECT returns every sub-column, so a record whose
+*    magnitude column is set and whose unit column is empty reads back as
+*    `{value: 900, unit: null}` (`nestEmbeddedAt` drops the key only when EVERY column is
+*    empty — `0` is a value), and feeding that exact object back used to fail with
+*    `measured_structure`: the write path refused the shape its own read produced. The null
+*    slot now parses through and is written back as NULL, so the round trip is closed and
+*    clearing ONE role of a filled composite works instead of erroring.
+*    NULL, not absence: a read emits every stored role (empty ones as `null`), so `null` is
+*    how "this record has no value there" arrives, while an ABSENT key is a writer that
+*    never mentioned a role it owns — which stays the structure error it has always been
+*    (`{unit: 'kg'}` with no magnitude, `{lat: 50}` with no longitude). That is the
+*    all-or-nothing rule for a DECLARATION, and it is untouched.
+* A composite used to be able to override this: `required: true` kept every client-owned
+*    slot MANDATORY, null included, so that "tolerate null" could not turn a demanded field
+*    optional. Nothing demands a value now, so there is no override and the rule above is the
+*    only one.
+*/
+/**
+* How much a CLIENT-OWNED slot forgives in the row shape: exactly one thing, an explicit
+* `null`. `.nullable()`, never `.nullish()` — a part that is MISSING entirely is still a
+* malformed row (`{lat: 5.5}` is half a coordinate), which is the one rule about composites
+* that judges CORRECTNESS rather than presence.
+*
+* There used to be a `RowTolerance` of three levels, and the field's `required` is what chose
+* between them: 'strict' when the field demanded a value, 'null-or-missing' when the value was
+* ABSENT under that demand — the third existing only so an absent required composite did not
+* report the same absence twice, once as `required` and once as a structure code. With nothing
+* able to demand a value there is no first issue to restate, so both levels and the type
+* itself are gone.
+*/
+function partsRowShape(shape, parts) {
 	const out = { ...shape };
 	for (const p of parts) if (p.mode === "computedStored") out[p.key] = unknown().optional();
 	else {
 		const own = p.overridden ? p.meta.zod : shape[p.role] ?? unknown().optional();
-		const relaxed = tolerance !== "strict" && !(p.overridden && p.meta.required === true);
-		out[p.key] = relaxed ? tolerance === "null-or-missing" ? own.nullish() : own.nullable() : own;
+		out[p.key] = own.nullable();
 	}
 	return out;
 }
@@ -9872,7 +10243,7 @@ function stripServerOwnedParts(value, parts) {
 * dimensions, check(single)) and differed only in the validation code and the per-role
 * default zod.
 *
-*   raw → jsonValue → absent by `absenceRoles`? (required → 'required')
+*   raw → jsonValue → carries nothing? (passthrough, when `acceptsEmptyRow`)
 *       → carries nothing at all? (pass through, there is nothing to judge)
 *       → rowSchema (partsRowShape) → stripServerOwnedParts → optional per-type refine
 *
@@ -9882,28 +10253,16 @@ function stripServerOwnedParts(value, parts) {
 * exactly once.
 */
 function buildComposite(def, opts, parts) {
-	const required = opts.required ?? false;
-	const roleZod = def.roleZod(opts, parts);
-	const rowSchema = object(partsRowShape(roleZod, parts, required === true ? "strict" : "null"));
-	const absentRowSchema = required === true ? object(partsRowShape(roleZod, parts, "null-or-missing")) : rowSchema;
+	const rowSchema = object(partsRowShape(def.roleZod(opts, parts), parts));
 	const roleKeys = (which) => parts.filter((p) => p.mode === "stored" && (which?.(p) ?? true)).map(partValueKey);
-	const absenceKeys = def.absenceRoles ? roleKeys((p) => def.absenceRoles.includes(p.role)) : void 0;
-	const clientKeys = def.absenceRoles ? roleKeys() : void 0;
+	const clientKeys = def.acceptsEmptyRow ? roleKeys() : void 0;
 	const zod = unknown().transform((raw, ctx) => {
 		const parsed = jsonValue(raw);
 		const p = parsed;
 		const isRow = p == null || typeof p === "object" && !Array.isArray(p);
 		/** Every one of `keys` empty in this value — `null`/absent alike. */
 		const allEmpty = (keys) => isRow && (p == null || keys.length > 0 && keys.every((k) => p[k] == null));
-		let absent = false;
-		if (absenceKeys && clientKeys) {
-			absent = allEmpty(absenceKeys);
-			if (absent && required) ctx.addIssue({
-				code: ZodIssueCode.custom,
-				message: vmsg("required")
-			});
-			if (allEmpty(clientKeys)) return raw;
-		}
+		if (clientKeys && allEmpty(clientKeys)) return raw;
 		if (typeof parsed === "string") {
 			ctx.addIssue({
 				code: ZodIssueCode.custom,
@@ -9911,7 +10270,7 @@ function buildComposite(def, opts, parts) {
 			});
 			return NEVER;
 		}
-		const r = (absent ? absentRowSchema : rowSchema).safeParse(parsed);
+		const r = rowSchema.safeParse(parsed);
 		if (!r.success) {
 			const message = typeof def.structureCode === "function" ? def.structureCode(r.error) : vmsg(def.structureCode);
 			ctx.addIssue({
@@ -9964,12 +10323,10 @@ function materialize(decl, name) {
 	if (isComposite(type) && (opts.multiple ?? false) && parts.length > 0 && !type.selfManages?.has("multiple")) return collectionGroup(name, opts, parts, type.collectionView);
 	const built = isComposite(type) ? buildComposite(type, opts, parts) : type.build(opts, parts, name);
 	const selfOptional = type.selfManages?.has("optional") ?? false;
-	const required = selfOptional ? false : opts.required ?? false;
 	const base = {
 		kind: type.kind,
 		label: opts.label ?? "",
 		...opts.agent !== void 0 && { agent: opts.agent },
-		required,
 		prim: type.prim,
 		column: built.column,
 		hints: built.hints ?? {},
@@ -9980,7 +10337,7 @@ function materialize(decl, name) {
 			columns: built.columns,
 			parts
 		},
-		zod: selfOptional ? built.zod : optionalize(built.zod, required)
+		zod: selfOptional ? built.zod : optionalize(built.zod)
 	};
 	return wrapKey(name, opts, type.selfManages?.has("multiple") ? base : applyMultiple(base, opts.multiple ?? false));
 }
@@ -10010,7 +10367,6 @@ function collectionGroup(key, opts, parts, collectionView) {
 		key,
 		scope: "nest",
 		multiple: true,
-		required: opts.required ?? false,
 		label: opts.label ?? key,
 		...opts.agent !== void 0 && { agent: opts.agent },
 		display: "wrap",
@@ -10139,6 +10495,8 @@ var src_default = definePlugin({
 	id: "webchat",
 	version: "1.0.0",
 	dependsOn: [],
+	label: "webchat.plugin.label",
+	description: "webchat.plugin.description",
 	settings: defineSettings({
 		label: "webchat.settings.label",
 		fields: { reasoning_display: field.string({