@tai42/studio-sdk 22.2.0 → 22.4.0

package/src/schema-form/classify.ts

@@ -213,10 +213,10 @@ function classifyAllOf(
 }
 
 /**
- * The platform date constraints on a `date`/`date-time` string property (scope C), or
+ * The platform date constraints on a `date`/`date-time` string property, or
  * `undefined` for a plain or non-date string. Each key is read defensively (the schema is
  * permissive); a date property with no constraint key classifies with `date: undefined`
- * so it renders exactly as before.
+ * and draws the plain date or date-time control with no bounds.
  */
 function dateConstraints(resolved: JsonSchema): DateConstraints | undefined {
   if (resolved.format !== 'date' && resolved.format !== 'date-time') return undefined;
@@ -312,7 +312,7 @@ function classifyArray(
   }
   // An array whose items are a FIXED set of strings (an `enum` on the items, or a
   // per-send option list that set one) is a multi-select: a checkbox group over a known
-  // option set (scope E). An array of free strings keeps the add/remove `array` field.
+  // option set. An array of free strings keeps the add/remove `array` field.
   const items = resolveRef(resolved.items, root);
   const itemTypes = typeList(items);
   const isStringItems = itemTypes.length === 1 && itemTypes[0] === 'string';

package/src/schema-form/default-value.ts

@@ -66,18 +66,19 @@ function seedObject(
   root: JsonSchema,
   mintScalars: boolean,
 ): Record<string, unknown> {
-  const result: Record<string, unknown> = {};
+  const entries: [string, unknown][] = [];
   for (const [name, propSchema] of model.properties) {
     if (model.required.has(name)) {
       const seeded = seedValue(propSchema, root, mintScalars);
-      if (seeded !== undefined) result[name] = seeded;
+      if (seeded !== undefined) entries.push([name, seeded]);
       continue;
     }
     const propClassified = classifySchema(propSchema, root);
     const propDefault = explicitDefault(propSchema, propClassified.schema);
-    if (propDefault.present) result[name] = propDefault.value;
+    if (propDefault.present) entries.push([name, propDefault.value]);
   }
-  return result;
+  // Built from entries so every property name, `__proto__` included, lands as an own key.
+  return Object.fromEntries(entries);
 }
 
 /**

package/src/schema-form/field-model.ts

@@ -29,8 +29,8 @@ export interface MediaUpload {
 }
 
 /**
- * The platform date constraints classified off a `date`/`date-time` string property
- * (scope C). `min`/`max` are inclusive `YYYY-MM-DD` bounds (passed to the native date
+ * The platform date constraints classified off a `date`/`date-time` string property.
+ * `min`/`max` are inclusive `YYYY-MM-DD` bounds (passed to the native date
  * control and enforced by the validator); `unavailable` is the set of excluded days
  * (the native control cannot disable arbitrary days, so this is validator-enforced).
  * A date RANGE is two ordinary date fields: on the END field, `rangeStart` names its
@@ -143,7 +143,7 @@ export type FieldModel =
        *  field into the jq expression editor (see {@link ExpressionAnnotation}). */
       readonly expression: ExpressionAnnotation | undefined;
       /** Present on a `date`/`date-time` string carrying any platform date
-       *  constraint (bounds, unavailable days, or range pairing — scope C). */
+       *  constraint (bounds, unavailable days, or range pairing). */
       readonly date: DateConstraints | undefined;
     }
   | { readonly kind: 'number'; readonly integer: boolean }

package/src/schema-form/field-node.tsx

@@ -9,6 +9,7 @@ import { memo, type ReactNode } from 'react';
 import { Checkbox } from '../components/checkbox';
 import { Field } from '../components/field';
 import { NumberInput, TextInput } from '../components/inputs';
+import { ownValue } from '../guards';
 import { ArrayField } from './array-field';
 import { classifySchema } from './classify';
 import { EnumField } from './enum-field';
@@ -46,7 +47,7 @@ interface FieldNodeProps {
    * its direct `enum`-select children draw their placeholder. Carried by the root form
    * only; nested objects receive none.
    */
-  readonly fieldWording?: Readonly<Record<string, { choiceLabel?: string }>>;
+  readonly fieldWording?: Readonly<Record<string, { choiceLabel?: string; invalid?: string }>>;
   /** This field's own picker placeholder, when it draws as an `enum` select. */
   readonly choiceLabel?: string;
 }
@@ -73,7 +74,7 @@ function FieldNodeImpl(props: FieldNodeProps): ReactNode {
     nullable: classified.nullable,
     heading,
     description,
-    error: errors?.[path],
+    error: ownValue(errors, path),
     root,
     value,
     onChange,
@@ -100,7 +101,7 @@ interface RenderFieldArgs {
   readonly required: boolean;
   readonly errors: SchemaFormErrors | undefined;
   readonly idPrefix: string;
-  readonly fieldWording?: Readonly<Record<string, { choiceLabel?: string }>>;
+  readonly fieldWording?: Readonly<Record<string, { choiceLabel?: string; invalid?: string }>>;
   readonly choiceLabel?: string;
 }
 

package/src/schema-form/multiselect-field.tsx

@@ -1,5 +1,5 @@
 /**
- * The multi-select field renderer (scope E): an array of a fixed set of strings drawn
+ * The multi-select field renderer: an array of a fixed set of strings drawn
  * as a checkbox group, one checkbox per option, emitting a `string[]`. Classification
  * lands an array here only when its items carry a known option set (an `enum`, or a
  * per-send option list), so there is always a definite set of boxes to draw; an array of

package/src/schema-form/object-fields.tsx

@@ -6,6 +6,7 @@
  */
 import type { ReactNode } from 'react';
 
+import { ownValue } from '../guards';
 import { DateRangeField, dateRangePairs } from './date-range-field';
 import { FieldNode } from './field-node';
 import { useKeyedCallbacks } from './keyed-callbacks';
@@ -45,7 +46,7 @@ export function ObjectFields({
    * object only; a property whose `enum` draws as a select shows its entry's
    * `choiceLabel` as the select placeholder. Absent for nested objects.
    */
-  fieldWording?: Readonly<Record<string, { choiceLabel?: string }>>;
+  fieldWording?: Readonly<Record<string, { choiceLabel?: string; invalid?: string }>>;
 }): ReactNode {
   const obj = isPlainObject(value) ? value : {};
   const changeFor = useKeyedCallbacks<string, unknown>(
@@ -66,7 +67,7 @@ export function ObjectFields({
       {properties.map(([name, propSchema]) => {
         if (skip !== undefined && name === skip) return null;
         if (skippedEnds.has(name)) return null;
-        // A field hidden by its `visibleWhen` predicate (scope B) is not rendered; the
+        // A field hidden by its `visibleWhen` predicate is not rendered; the
         // validator skips it in step, so a hidden field is neither shown nor required.
         if (!isFieldVisible(propSchema, obj)) return null;
         const pair = pairByStart.get(name);
@@ -75,13 +76,13 @@ export function ObjectFields({
             <DateRangeField
               key={name}
               pair={pair}
-              startValue={obj[pair.startName]}
-              endValue={obj[pair.endName]}
+              startValue={ownValue(obj, pair.startName)}
+              endValue={ownValue(obj, pair.endName)}
               startRequired={requiredKeys.has(pair.startName)}
               endRequired={requiredKeys.has(pair.endName)}
               markRequired={markRequired}
-              startError={errors?.[childPathOf(pair.startName)]}
-              endError={errors?.[childPathOf(pair.endName)]}
+              startError={ownValue(errors, childPathOf(pair.startName))}
+              endError={ownValue(errors, childPathOf(pair.endName))}
               onChangeStart={changeFor(pair.startName)}
               onChangeEnd={changeFor(pair.endName)}
             />
@@ -92,7 +93,7 @@ export function ObjectFields({
             key={name}
             schema={propSchema}
             root={root}
-            value={obj[name]}
+            value={ownValue(obj, name)}
             onChange={changeFor(name)}
             path={childPathOf(name)}
             label={name}

package/src/schema-form/record-field.tsx

@@ -43,7 +43,7 @@ interface Analysis {
 }
 
 function analyzeRows(rows: readonly Row[]): Analysis {
-  const value: Record<string, unknown> = {};
+  const entries: [string, unknown][] = [];
   const seen = new Set<string>();
   const blankRowIds = new Set<number>();
   const duplicateRowIds = new Set<number>();
@@ -57,8 +57,10 @@ function analyzeRows(rows: readonly Row[]): Analysis {
       continue;
     }
     seen.add(row.key);
-    value[row.key] = row.value;
+    entries.push([row.key, row.value]);
   }
+  // Built from entries so every typed key, `__proto__` included, lands as an own key.
+  const value = Object.fromEntries(entries);
   return { value, blankRowIds, duplicateRowIds };
 }
 

package/src/schema-form/string-field.tsx

@@ -142,7 +142,7 @@ export function StringField({
           // numeric/decimal keyboard); `undefined` for every other control, which
           // selects its kind through `type` instead.
           inputMode={control.inputMode}
-          // A native date control enforces its inclusive bounds (scope C); on a
+          // A native date control enforces its inclusive bounds; on a
           // non-date input the browser ignores these, and the validator enforces the
           // rest (unavailable days, range span) that the control cannot draw.
           min={date?.min}
@@ -421,7 +421,7 @@ const INPUT_MODE_CONTROLS: Record<
 };
 
 // The native control for a string field: the `inputMode` keyword OUTRANKS
-// `format` when present; otherwise the format mapping stands as before. The value
+// `format` when present; otherwise the format mapping picks the control. The value
 // is always the typed string — `numeric`/`decimal` set only the keyboard, never a
 // number coercion.
 function stringControl(

package/src/schema-form/union-field.tsx

@@ -65,12 +65,11 @@ function switchVariantValue(
   const { model } = classifySchema(target.schema, root);
   if (model.kind !== 'object') return seeded;
   const targetNames = new Set(model.properties.map(([name]) => name));
-  const merged: Record<string, unknown> = { ...seeded };
-  for (const [name, held] of Object.entries(current)) {
-    if (name === discriminator) continue;
-    if (targetNames.has(name)) merged[name] = held;
-  }
-  return merged;
+  const carried = Object.entries(current).filter(
+    ([name]) => name !== discriminator && targetNames.has(name),
+  );
+  // Built from entries so every property name, `__proto__` included, lands as an own key.
+  return Object.fromEntries([...Object.entries(seeded), ...carried]);
 }
 
 /** Title-case a property name: `kind` → "Kind", `content_type` → "Content Type". */

package/src/schema-form/union.ts

@@ -67,7 +67,7 @@ export function activeVariantIndex(
     const required = resolved.required ?? [];
     let score = 0;
     for (const key of required) {
-      if (key in value) score += 1;
+      if (Object.hasOwn(value, key)) score += 1;
     }
     if (score > bestScore) {
       bestScore = score;

package/src/schema-form/validate.ts

@@ -5,7 +5,7 @@
  * container constraint on a free-form `json` field. It never throws on a
  * malformed value — a malformed value IS the error it reports.
  */
-import { isRecord } from '../guards';
+import { isRecord, ownValue } from '../guards';
 import { classifySchema } from './classify';
 import type { DateConstraints, FieldModel } from './field-model';
 import { decodedByteSize, effectiveMaxBytes, overCapMessage } from './media';
@@ -22,16 +22,62 @@ export interface ValidateOptions {
    * absent both, the shared default applies.
    */
   readonly maxUploadBytes?: number;
+  /**
+   * Per-field words, keyed by the root object's exact property name. A field's
+   * `invalid` sentence replaces every shape error on that field and anything inside
+   * it (a format, pattern, length, bound, type or item error). A missing required
+   * value keeps its own required message, and a `pattern` that cannot compile keeps
+   * its own message, since that is a defect of the schema, not of the value. A field
+   * with no `invalid` sentence keeps the SDK's word for the failing shape.
+   */
+  readonly fieldWording?: Readonly<Record<string, { invalid?: string }>>;
 }
 
 /** The invariants every per-node validator shares while walking one value tree. */
 interface ValidateCtx {
   /** The document root, for `$ref` resolution during re-classification. */
   readonly root: JsonSchema;
-  /** The path-keyed error bag every validator writes into. */
+  /**
+   * The path-keyed error bag every validator writes into. It has no prototype, so a
+   * path that names a built-in object member (`toString`, `__proto__`) is an ordinary key.
+   */
   readonly errors: Record<string, string>;
   /** The host's default media byte cap (a field's own cap still overrides it). */
   readonly maxUploadBytes: number | undefined;
+  /**
+   * The root object's property the walk is inside, or `undefined` at the root itself
+   * and inside a root that is not an object or record.
+   */
+  readonly field: string | undefined;
+  /**
+   * The paths whose error is a shape error a field's `invalid` sentence may replace,
+   * each mapped to the root property it lies inside.
+   */
+  readonly shapeErrorFields: Map<string, string>;
+}
+
+/**
+ * Record a shape error at `path`: the value breaks a shape the schema declares. Inside
+ * a root property, that field's `invalid` sentence may replace it.
+ */
+function shapeError(ctx: ValidateCtx, path: string, message: string): void {
+  ctx.errors[path] = message;
+  if (ctx.field === undefined) ctx.shapeErrorFields.delete(path);
+  else ctx.shapeErrorFields.set(path, ctx.field);
+}
+
+/**
+ * Record an error at `path` that is not a shape the value breaks (a missing required
+ * value, a schema constraint that cannot run): a field's words never replace it.
+ */
+function keptError(ctx: ValidateCtx, path: string, message: string): void {
+  ctx.errors[path] = message;
+  ctx.shapeErrorFields.delete(path);
+}
+
+/** The context for the child `name` of the value at `path`: a root child is its own field. */
+function childCtx(ctx: ValidateCtx, path: string, name: string): ValidateCtx {
+  return path === '' ? { ...ctx, field: name } : ctx;
 }
 
 const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
@@ -78,9 +124,9 @@ function validateJson(
   ctx: ValidateCtx,
 ): void {
   if (model.jsonType === 'object' && !isRecord(value)) {
-    ctx.errors[path] = 'must be a JSON object';
+    shapeError(ctx, path, 'must be a JSON object');
   } else if (model.jsonType === 'array' && !Array.isArray(value)) {
-    ctx.errors[path] = 'must be a JSON array';
+    shapeError(ctx, path, 'must be a JSON array');
   }
 }
 
@@ -90,7 +136,7 @@ function validateConst(
   path: string,
   ctx: ValidateCtx,
 ): void {
-  if (value !== model.value) ctx.errors[path] = `must equal ${scalarLabel(model.value)}`;
+  if (value !== model.value) shapeError(ctx, path, `must equal ${scalarLabel(model.value)}`);
 }
 
 function validateEnum(
@@ -100,7 +146,7 @@ function validateEnum(
   ctx: ValidateCtx,
 ): void {
   const allowed = model.options.some((option) => option.value === value);
-  if (!allowed) ctx.errors[path] = 'must be one of the allowed values';
+  if (!allowed) shapeError(ctx, path, 'must be one of the allowed values');
 }
 
 function validateString(
@@ -110,7 +156,7 @@ function validateString(
   ctx: ValidateCtx,
 ): void {
   if (typeof value !== 'string') {
-    ctx.errors[path] = 'must be a string';
+    shapeError(ctx, path, 'must be a string');
     return;
   }
   // A media-annotated string carries a byte cap; enforce it on the value's
@@ -121,22 +167,22 @@ function validateString(
     const cap = effectiveMaxBytes(model.media.maxBytes, ctx.maxUploadBytes);
     const size = decodedByteSize(value);
     if (size > cap) {
-      ctx.errors[path] = overCapMessage('The value', size, cap);
+      shapeError(ctx, path, overCapMessage('The value', size, cap));
       return;
     }
   }
   if (value.length > 0 && model.format !== undefined) {
     const message = formatError(model.format, value);
     if (message !== undefined) {
-      ctx.errors[path] = message;
+      shapeError(ctx, path, message);
       return;
     }
   }
-  // Date bounds and unavailable days (scope C). Range span/ordering needs the sibling
+  // Date bounds and unavailable days. Range span/ordering needs the sibling
   // start field, so it is enforced at the object level (see validateDateRanges).
   if (model.date !== undefined && value.length > 0) {
     const message = dateConstraintError(model.date, value);
-    if (message !== undefined) ctx.errors[path] = message;
+    if (message !== undefined) shapeError(ctx, path, message);
   }
 }
 
@@ -159,14 +205,14 @@ function validateNumber(
   ctx: ValidateCtx,
 ): void {
   if (typeof value !== 'number' || Number.isNaN(value)) {
-    ctx.errors[path] = model.integer ? 'must be an integer' : 'must be a number';
+    shapeError(ctx, path, model.integer ? 'must be an integer' : 'must be a number');
     return;
   }
-  if (model.integer && !Number.isInteger(value)) ctx.errors[path] = 'must be an integer';
+  if (model.integer && !Number.isInteger(value)) shapeError(ctx, path, 'must be an integer');
 }
 
 function validateBoolean(value: unknown, path: string, ctx: ValidateCtx): void {
-  if (typeof value !== 'boolean') ctx.errors[path] = 'must be true or false';
+  if (typeof value !== 'boolean') shapeError(ctx, path, 'must be true or false');
 }
 
 function validateArray(
@@ -176,7 +222,7 @@ function validateArray(
   ctx: ValidateCtx,
 ): void {
   if (!Array.isArray(value)) {
-    ctx.errors[path] = 'must be an array';
+    shapeError(ctx, path, 'must be an array');
     return;
   }
   value.forEach((item, index) => {
@@ -191,40 +237,45 @@ function validateObject(
   ctx: ValidateCtx,
 ): void {
   if (!isRecord(value)) {
-    ctx.errors[path] = 'must be an object';
+    shapeError(ctx, path, 'must be an object');
     return;
   }
   const propMap = new Map(model.properties);
   for (const [name, propSchema] of model.properties) {
-    // A field hidden by its `visibleWhen` predicate (scope B) is not part of the answer:
+    // A field hidden by its `visibleWhen` predicate is not part of the answer:
     // it is not required and not validated, and a value left on it is dropped by the
     // server, not an error here. Evaluated on the current values, so a field that was
     // hidden by the predicate is skipped even if it still carries a stale value.
     if (!isFieldVisible(propSchema, value)) continue;
     const childPath = joinPath(path, name);
-    const childValue = value[name];
+    const childValue = ownValue(value, name);
     if (childValue === undefined) {
-      if (model.required.has(name)) ctx.errors[childPath] = `"${name}" is required`;
+      if (model.required.has(name)) markRequired(childPath, name, ctx);
       continue;
     }
-    walk(propSchema, childValue, childPath, ctx);
+    walk(propSchema, childValue, childPath, childCtx(ctx, path, name));
   }
   // Required keys naming a property that somehow isn't declared still count.
   for (const name of model.required) {
-    if (!propMap.has(name) && value[name] === undefined) {
-      ctx.errors[joinPath(path, name)] = `"${name}" is required`;
+    if (!propMap.has(name) && ownValue(value, name) === undefined) {
+      markRequired(joinPath(path, name), name, ctx);
     }
   }
   validateDateRanges(model, value, path, ctx);
 }
 
+/** Record a missing required value at `path`, the one error a field's words never replace. */
+function markRequired(path: string, name: string, ctx: ValidateCtx): void {
+  keptError(ctx, path, `"${name}" is required`);
+}
+
 /** Days from `start` to `end` inclusive (both `YYYY-MM-DD`); 1 when they are equal. */
 function inclusiveDayCount(start: string, end: string): number {
   return Math.round((Date.parse(end) - Date.parse(start)) / 86_400_000) + 1;
 }
 
 /**
- * Enforce a date RANGE declared on an END field (scope C): the end is on or after its
+ * Enforce a date RANGE declared on an END field: the end is on or after its
  * named `rangeStart` field, and the inclusive day span is within `minDays`/`maxDays`.
  * Read from the two plain date values — nothing recombined. A missing or not-yet-valid
  * endpoint is left to that field's own validation; a hidden end field is skipped.
@@ -239,14 +290,14 @@ function validateDateRanges(
     if (!isFieldVisible(propSchema, value)) continue;
     const resolved = resolveRef(propSchema, ctx.root);
     if (typeof resolved.rangeStart !== 'string') continue;
-    const endValue = value[name];
-    const startValue = value[resolved.rangeStart];
+    const endValue = ownValue(value, name);
+    const startValue = ownValue(value, resolved.rangeStart);
     if (typeof endValue !== 'string' || typeof startValue !== 'string') continue;
     if (!DATE_RE.test(endValue) || !DATE_RE.test(startValue)) continue;
     const childPath = joinPath(path, name);
     if (ctx.errors[childPath] !== undefined) continue;
     const message = dateRangeMessage(resolved, startValue, endValue);
-    if (message !== undefined) ctx.errors[childPath] = message;
+    if (message !== undefined) shapeError(childCtx(ctx, path, name), childPath, message);
   }
 }
 
@@ -273,20 +324,20 @@ function validateMultiselect(
   ctx: ValidateCtx,
 ): void {
   if (!Array.isArray(value)) {
-    ctx.errors[path] = 'must be an array';
+    shapeError(ctx, path, 'must be an array');
     return;
   }
   const allowed = new Set(model.options.map((option) => option.value));
   for (const item of value) {
     if (!allowed.has(item)) {
-      ctx.errors[path] = 'must be one of the allowed values';
+      shapeError(ctx, path, 'must be one of the allowed values');
       return;
     }
   }
 }
 
 /**
- * The JSON-Schema value/length/items bounds the client mirrors from the server (bug 4):
+ * The JSON-Schema value/length/items bounds the client mirrors from the server:
  * `minLength`/`maxLength`/`pattern` on a string, `minimum`/`maximum` on a number,
  * `minItems`/`maxItems` on an array. Applied only when the kind check found no type
  * error. A `pattern` that cannot compile surfaces as a loud field error, never a silent
@@ -306,11 +357,11 @@ function applyStringBounds(
 ): void {
   const length = Array.from(value).length;
   if (typeof schema.minLength === 'number' && length < schema.minLength) {
-    ctx.errors[path] = `must be at least ${String(schema.minLength)} character(s)`;
+    shapeError(ctx, path, `must be at least ${String(schema.minLength)} character(s)`);
     return;
   }
   if (typeof schema.maxLength === 'number' && length > schema.maxLength) {
-    ctx.errors[path] = `must be at most ${String(schema.maxLength)} character(s)`;
+    shapeError(ctx, path, `must be at most ${String(schema.maxLength)} character(s)`);
     return;
   }
   if (typeof schema.pattern !== 'string' || schema.pattern === '') return;
@@ -318,10 +369,10 @@ function applyStringBounds(
   try {
     pattern = new RegExp(schema.pattern);
   } catch {
-    ctx.errors[path] = 'has an invalid pattern constraint';
+    keptError(ctx, path, 'has an invalid pattern constraint');
     return;
   }
-  if (!pattern.test(value)) ctx.errors[path] = 'must match the required pattern';
+  if (!pattern.test(value)) shapeError(ctx, path, 'must match the required pattern');
 }
 
 function applyNumberBounds(
@@ -331,11 +382,11 @@ function applyNumberBounds(
   ctx: ValidateCtx,
 ): void {
   if (typeof schema.minimum === 'number' && value < schema.minimum) {
-    ctx.errors[path] = `must be at least ${String(schema.minimum)}`;
+    shapeError(ctx, path, `must be at least ${String(schema.minimum)}`);
     return;
   }
   if (typeof schema.maximum === 'number' && value > schema.maximum) {
-    ctx.errors[path] = `must be at most ${String(schema.maximum)}`;
+    shapeError(ctx, path, `must be at most ${String(schema.maximum)}`);
   }
 }
 
@@ -346,11 +397,11 @@ function applyArrayBounds(
   ctx: ValidateCtx,
 ): void {
   if (typeof schema.minItems === 'number' && value.length < schema.minItems) {
-    ctx.errors[path] = `must have at least ${String(schema.minItems)} item(s)`;
+    shapeError(ctx, path, `must have at least ${String(schema.minItems)} item(s)`);
     return;
   }
   if (typeof schema.maxItems === 'number' && value.length > schema.maxItems) {
-    ctx.errors[path] = `must have at most ${String(schema.maxItems)} item(s)`;
+    shapeError(ctx, path, `must have at most ${String(schema.maxItems)} item(s)`);
   }
 }
 
@@ -361,11 +412,11 @@ function validateRecord(
   ctx: ValidateCtx,
 ): void {
   if (!isRecord(value)) {
-    ctx.errors[path] = 'must be an object';
+    shapeError(ctx, path, 'must be an object');
     return;
   }
   for (const [key, entryValue] of Object.entries(value)) {
-    walk(model.values, entryValue, joinPath(path, key), ctx);
+    walk(model.values, entryValue, joinPath(path, key), childCtx(ctx, path, key));
   }
 }
 
@@ -378,7 +429,7 @@ function validateUnion(
   const index = activeVariantIndex(value, model.variants, model.discriminator, ctx.root);
   const variant = index === -1 ? undefined : model.variants[index];
   if (variant === undefined) {
-    ctx.errors[path] = 'does not match any allowed variant';
+    shapeError(ctx, path, 'does not match any allowed variant');
     return;
   }
   walk(variant.schema, value, path, ctx);
@@ -388,12 +439,12 @@ function walk(schema: JsonSchema, value: unknown, path: string, ctx: ValidateCtx
   const classified = classifySchema(schema, ctx.root);
 
   if (value === null) {
-    if (!classified.nullable) ctx.errors[path] = 'must not be null';
+    if (!classified.nullable) shapeError(ctx, path, 'must not be null');
     return;
   }
 
   dispatchKind(classified.model, value, path, ctx);
-  // The value/length/items bounds (bug 4) mirror the server and apply only when the kind
+  // The value/length/items bounds mirror the server and apply only when the kind
   // check found no type error for this field — a bound on a wrong-typed value is noise.
   if (ctx.errors[path] === undefined) applyBounds(classified.schema, value, path, ctx);
 }
@@ -436,18 +487,48 @@ function dispatchKind(model: FieldModel, value: unknown, path: string, ctx: Vali
   }
 }
 
+/**
+ * Replace each shape error inside a root property whose words carry an `invalid`
+ * sentence with that sentence; every other error keeps its own message.
+ */
+function applyFieldWording(
+  fieldWording: Readonly<Record<string, { invalid?: string }>>,
+  errors: Record<string, string>,
+  shapeErrorFields: ReadonlyMap<string, string>,
+): void {
+  for (const [path, field] of shapeErrorFields) {
+    if (!Object.hasOwn(fieldWording, field)) continue;
+    const invalid = fieldWording[field]?.invalid;
+    if (invalid !== undefined) errors[path] = invalid;
+  }
+}
+
 /**
  * Validate `value` against `schema`, returning a per-path error bag (empty =
  * valid). The caller runs this before submit and feeds the result back to
  * `SchemaForm` for display. `options.maxUploadBytes` mirrors the renderer's
- * `maxUploadBytes` prop so a media field's byte cap is enforced identically here.
+ * `maxUploadBytes` prop so a media field's byte cap is enforced identically here;
+ * `options.fieldWording` puts a field's own `invalid` sentence in place of the
+ * SDK's word for any shape error on that field.
  */
 export function validateAgainstSchema(
   schema: JsonSchema,
   value: unknown,
   options?: ValidateOptions,
 ): SchemaFormErrors {
-  const errors: Record<string, string> = {};
-  walk(schema, value, '', { root: schema, errors, maxUploadBytes: options?.maxUploadBytes });
-  return errors;
+  const errors = Object.create(null) as Record<string, string>;
+  const shapeErrorFields = new Map<string, string>();
+  walk(schema, value, '', {
+    root: schema,
+    errors,
+    maxUploadBytes: options?.maxUploadBytes,
+    field: undefined,
+    shapeErrorFields,
+  });
+  if (options?.fieldWording !== undefined) {
+    applyFieldWording(options.fieldWording, errors, shapeErrorFields);
+  }
+  // Hand back an ordinary object; its entries are defined as own keys, so a path such as
+  // `__proto__` stays an entry of the result.
+  return Object.fromEntries(Object.entries(errors));
 }