@coffer-org/plugin-documents 4.0.0 → 6.0.0

package/dist/person_identity/index.js

@@ -5,14 +5,14 @@ export default defineExtend({
     label: 'documents.person_identity.label',
     icon: 'lucide:globe',
     attachTo: [{ library: 'people', shelf: 'person' }],
-    claude: `Canonical person identity (not tied to a physical document).
+    agent: `Canonical person identity (not tied to a physical document).
 nationality — ISO alpha-2. variants — given/family name per language (field.keyed by lang: name+surname).`,
     fields: {
         nationality: field.string({
             label: 'documents.person_identity.fields.nationality',
             options: 'countries',
             strict: true,
-            view: { noSearch: true },
+            noSearch: true,
         }),
         variants: field.keyed({
             label: 'documents.person_identity.fields.variants',
@@ -22,7 +22,7 @@ nationality — ISO alpha-2. variants — given/family name per language (field.
                     label: 'documents.person_identity.variants.lang',
                     options: 'languages',
                     strict: true,
-                    view: { noSearch: true },
+                    noSearch: true,
                 }),
                 name: field.string({ label: 'documents.person_identity.variants.name' }),
                 surname: field.string({ label: 'documents.person_identity.variants.surname' }),

package/dist/personal_document/index.js

@@ -12,7 +12,7 @@ export default defineShelf({
         name: field.title({ label: 'core.fields.name' }),
         about: field.illustrated({
             label: 'documents.personal_document.fields.about',
-            fields: { image: field.avatar({ role: 'avatar' }), text: field.text({ rules: { max: 1000 } }) },
+            fields: { image: field.avatar({ ui: { role: 'avatar' } }), text: field.text({ rules: { max: 1000 } }) },
         }),
         idcard: field.idcard({
             number: { number: field.string({ label: 'documents.personal_document.fields.number', rules: { max: 50 } }) },
@@ -38,7 +38,7 @@ export default defineShelf({
         sex: field.string({
             label: 'documents.personal_document.fields.sex',
             strict: true,
-            view: { noSearch: true },
+            noSearch: true,
             options: [
                 { value: 'M', title: 'documents.personal_document.options.sex.M' },
                 { value: 'F', title: 'documents.personal_document.options.sex.F' },
@@ -49,7 +49,7 @@ export default defineShelf({
             label: 'documents.personal_document.fields.nationality',
             options: 'countries',
             strict: true,
-            view: { noSearch: true },
+            noSearch: true,
             ui: { span: 4 },
         }),
         owner: field.relation({
@@ -73,7 +73,7 @@ export default defineShelf({
             label: 'core.fields.type',
             required: true,
             strict: true,
-            view: { noSearch: true },
+            noSearch: true,
             options: [
                 { value: 'P', title: 'documents.personal_document.options.type.P' },
                 { value: 'PA', title: 'documents.personal_document.options.type.PA' },

package/dist/schema.js

@@ -4371,8 +4371,28 @@ var UNITS_MAP = {
 		label: "core.units.ppm"
 	}]
 };
+/**
+* Resolve a unit spec — a named scale or an explicit option list — to its options.
+*
+* Throws rather than returning `undefined`, because both ways of reaching `undefined` here
+* produce a field that CONSTRUCTS and then crashes when someone tries to save through it:
+* `measured`'s unit role closes over these options and calls `.some(…)` on them inside its
+* refine, so a missing spec or a typo'd scale name turns a user's save into a
+* `Cannot read properties of undefined` instead of a validation message. The golden matrix
+* recorded exactly that for `f.measured({})`.
+*
+* A declaration error belongs at declaration time, where the plugin author sees it and the
+* message can name the scale they meant — the same reason the host-services seam fails at
+* registration rather than at first render.
+*/
 function resolveUnits(u) {
-	return typeof u === "string" ? UNITS_MAP[u] : u;
+	if (typeof u === "string") {
+		const known = UNITS_MAP[u];
+		if (!known) throw new Error(`units: unknown scale '${u}' (known: ${Object.keys(UNITS_MAP).sort().join(", ")})`);
+		return known;
+	}
+	if (!Array.isArray(u)) throw new Error("units: a unit spec is required — a named scale, or an explicit list of options");
+	return u;
 }
 //#endregion
 //#region ../sdk/src/fields/validation.ts
@@ -4395,6 +4415,23 @@ function typeErr(code = "invalid_type") {
 function reqTypeErr() {
 	return { error: (iss) => iss.code === "invalid_type" ? iss.input === void 0 ? vmsg("required") : vmsg("invalid_type") : void 0 };
 }
+/**
+* A string schema whose CONTENT checks only speak once the value is known to be a string.
+*
+* zod's length checks are not type-guarded: `min`/`max` read `input.length`, and an ARRAY has
+* one. So `z.string().min(1)` answers `[]` with `invalid_type` AND `too_small` — two messages
+* about a single wrongness, both of which reach the user, since `mutate.ts` and `extend-io.ts`
+* turn every issue into its own `ValidationError`. (A number answers with `invalid_type`
+* alone, having no `length` to read — so the redundancy was array-shaped and invisible until
+* the golden matrix started recording the whole issue list instead of `issues[0]`.)
+*
+* Piping puts the type question first and alone: `add` never runs on a non-string. Pass the
+* content checks as a builder rather than chaining them onto the result, because a `ZodPipe`
+* has no `.min`/`.max`/`.regex` to chain.
+*/
+function stringContent(add) {
+	return string$1(reqTypeErr()).pipe(add(string$1()));
+}
 /** Parse a JSON string, else return the native value (object/array) as-is.
 *  Tolerant input for native form-state AND legacy JSON-string payloads.
 *  A string that fails JSON.parse is returned unchanged — callers detect
@@ -4650,6 +4687,13 @@ function wrapKey(key, opts, meta) {
 			editor: opts.editor
 		}
 	};
+	if (opts.activate) m = {
+		...m,
+		hints: {
+			...m.hints,
+			activate: opts.activate
+		}
+	};
 	if (opts.span !== void 0) m = {
 		...m,
 		hints: {
@@ -4721,11 +4765,10 @@ function wrapKey(key, opts, meta) {
 //#region ../sdk/src/fields/normalize.ts
 function normalizeOpts(rawIn) {
 	const raw = rawIn;
+	if (raw["view"] !== void 0) throw new Error("[normalizeOpts] `view` is gone — presentational options live in `ui: {}` (see CLAUDE.md § field author options and the field-types skill).");
+	if (raw.ui?.["agent"] !== void 0) throw new Error("[normalizeOpts] `agent` is not presentation — declare it at the top level of the field call, not in `ui: {}`.");
 	const r = raw.rules ?? {};
-	const v = {
-		...raw.view ?? {},
-		...raw.ui ?? {}
-	};
+	const v = raw.ui ?? {};
 	const config = {};
 	if (r.min != null && typeof r.min === "number") config.min = r.min;
 	if (r.max != null && typeof r.max === "number") config.max = r.max;
@@ -4734,7 +4777,7 @@ function normalizeOpts(rawIn) {
 	if (r.messageKey != null) config.messageKey = r.messageKey;
 	if (r.granularity != null) config.granularity = r.granularity;
 	if (r.language != null) config.language = r.language;
-	const { rules: _r, view: _v, ui: _ui, ...flat } = raw;
+	const { rules: _r, ui: _ui, ...flat } = raw;
 	const result = {
 		...flat,
 		...Object.keys(config).length ? { config } : {},
@@ -4749,7 +4792,6 @@ function normalizeOpts(rawIn) {
 		step: r.step,
 		hidden: v.hidden,
 		noEditControl: v.noEditControl,
-		noSearch: v.noSearch,
 		display: v.display,
 		kind: v.kind,
 		icon: v.icon,
@@ -4757,7 +4799,12 @@ function normalizeOpts(rawIn) {
 		...v.keyLabel !== void 0 ? { keyLabel: v.keyLabel } : {},
 		...v.valueLabel !== void 0 ? { valueLabel: v.valueLabel } : {},
 		compareWith: v.compareWith,
-		span: v.span
+		span: v.span,
+		emphasis: v.emphasis,
+		noLabel: v.noLabel,
+		role: v.role,
+		editor: v.editor,
+		activate: v.activate
 	};
 	return Object.fromEntries(Object.entries(result).filter(([, val]) => val !== void 0));
 }
@@ -4908,16 +4955,17 @@ function registerPreset(factory, base, presetOpts, over = {}) {
 function buildComposite(def, opts, parts) {
 	const required = opts.required ?? false;
 	const roleZod = def.roleZod(opts, parts);
-	const rowSchema = object(partsRowShape(roleZod, parts, required !== true));
-	const absentRowSchema = required === true ? object(partsRowShape(roleZod, parts, true)) : rowSchema;
+	const rowSchema = object(partsRowShape(roleZod, parts, required === true ? "strict" : "null"));
+	const absentRowSchema = required === true ? object(partsRowShape(roleZod, parts, "null-or-missing")) : rowSchema;
 	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 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) => p == null || typeof p === "object" && keys.length > 0 && keys.every((k) => p[k] == null);
+		const allEmpty = (keys) => isRow && (p == null || keys.length > 0 && keys.every((k) => p[k] == null));
 		let absent = false;
 		if (absenceKeys && clientKeys) {
 			absent = allEmpty(absenceKeys);
@@ -4991,6 +5039,7 @@ function materialize(decl, name) {
 	const base = {
 		kind: type.kind,
 		label: opts.label ?? "",
+		...opts.agent !== void 0 && { agent: opts.agent },
 		required,
 		prim: type.prim,
 		column: built.column,
@@ -5034,6 +5083,7 @@ function collectionGroup(key, opts, parts, collectionView) {
 		multiple: true,
 		required: opts.required ?? false,
 		label: opts.label ?? key,
+		...opts.agent !== void 0 && { agent: opts.agent },
 		display: "wrap",
 		kind: collectionView,
 		fields: rowFields
@@ -5157,15 +5207,14 @@ function materializeDef(def) {
 * open: a magnitude may be real/int/rating, a unit may be a select or a relation.
 */
 /**
-* `NormalizedOpts` (what `FieldDecl.opts` actually is) has no single `view` property — the
-* author's `view`/`ui` are flattened into individual fields (`hidden`, `display`, `kind`, …)
-* by `normalizeOpts`. A correction that wants to carry "view" forward has to collect those
-* flat fields back into the nested shape `declare()`'s own `normalizeOpts` call expects.
+* `NormalizedOpts` (what `FieldDecl.opts` actually is) has no single `ui` property — the
+* author's `ui` is flattened into individual fields (`hidden`, `display`, `kind`, …)
+* by `normalizeOpts`. A correction that wants to carry presentation forward has to collect
+* those flat fields back into the nested shape `declare()`'s own `normalizeOpts` call expects.
 */
-var VIEW_KEYS = [
+var UI_KEYS = [
 	"hidden",
 	"noEditControl",
-	"noSearch",
 	"display",
 	"kind",
 	"icon",
@@ -5176,11 +5225,11 @@ var VIEW_KEYS = [
 	"span"
 ];
 /** The author's presentation opts, re-nested from `opts`'s flat fields — `undefined` when
-*  none were set, so a correction never adds an empty `view: {}` no filling ever had. */
-function viewOf(opts) {
+*  none were set, so a correction never adds an empty `ui: {}` no filling ever had. */
+function uiOf(opts) {
 	if (!opts) return void 0;
 	const v = {};
-	for (const k of VIEW_KEYS) if (opts[k] !== void 0) v[k] = opts[k];
+	for (const k of UI_KEYS) if (opts[k] !== void 0) v[k] = opts[k];
 	return Object.keys(v).length ? v : void 0;
 }
 /** A filling built from a ported factory arrives as a FieldDecl — build it into the
@@ -5203,7 +5252,7 @@ function accepts(def, d) {
 }
 /**
 * The correction every role gets for free: keep what the author said ABOUT the field
-* (`label`, `required`, `view`, `value` — a constant or a ComputeFn), replace the type, and
+* (`label`, `required`, `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)
@@ -5216,7 +5265,8 @@ function retypeTo(factory) {
 			label,
 			required,
 			value,
-			view: viewOf(d?.opts)
+			noSearch: d?.opts.noSearch,
+			ui: uiOf(d?.opts)
 		});
 	};
 }
@@ -5399,56 +5449,13 @@ function partColumns(parts) {
 	}
 	return cols;
 }
-/**
-* 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 that is not `required: true` 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 `required: true` composite keeps every client-owned slot MANDATORY, null included —
-*    "tolerate null" must not turn a required field optional, so an empty or half-empty
-*    value still fails with the same structure code it fails with today. A filling the
-*    author declared `required` keeps its own mandate too.
-*/
-function partsRowShape(shape, parts, tolerateNull = false) {
+function partsRowShape(shape, parts, tolerance = "strict") {
 	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();
-		out[p.key] = tolerateNull && !(p.overridden && p.meta.required === true) ? own.nullable() : own;
+		const relaxed = tolerance !== "strict" && !(p.overridden && p.meta.required === true);
+		out[p.key] = relaxed ? tolerance === "null-or-missing" ? own.nullish() : own.nullable() : own;
 	}
 	return out;
 }
@@ -5643,7 +5650,7 @@ function internalApiToken(o) {
 		label: o.label,
 		multiple: true,
 		rules: { unique: ["name"] },
-		view: { kind: "internalApiToken" },
+		ui: { kind: "internalApiToken" },
 		fields: {
 			name: string({}),
 			token: password({}),
@@ -5669,7 +5676,7 @@ function internalOauthGrants(o) {
 		scope: "nest",
 		label: o.label,
 		multiple: true,
-		view: { kind: "internalOauthGrants" },
+		ui: { kind: "internalOauthGrants" },
 		fields: {
 			clientName: string({}),
 			createdAt: string({}),
@@ -6296,10 +6303,8 @@ function country(raw) {
 		...raw,
 		options: "countries",
 		strict: true,
-		view: {
-			...raw.view ?? {},
-			noSearch: true
-		}
+		ui: { ...raw.ui ?? {} },
+		noSearch: true
 	});
 }
 /**
@@ -6323,10 +6328,8 @@ function currency(raw) {
 		...raw,
 		options: "currencies",
 		strict: true,
-		view: {
-			...raw.view ?? {},
-			noSearch: true
-		}
+		ui: { ...raw.ui ?? {} },
+		noSearch: true
 	});
 }
 /**
@@ -6486,7 +6489,7 @@ function bento(opts) {
 			label: opts.label,
 			icon: opts.icon,
 			fields,
-			view: { kind: "bento" }
+			ui: { kind: "bento" }
 		}),
 		view: {
 			kind: "bento",
@@ -6515,7 +6518,7 @@ function split(opts) {
 	return {
 		...group({
 			fields: merge("split", opts.columns[0], opts.columns[1]),
-			view: { kind: "split" }
+			ui: { kind: "split" }
 		}),
 		view: {
 			kind: "split",
@@ -6539,7 +6542,7 @@ function grid(opts) {
 			label: opts.label,
 			icon: opts.icon,
 			fields: opts.fields,
-			view: { kind: "grid" }
+			ui: { kind: "grid" }
 		}),
 		view: {
 			kind: "grid",
@@ -6564,7 +6567,7 @@ function spread(opts) {
 	return {
 		...group({
 			fields: merge("spread", visual, quote, opts.facts),
-			view: { kind: "spread" }
+			ui: { kind: "spread" }
 		}),
 		view: {
 			kind: "spread",
@@ -6589,7 +6592,7 @@ function aside(opts) {
 	return {
 		...group({
 			fields: merge("aside", opts.fields, opts.aside),
-			view: { kind: "aside" }
+			ui: { kind: "aside" }
 		}),
 		view: {
 			kind: "aside",
@@ -6621,7 +6624,7 @@ function tabs(opts) {
 	return {
 		...group({
 			fields,
-			view: { kind: "tabs" }
+			ui: { kind: "tabs" }
 		}),
 		view: {
 			kind: "tabs",
@@ -6653,7 +6656,7 @@ function accordion(opts) {
 	return {
 		...group({
 			fields,
-			view: { kind: "accordion" }
+			ui: { kind: "accordion" }
 		}),
 		view: {
 			kind: "accordion",
@@ -6683,7 +6686,7 @@ function prose(opts) {
 			label: opts.label,
 			icon: opts.icon,
 			fields: opts.fields,
-			view: { kind: "prose" }
+			ui: { kind: "prose" }
 		}),
 		view: {
 			kind: "prose",
@@ -6709,7 +6712,7 @@ function plaque(opts) {
 			label: opts.label,
 			icon: opts.icon,
 			fields: merge("plaque", title, opts.subtitle),
-			view: { kind: "plaque" }
+			ui: { kind: "plaque" }
 		}),
 		view: {
 			kind: "plaque",
@@ -6732,7 +6735,7 @@ function ledger(opts) {
 			label: opts.label,
 			icon: opts.icon,
 			fields: opts.fields,
-			view: { kind: "ledger" }
+			ui: { kind: "ledger" }
 		}),
 		view: { kind: "ledger" }
 	};
@@ -6751,7 +6754,7 @@ function stats(opts) {
 			label: opts.label,
 			icon: opts.icon,
 			fields: opts.fields,
-			view: { kind: "stats" }
+			ui: { kind: "stats" }
 		}),
 		view: { kind: "stats" }
 	};
@@ -6770,7 +6773,7 @@ function facets(opts) {
 			label: opts.label,
 			icon: opts.icon,
 			fields: opts.fields,
-			view: { kind: "facets" }
+			ui: { kind: "facets" }
 		}),
 		view: { kind: "facets" }
 	};
@@ -6789,7 +6792,7 @@ function terminal(opts) {
 			label: opts.label,
 			icon: opts.icon,
 			fields: opts.fields,
-			view: { kind: "terminal" }
+			ui: { kind: "terminal" }
 		}),
 		view: {
 			kind: "terminal",
@@ -6811,7 +6814,7 @@ function callout(opts) {
 			label: opts.label,
 			icon: opts.icon,
 			fields: opts.fields,
-			view: { kind: "callout" }
+			ui: { kind: "callout" }
 		}),
 		view: {
 			kind: "callout",
@@ -6836,7 +6839,7 @@ function compare(opts) {
 			label: opts.label,
 			icon: opts.icon,
 			fields: merge("compare", opts.left, opts.right),
-			view: { kind: "compare" }
+			ui: { kind: "compare" }
 		}),
 		view: {
 			kind: "compare",
@@ -6867,7 +6870,7 @@ function figure(opts) {
 	return {
 		...group({
 			fields: merge("figure", image, caption),
-			view: { kind: "figure" }
+			ui: { kind: "figure" }
 		}),
 		view: {
 			kind: "figure",
@@ -6892,7 +6895,7 @@ function epigraph(opts) {
 	return {
 		...group({
 			fields: merge("epigraph", source, attribution),
-			view: { kind: "epigraph" }
+			ui: { kind: "epigraph" }
 		}),
 		view: {
 			kind: "epigraph",
@@ -6918,7 +6921,7 @@ function masthead(opts) {
 	return {
 		...group({
 			fields: merge("masthead", overline, title, opts.meta),
-			view: { kind: "masthead" }
+			ui: { kind: "masthead" }
 		}),
 		view: {
 			kind: "masthead",
@@ -6942,7 +6945,7 @@ function timeline(opts) {
 			label: opts.label,
 			icon: opts.icon,
 			fields: opts.fields,
-			view: { kind: "timeline" }
+			ui: { kind: "timeline" }
 		}),
 		view: { kind: "timeline" }
 	};
@@ -6961,7 +6964,7 @@ function countdown(opts) {
 		...group({
 			label: opts.label,
 			fields: source,
-			view: { kind: "countdown" }
+			ui: { kind: "countdown" }
 		}),
 		view: {
 			kind: "countdown",
@@ -6984,7 +6987,7 @@ function deck(opts) {
 		...group({
 			label: opts.label,
 			fields: source,
-			view: { kind: "deck" }
+			ui: { kind: "deck" }
 		}),
 		view: {
 			kind: "deck",
@@ -7006,7 +7009,7 @@ function people(opts) {
 		...group({
 			label: opts.label,
 			fields: source,
-			view: { kind: "people" }
+			ui: { kind: "people" }
 		}),
 		view: {
 			kind: "people",
@@ -7032,7 +7035,7 @@ function identity(opts) {
 	return {
 		...group({
 			fields: merge("identity", avatar, name, role, opts.channels),
-			view: { kind: "identity" }
+			ui: { kind: "identity" }
 		}),
 		view: {
 			kind: "identity",
@@ -7058,7 +7061,7 @@ function score(opts) {
 		...group({
 			label: opts.label,
 			fields: merge("score", source, verdict),
-			view: { kind: "score" }
+			ui: { kind: "score" }
 		}),
 		view: {
 			kind: "score",
@@ -7083,7 +7086,7 @@ function status(opts) {
 		...group({
 			label: opts.label,
 			fields: merge("status", source, since),
-			view: { kind: "status" }
+			ui: { kind: "status" }
 		}),
 		view: {
 			kind: "status",
@@ -7107,7 +7110,7 @@ function meter(opts) {
 		...group({
 			label: opts.label,
 			fields: merge("meter", source, of),
-			view: { kind: "meter" }
+			ui: { kind: "meter" }
 		}),
 		view: {
 			kind: "meter",
@@ -7134,7 +7137,7 @@ function receipt(opts) {
 		...group({
 			label: opts.label,
 			fields: merge("receipt", opts.fields, total),
-			view: { kind: "receipt" }
+			ui: { kind: "receipt" }
 		}),
 		view: {
 			kind: "receipt",
@@ -7157,7 +7160,7 @@ function balance(opts) {
 		...group({
 			label: opts.label,
 			fields: source,
-			view: { kind: "balance" }
+			ui: { kind: "balance" }
 		}),
 		view: {
 			kind: "balance",
@@ -7185,7 +7188,7 @@ function route(opts) {
 	return {
 		...group({
 			fields: merge("route", from, to, depart, arrive, duration),
-			view: { kind: "route" }
+			ui: { kind: "route" }
 		}),
 		view: {
 			kind: "route",
@@ -7334,7 +7337,7 @@ function nutrition(opts) {
 		...group({
 			label: opts.label,
 			fields: merge("nutrition", energy, opts.fields),
-			view: { kind: "nutrition" }
+			ui: { kind: "nutrition" }
 		}),
 		view: {
 			kind: "nutrition",
@@ -7360,7 +7363,7 @@ function specimen(opts) {
 	return {
 		...group({
 			fields: merge("specimen", title, subtitle, opts.conditions),
-			view: { kind: "specimen" }
+			ui: { kind: "specimen" }
 		}),
 		view: {
 			kind: "specimen",
@@ -7437,7 +7440,7 @@ function idcard(opts) {
 	return {
 		...group({
 			fields: merge("idcard", overline, number, opts.meta),
-			view: { kind: "idcard" }
+			ui: { kind: "idcard" }
 		}),
 		view: {
 			kind: "idcard",
@@ -7463,7 +7466,7 @@ function properties(opts) {
 			label: opts.label,
 			icon: opts.icon,
 			fields: opts.fields,
-			view: { kind: "properties" }
+			ui: { kind: "properties" }
 		}),
 		view: {
 			kind: "properties",
@@ -7485,7 +7488,7 @@ function stack(opts) {
 			label: opts.label,
 			icon: opts.icon,
 			fields: opts.fields,
-			view: { kind: "stack" }
+			ui: { kind: "stack" }
 		}),
 		view: { kind: "stack" }
 	};
@@ -8381,8 +8384,9 @@ var isNamedField = (x) => hasValue(x) && !hasChildren(x) && x.key !== void 0;
 * @example f.group({ scope: 'nest', label: 'mod.fields.contact', fields: { name: f.string({}) } })
 */
 function group(o) {
+	if (o["view"] !== void 0) throw new Error("[group] `view` is gone — presentational options live in `ui: {}` (see CLAUDE.md § field author options and the field-types skill).");
 	const r = o.rules ?? {};
-	const v = o.view ?? {};
+	const v = o.ui ?? {};
 	const fields = materializeTree(o.fields);
 	const scope = o.scope ?? "hoist";
 	if (scope === "nest") {
@@ -8428,7 +8432,7 @@ function row(o) {
 		multiple: o.multiple,
 		required: o.required,
 		rules: o.rules,
-		view: { display: "scroll" }
+		ui: { display: "scroll" }
 	});
 }
 /**
@@ -8456,7 +8460,7 @@ function sheet(o) {
 		label: o.label,
 		icon: o.icon,
 		fields: rows,
-		view: { display: "sheet" }
+		ui: { display: "sheet" }
 	});
 }
 /**
@@ -8475,7 +8479,7 @@ function url(o) {
 		scope: "nest",
 		label: o.label,
 		required: o.required,
-		view: { kind: "url" },
+		ui: { kind: "url" },
 		fields: {
 			scheme: string({}),
 			username: string({}),
@@ -8637,13 +8641,15 @@ registerType("string", {
 	build(o) {
 		const cfg = o.config ?? {};
 		const min = cfg.min ?? (o.required === true ? 1 : 0);
-		let s = string$1(reqTypeErr());
-		if (min > 0) s = s.min(min, { message: vmsg("min_length", { min }) });
-		if (cfg.max != null) s = s.max(cfg.max, { message: vmsg("max_length", { max: cfg.max }) });
-		if (cfg.pattern) s = s.regex(new RegExp(cfg.pattern), { message: vmsg("pattern", cfg.messageKey ? { messageKey: cfg.messageKey } : void 0) });
 		return {
 			column: "text",
-			zod: s,
+			zod: stringContent((str) => {
+				let c = str;
+				if (min > 0) c = c.min(min, { message: vmsg("min_length", { min }) });
+				if (cfg.max != null) c = c.max(cfg.max, { message: vmsg("max_length", { max: cfg.max }) });
+				if (cfg.pattern) c = c.regex(new RegExp(cfg.pattern), { message: vmsg("pattern", cfg.messageKey ? { messageKey: cfg.messageKey } : void 0) });
+				return c;
+			}),
 			hints: {
 				minLength: cfg.min,
 				maxLength: cfg.max
@@ -8664,9 +8670,7 @@ function string(o) {
 }
 /** Shared by localDir/localFile's build(): a server path, min-length-1 when required. */
 function pathZod(o) {
-	let s = string$1(reqTypeErr());
-	if (o.required === true) s = s.min(1, { message: vmsg("min_length", { min: 1 }) });
-	return s;
+	return stringContent((s) => o.required === true ? s.min(1, { message: vmsg("min_length", { min: 1 }) }) : s);
 }
 registerType("localDir", {
 	kind: "localDir",
@@ -9328,7 +9332,8 @@ var MEASURED_ROLES = (opts) => {
 				label,
 				required,
 				value,
-				view: viewOf(d?.opts),
+				noSearch: d?.opts.noSearch,
+				ui: uiOf(d?.opts),
 				options: opts.units,
 				strict: true
 			});
@@ -9697,7 +9702,7 @@ function periodMkSubDecl(granularity) {
 * (`mkSubDecl`), so it writes its own `normalize` rather than using `role()`. A CORRECTED
 * filling still keeps the composite's own granularity (`canonical.opts`) — the same
 * `date`/`datetime` config the role's own default carries — with the author's
-* label/required/view/value layered on top, exactly like `retypeTo`'s default.
+* label/required/ui/value layered on top, exactly like `retypeTo`'s default.
 */
 function periodRole(key, label, mkSubDecl) {
 	const def = {
@@ -9713,7 +9718,8 @@ function periodRole(key, label, mkSubDecl) {
 				label: l ?? canonical.opts.label,
 				required,
 				value,
-				view: viewOf(d.opts)
+				noSearch: d.opts.noSearch,
+				ui: uiOf(d.opts)
 			});
 		}
 	};
@@ -10181,10 +10187,11 @@ var field = new Proxy({}, {
 	has: (_t, k) => k in composedField()
 });
 function toClient(field) {
-	const { kind, label, required, prim, hints, options, strict, relation, json, hidden, derived, parts, cache } = field;
+	const { kind, label, agent, required, prim, hints, options, strict, relation, json, hidden, derived, parts, cache } = field;
 	return {
 		kind,
 		label,
+		...agent !== void 0 && { agent },
 		required,
 		prim,
 		hints,
@@ -10972,7 +10979,7 @@ function defineShelf(m) {
 	const keys = fieldEntries(built.fields).map(([k]) => k);
 	const dup = keys.find((k, i) => keys.indexOf(k) !== i);
 	if (dup) throw new Error(`[shelf] ${built.library}/${built.shelf}: duplicate key '${dup}'`);
-	if (built.single && !built.claude) throw new Error(`[shelf] ${built.library}/${built.shelf}: single shelf requires \`claude\` — the agent cannot find it otherwise`);
+	if (built.single && !built.agent) throw new Error(`[shelf] ${built.library}/${built.shelf}: single shelf requires \`agent\` — the agent cannot find it otherwise`);
 	if (built.views?.list !== void 0 && !Array.isArray(built.views.list)) throw new Error(`[shelf] ${built.library}/${built.shelf}: views.list is a flat array of field keys — the { kind, fields } form is gone; use views.list: [...] plus views.listKind`);
 	if (built.standalone !== false && !built.single && !built.views?.list?.length) console.warn(`[shelf] ${built.library}/${built.shelf}: standalone shelf without an explicit views.list`);
 	if (built.views?.title && !ownFieldEntries(built.fields).some(([k]) => k === built.views.title)) throw new Error(`[shelf] ${built.library}/${built.shelf}: views.title '${built.views.title}' is not a field`);
@@ -11032,7 +11039,7 @@ var personal_document_default = defineShelf({
 		about: field.illustrated({
 			label: "documents.personal_document.fields.about",
 			fields: {
-				image: field.avatar({ role: "avatar" }),
+				image: field.avatar({ ui: { role: "avatar" } }),
 				text: field.text({ rules: { max: 1e3 } })
 			}
 		}),
@@ -11070,7 +11077,7 @@ var personal_document_default = defineShelf({
 		sex: field.string({
 			label: "documents.personal_document.fields.sex",
 			strict: true,
-			view: { noSearch: true },
+			noSearch: true,
 			options: [{
 				value: "M",
 				title: "documents.personal_document.options.sex.M"
@@ -11084,7 +11091,7 @@ var personal_document_default = defineShelf({
 			label: "documents.personal_document.fields.nationality",
 			options: "countries",
 			strict: true,
-			view: { noSearch: true },
+			noSearch: true,
 			ui: { span: 4 }
 		}),
 		owner: field.relation({
@@ -11121,7 +11128,7 @@ var personal_document_default = defineShelf({
 			label: "core.fields.type",
 			required: true,
 			strict: true,
-			view: { noSearch: true },
+			noSearch: true,
 			options: [
 				{
 					value: "P",
@@ -11189,14 +11196,14 @@ var person_identity_default = defineExtend({
 		library: "people",
 		shelf: "person"
 	}],
-	claude: `Canonical person identity (not tied to a physical document).
+	agent: `Canonical person identity (not tied to a physical document).
 nationality — ISO alpha-2. variants — given/family name per language (field.keyed by lang: name+surname).`,
 	fields: {
 		nationality: field.string({
 			label: "documents.person_identity.fields.nationality",
 			options: "countries",
 			strict: true,
-			view: { noSearch: true }
+			noSearch: true
 		}),
 		variants: field.keyed({
 			label: "documents.person_identity.fields.variants",
@@ -11206,7 +11213,7 @@ nationality — ISO alpha-2. variants — given/family name per language (field.
 					label: "documents.person_identity.variants.lang",
 					options: "languages",
 					strict: true,
-					view: { noSearch: true }
+					noSearch: true
 				}),
 				name: field.string({ label: "documents.person_identity.variants.name" }),
 				surname: field.string({ label: "documents.person_identity.variants.surname" })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffer-org/plugin-documents",
-  "version": "4.0.0",
+  "version": "6.0.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -26,9 +26,9 @@
     "postpack": "node ../../scripts/swap-exports.mjs src"
   },
   "dependencies": {
-    "@coffer-org/plugin-people": "^4.0.0",
-    "@coffer-org/sdk": "^4.0.0",
-    "@coffer-org/server": "^4.0.0"
+    "@coffer-org/plugin-people": "^6.0.0",
+    "@coffer-org/sdk": "^6.0.0",
+    "@coffer-org/server": "^6.0.0"
   },
   "coffer": {
     "runtime": "node",