@jxsuite/studio 6.1.1 → 8.0.0

package/src/ui/schema-form.ts

@@ -3,11 +3,11 @@
  * Schema-form — the reusable JSON-Schema → form engine, and the FLOW half of it.
  *
  * Maps schema property types to controls (enum → select, boolean → checkbox, number/integer →
- * number field, `json-schema` format → JSON editor, array-of-objects → a row per item, other
- * array/object → JSON text, default → text field); hosts commit edits through a single
- * `onChange(patch)` callback; dynamic enum choices resolve through a {@link SchemaFormContext}.
- * Custom controls register by name via {@link registerFormControl} and are consulted first for `ui`
- * overrides.
+ * number field, `json-schema` format → JSON editor, array-of-objects → a row per item, an array of
+ * single values (text, numbers, pictures, entries) → a row per item too, other array/object → JSON
+ * text, default → text field); hosts commit edits through a single `onChange(patch)` callback;
+ * dynamic enum choices resolve through a {@link SchemaFormContext}. Custom controls register by
+ * name via {@link registerFormControl} and are consulted first for `ui` overrides.
  *
  * **This module decides; `surfaces/schema-form.json` draws.** Every question with an answer — which
  * control a property gets, what its choices are, which rungs of the value ladder the position
@@ -39,7 +39,16 @@
  * mount, updated rather than rebuilt on every repaint (specs/extensions.md §9.1).
  */
 
-import { isRef } from "@jxsuite/schema/guards";
+import {
+  isBoolean,
+  isJsonObject,
+  isNonNullObject,
+  isNumber,
+  isRef,
+  isString,
+} from "@jxsuite/schema/guards";
+import type { ReadonlyJsonObject } from "@jxsuite/schema/project-schemas";
+import type { JsonObject, JsonValue, JxDocumentValue } from "@jxsuite/schema/types";
 import { createSchemaFormSurface } from "../surfaces/schema-form";
 import { openMenu } from "../surfaces/menu";
 import type { MenuHandle } from "../surfaces/menu";
@@ -58,15 +67,13 @@ import {
   slotCaps,
 } from "./value-source";
 import type { SlotMode } from "./value-source";
-import type { SignalOption } from "./dynamic-slot";
-import type { JsonValue } from "../types";
 import type {
   SchemaFormCellView,
   SchemaFormFieldView,
-  SchemaFormOption,
   SchemaFormRowView,
   SchemaFormSurface,
 } from "../surfaces/schema-form";
+import type { SurfaceOption } from "./surface";
 
 /** A (possibly nested) JSON Schema node, covering both object and property level keys. */
 export interface JsonSchema {
@@ -91,10 +98,19 @@ export interface JsonSchema {
   $ref?: string;
 }
 
+/**
+ * What a form commits: the properties that changed, each with its new value. `undefined` removes
+ * the property — a cleared field is absent from the record, not stored as an empty string.
+ */
+export type SchemaFormPatch = Record<string, JsonValue | undefined>;
+
 /** Host-provided context threaded to every control. */
 export interface SchemaFormContext {
-  /** Resolve a `#/$context/…` pointer (or legacy sentinel) against the host's project config. */
-  resolvePointer: (pointer: string, scope?: Record<string, unknown>) => unknown;
+  /**
+   * Resolve a `#/$context/…` pointer (or legacy sentinel) against the host's project config. A
+   * config section is document data, so the answer is whatever the config holds there.
+   */
+  resolvePointer: (pointer: string, scope?: JsonObject) => JxDocumentValue | JsonValue | undefined;
   /** Route params available for `$ref` bindings (e.g. from the document path). */
   params?: string[] | undefined;
   /**
@@ -117,8 +133,8 @@ export interface SchemaFormContext {
 export interface SchemaFormControlArgs {
   key: string;
   schema: JsonSchema;
-  value: unknown;
-  onChange: (next: unknown) => void;
+  value: JsonValue | undefined;
+  onChange: (next: JsonValue | undefined) => void;
   ctx: SchemaFormContext;
   /**
    * Ask the HOST to draw the form again, where it offered a way to.
@@ -153,14 +169,15 @@ export interface SchemaFormControlHandle {
 
 /** Options for {@link mountSchemaForm}. */
 export interface RenderFormOptions {
-  onChange: (patch: Record<string, unknown>) => void;
+  onChange: (patch: SchemaFormPatch) => void;
   context?: SchemaFormContext | undefined;
   /**
    * Per-field overrides from `$studio.settings.entry.ui`: a registered control name, and/or an
    * `enum` source (choice list or `{ "$ref": "#/$context/<pointer>" }`) layered over the field
-   * schema — fragments stay valid JSON Schema while descriptors add dynamic choices.
+   * schema — fragments stay valid JSON Schema while descriptors add dynamic choices. `label` is the
+   * words the row is titled with in place of the property's key.
    */
-  ui?: Record<string, { control?: string; enum?: unknown }> | undefined;
+  ui?: Record<string, { control?: string; enum?: unknown; label?: string }> | undefined;
   rerender?: (() => void) | undefined;
   /**
    * Externally-produced diagnostics, keyed by property name — §16.1's inline tier, sourced.
@@ -217,7 +234,9 @@ const CONTENT_REF = /^#\/content\/([^/]+)$/;
  * reading of `$ref` is how the picker ends up existing three times with three behaviours.
  */
 export function referenceTarget(schema: { $ref?: string } | undefined): string | null {
-  const match = typeof schema?.$ref === "string" ? CONTENT_REF.exec(schema.$ref) : null;
+  // The schema is project JSON, so the declared `string` is checked rather than trusted.
+  const ref = schema?.$ref;
+  const match = isString(ref) ? CONTENT_REF.exec(ref) : null;
   return match ? match[1]! : null;
 }
 
@@ -240,26 +259,30 @@ export const NULL_FORM_CONTEXT: SchemaFormContext = {
  * and sentinel strings resolve through the context's pointer resolver, applying object →
  * `Object.keys` and string[] → itself.
  *
- * @param {unknown} enumDef
+ * @param {JsonValue | undefined} enumDef
  * @param {SchemaFormContext | undefined} ctx
- * @param {Record<string, unknown>} [scope] - Scope for `{@param}` substitution (the form value)
+ * @param {JsonObject} [scope] - Scope for `{@param}` substitution (the form value)
  * @returns {string[] | undefined}
  */
 export function resolveFormEnum(
-  enumDef: unknown,
+  enumDef: JsonValue | undefined,
   ctx?: SchemaFormContext,
-  scope?: Record<string, unknown>,
+  scope?: JsonObject,
 ): string[] | undefined {
   if (Array.isArray(enumDef)) {
+    /* SAFETY: a form `enum` is a list of string choices — every select this engine draws is fed by
+       a settings fragment or collection schema that declares `type: "string"` beside its enum, and
+       each choice is only ever interpolated as text (an option label and value), which is what a
+       stray number would be read as too. */
     return enumDef as string[];
   }
   let pointer: string | undefined;
-  if (enumDef && typeof enumDef === "object") {
-    const ref = (enumDef as Record<string, unknown>).$ref;
-    if (typeof ref === "string") {
+  if (isJsonObject(enumDef)) {
+    const ref = enumDef.$ref;
+    if (isString(ref)) {
       pointer = ref;
     }
-  } else if (typeof enumDef === "string") {
+  } else if (isString(enumDef)) {
     // Legacy sentinel strings (e.g. "$contentTypes") resolve through the host's pointer resolver
     pointer = enumDef;
   }
@@ -270,7 +293,7 @@ export function resolveFormEnum(
   if (Array.isArray(resolved)) {
     return resolved.map(String);
   }
-  if (resolved && typeof resolved === "object") {
+  if (isJsonObject(resolved)) {
     return Object.keys(resolved);
   }
   return undefined;
@@ -296,7 +319,7 @@ function isBindableField(ps: JsonSchema): boolean {
 }
 
 /** Every pointer this form's host says a value may come from. */
-function refSourcesFor(ctx: SchemaFormContext): SignalOption[] {
+function refSourcesFor(ctx: SchemaFormContext): SurfaceOption[] {
   return [
     ...(ctx.signals ?? []).map((name) => ({ label: name, value: `#/state/${name}` })),
     ...(ctx.params ?? []).map((name) => ({ label: `$params/${name}`, value: `#/$params/${name}` })),
@@ -307,11 +330,11 @@ function refSourcesFor(ctx: SchemaFormContext): SignalOption[] {
 const NONE = "__none__";
 
 /** A value as a control reads it: a string, and never `"[object Object]"`. */
-function asText(value: unknown): string {
+function asText(value: JsonValue | undefined): string {
   if (value === undefined || value === null) {
     return "";
   }
-  return typeof value === "object" ? JSON.stringify(value, null, 2) : String(value);
+  return isNonNullObject(value) ? JSON.stringify(value, null, 2) : String(value);
 }
 
 // ─── Field validation (§16.1, inline tier) ───────────────────────────────────
@@ -328,13 +351,13 @@ function asText(value: unknown): string {
  * cannot see, so type-checking the reference itself would refuse every correct binding.
  *
  * @param {JsonSchema} schema
- * @param {unknown} value
+ * @param {JsonValue | undefined} value
  * @param {boolean} isRequired
  * @returns {string}
  */
 export function validateFieldValue(
   schema: JsonSchema,
-  value: unknown,
+  value: JsonValue | undefined,
   isRequired: boolean,
 ): string {
   if (isRef(value)) {
@@ -348,7 +371,7 @@ export function validateFieldValue(
     return `Choose one of: ${schema.enum.map(String).join(", ")}.`;
   }
   if (schema.type === "number" || schema.type === "integer") {
-    const n = typeof value === "number" ? value : Number(value);
+    const n = isNumber(value) ? value : Number(value);
     if (!Number.isFinite(n)) {
       return "Enter a number.";
     }
@@ -363,13 +386,14 @@ export function validateFieldValue(
     }
     return "";
   }
-  if (schema.type === "boolean" && typeof value !== "boolean") {
+  if (schema.type === "boolean" && !isBoolean(value)) {
     return "Must be true or false.";
   }
   if (schema.type === "array" && !Array.isArray(value)) {
     return "Must be a list.";
   }
-  if (schema.type === "object" && (typeof value !== "object" || Array.isArray(value))) {
+  // `null` is "empty" and answered above, so only a primitive or an array can fail here.
+  if (schema.type === "object" && !isJsonObject(value)) {
     return "Must be an object.";
   }
   return "";
@@ -392,17 +416,29 @@ interface FieldPlan {
   /** Item-property schemas, for an array-of-objects field. */
   itemProps?: Record<string, JsonSchema> | undefined;
   /** The rows currently held, so a cell edit can rebuild the array. */
-  rows?: Record<string, unknown>[] | undefined;
+  rows?: JsonObject[] | undefined;
+  /**
+   * The field is an array of single values (`string[]`, a gallery of pictures), drawn as rows of
+   * one cell each: every row is `{ [SCALAR_CELL]: item }` here, and a commit writes the bare items
+   * back. One row editor for both shapes, rather than a list control beside the row control.
+   */
+  scalarItems?: boolean | undefined;
   /** The ladder, when this position offers one. */
-  ladder?: { fieldKey: string; mode: SlotMode; offered: SlotMode[]; sources: SignalOption[] };
+  ladder?: { fieldKey: string; mode: SlotMode; offered: SlotMode[]; sources: SurfaceOption[] };
   /** A registered control owns the whole field; args are rebuilt for it on every repaint. */
   control?: SchemaFormMountedControl | undefined;
+  /**
+   * The member of the property's OBJECT this row edits, when the row is one part of an object
+   * field: an image object's `alt` is a text row of its own, and its commit writes the whole object
+   * back with that one member changed.
+   */
+  member?: string | undefined;
   /**
    * Registered controls owning one cell, keyed by the cell's host id.
    *
    * The same kind of entry a field's own control is, and reached by the same dispatch: a cell host
-   * is a host like any other. The one control a cell is ever given is `reference` (see
-   * {@link deriveCell}).
+   * is a host like any other. A cell is given `reference` for an entry of another collection and
+   * `media` for a picture (see {@link deriveCell}).
    */
   cellControls?: Map<
     string,
@@ -427,11 +463,7 @@ const TEXT_COMMIT_MS = 400;
 
 interface FormController {
   readonly host: HTMLElement;
-  readonly update: (
-    schema: JsonSchema,
-    value: Record<string, unknown>,
-    opts: RenderFormOptions,
-  ) => void;
+  readonly update: (schema: JsonSchema, value: JsonObject, opts: RenderFormOptions) => void;
   readonly dispose: () => void;
 }
 
@@ -452,14 +484,14 @@ export function resetSchemaForms(): void {
  * @param {string} formKey Stable identity for this form — the same key updates the standing mount
  *   instead of building a second one, which is what keeps the caret in a field across a repaint.
  * @param {JsonSchema} schema
- * @param {Record<string, unknown>} value The record being edited
+ * @param {JsonObject} value The record being edited
  * @param {RenderFormOptions} opts
  * @returns {HTMLElement} The form's own host, for a lit caller to place in its tree
  */
 export function mountSchemaForm(
   formKey: string,
   schema: JsonSchema,
-  value: Record<string, unknown>,
+  value: JsonObject,
   opts: RenderFormOptions,
 ): HTMLElement {
   sweep(formKey);
@@ -490,7 +522,7 @@ function sweep(exceptKey: string): void {
 
 function createController(): FormController {
   let schema: JsonSchema = {};
-  let value: Record<string, unknown> = {};
+  let value: JsonObject = {};
   let opts: RenderFormOptions = { onChange: () => {} };
   let ctx: SchemaFormContext = NULL_FORM_CONTEXT;
   const plans = new Map<string, FieldPlan>();
@@ -515,7 +547,7 @@ function createController(): FormController {
     run();
   };
 
-  const patch = (prop: string, next: unknown): void => {
+  const patch = (prop: string, next: JsonValue | undefined): void => {
     opts.onChange({ [prop]: next });
   };
 
@@ -546,7 +578,8 @@ function createController(): FormController {
       }
       case "json": {
         try {
-          patch(plan.prop, JSON.parse(raw) as unknown);
+          // SAFETY: `JSON.parse` with no reviver yields only JSON values, which is all a JsonValue is.
+          patch(plan.prop, JSON.parse(raw) as JsonValue);
         } catch {
           /* A half-typed object is not a refusal: the last parsable text is what the document
              keeps, and the field goes on showing what is actually in it. */
@@ -554,14 +587,40 @@ function createController(): FormController {
         return;
       }
       default: {
+        if (plan.member !== undefined) {
+          // One member of an object: the object goes back whole, with that member set or removed.
+          const held = value[plan.prop];
+          const base: JsonObject = isJsonObject(held) ? { ...held } : {};
+          if (raw) {
+            base[plan.member] = raw;
+          } else {
+            delete base[plan.member];
+          }
+          patch(plan.prop, Object.keys(base).length > 0 ? base : undefined);
+          return;
+        }
         patch(plan.prop, raw || undefined);
       }
     }
   };
 
+  /**
+   * Write a row field's rows back as the array the document holds: the rows themselves for an array
+   * of objects, each row's one value for an array of single values. A row whose value was cleared
+   * stays as an empty string, so clearing the text of an item does not delete its row under the
+   * caret; Remove is how an item goes.
+   */
+  const patchRows = (plan: FieldPlan, rows: JsonObject[]): void => {
+    let next: JsonValue | undefined;
+    if (rows.length > 0) {
+      next = plan.scalarItems ? rows.map((row) => row[SCALAR_CELL] ?? "") : rows;
+    }
+    patch(plan.prop, next);
+  };
+
   /** The field's items, each shallow-copied so a cell edit never writes through to the document. */
-  const cellRows = (plan: FieldPlan): Record<string, unknown>[] => {
-    const copies: Record<string, unknown>[] = [];
+  const cellRows = (plan: FieldPlan): JsonObject[] => {
+    const copies: JsonObject[] = [];
     for (const item of plan.rows ?? []) {
       copies.push({ ...item });
     }
@@ -574,13 +633,15 @@ function createController(): FormController {
       if (!plan?.itemProps) {
         return;
       }
-      const seed: Record<string, unknown> = {};
+      const seed: JsonObject = {};
       for (const [k, v] of Object.entries(plan.itemProps)) {
         if (v.default !== undefined) {
-          seed[k] = v.default;
+          /* SAFETY: an item schema is read from a JSON schema document, so the `default` it
+             declares is a JSON value. */
+          seed[k] = v.default as JsonValue;
         }
       }
-      patch(field, [...cellRows(plan), seed]);
+      patchRows(plan, [...cellRows(plan), seed]);
       opts.rerender?.();
     },
     commit: (key: string, raw: string) => {
@@ -622,13 +683,15 @@ function createController(): FormController {
         return;
       }
       const idx = Number(row);
-      const kept = cellRows(plan).filter((_, i) => i !== idx);
-      patch(field, kept.length > 0 ? kept : undefined);
+      patchRows(
+        plan,
+        cellRows(plan).filter((_, i) => i !== idx),
+      );
       opts.rerender?.();
     },
   };
 
-  function writeCell(field: string, row: string, cell: string, next: unknown): void {
+  function writeCell(field: string, row: string, cell: string, next: JsonValue | undefined): void {
     const plan = plans.get(field);
     if (!plan?.itemProps) {
       return;
@@ -640,20 +703,23 @@ function createController(): FormController {
       return;
     }
     const cellSchema = plan.itemProps[cell];
+    /* SAFETY: the one non-JSON member this row can gain is an `undefined` for a cleared cell, and
+       every host's `onChange` persists the patch as JSON (the entry, the def and the project config
+       are all serialized), where an undefined member is simply omitted. */
     rows[idx] = {
       ...target,
       [cell]: coerceCell(cellSchema, next, plan.refCells?.has(`${field}/${row}/${cell}`) ?? false),
-    };
-    patch(field, rows);
+    } as JsonObject;
+    patchRows(plan, rows);
   }
 
   /** A cell's committed string, as the item property's declared type. */
   function coerceCell(
     cellSchema: JsonSchema | undefined,
-    next: unknown,
+    next: JsonValue | undefined,
     isPointer: boolean,
-  ): unknown {
-    if (typeof next === "boolean") {
+  ): JsonValue | undefined {
+    if (isBoolean(next)) {
       return next;
     }
     const raw = String(next);
@@ -687,7 +753,7 @@ function createController(): FormController {
       opener: anchor,
       region: "value-source",
       rows: offered.map((rung) => ({
-        checked: (rung === mode ? "true" : "false") as "true" | "false",
+        checked: rung === mode ? ("true" as const) : ("false" as const),
         destructive: false,
         disabled: false,
         dividerAbove: false,
@@ -695,12 +761,14 @@ function createController(): FormController {
         title: VALUE_SOURCE_LABELS[rung],
       })),
       run: (id) => {
-        const next = id as SlotMode;
-        if (next === mode) {
+        // The menu's rows are `offered`, so an id is always one of its rungs.
+        const next = offered.find((rung) => rung === id);
+        if (next === undefined || next === mode) {
           return;
         }
         /* Leaving From data… seeds an empty Fixed value stash with the property's declared default,
            so unbind-restores-default survives a detour through Mixed text. */
+        // SAFETY: the field schema is read from JSON, so the `default` it declares is a JSON value.
         const literalDefault = plan.schema.default as JsonValue | undefined;
         if (
           mode === "ref" &&
@@ -715,7 +783,7 @@ function createController(): FormController {
             fieldKey,
             mode,
             next,
-            cloneValue(value[plan.prop] as JsonValue | undefined),
+            cloneValue(value[plan.prop]),
             slotModeSeed(next, { extraSignals: sources, literalDefault, stateDefs: [] }),
           ),
         );
@@ -853,32 +921,107 @@ function createController(): FormController {
 /** Every row the document draws, and the plan that reads each one's gestures back. */
 function deriveFields(
   schema: JsonSchema,
-  value: Record<string, unknown>,
+  value: JsonObject,
   opts: RenderFormOptions,
   ctx: SchemaFormContext,
   plans: Map<string, FieldPlan>,
 ): SchemaFormFieldView[] {
   const required = new Set(schema.required);
   const sources = refSourcesFor(ctx);
-  return Object.entries(schema.properties ?? {}).map(([prop, ps]) =>
-    deriveField(prop, ps, {
-      ctx,
-      opts,
-      plans,
-      required: required.has(prop),
-      sources,
-      value,
-    }),
+  return Object.entries(schema.properties ?? {}).flatMap(([prop, ps]) => {
+    const args = { ctx, opts, plans, required: required.has(prop), sources, value };
+    const field = deriveField(prop, ps, args);
+    // An image object's alt text is a row of its own, under the picture it describes.
+    return field.kind === "control" && isImageObjectSchema(ps) && ps.properties?.["alt"]
+      ? [field, imageAltRow(prop, args)]
+      : [field];
+  });
+}
+
+/** The members an image object may have beside its `src`: what an `<img>` says about itself. */
+const IMAGE_OBJECT_MEMBERS: ReadonlySet<string> = new Set([
+  "src",
+  "alt",
+  "width",
+  "height",
+  "title",
+]);
+
+/**
+ * Whether a property is an image OBJECT: `{ src, alt?, width?, height?, title? }`, the shape a site
+ * imported from a CMS keeps a picture in (`featuredImage: { src, width, height, alt }`). Such a
+ * field is a picture to pick, not a record to type JSON into.
+ */
+export function isImageObjectSchema(ps: JsonSchema): boolean {
+  const properties = ps.properties ?? {};
+  return (
+    ps.type === "object" &&
+    properties["src"]?.type === "string" &&
+    Object.keys(properties).every((name) => IMAGE_OBJECT_MEMBERS.has(name))
   );
 }
 
+/** The media control over an image object's `src`, writing the object back around it. */
+function imageObjectControl(media: SchemaFormMountedControl): SchemaFormMountedControl {
+  /** The args the media control sees: the `src`, and a commit that rebuilds the object. */
+  const srcArgs = (args: SchemaFormControlArgs): SchemaFormControlArgs => {
+    const held = isJsonObject(args.value) ? args.value : {};
+    const { src } = held;
+    return {
+      ...args,
+      onChange: (next) => {
+        if (next === src) {
+          return;
+        }
+        /* A different picture: its alt text and title still describe what the author meant, but the
+           old picture's width and height would be a lie about the new one, so they go. A cleared
+           field clears the whole object: an image with no picture is no image. */
+        const { height: _height, width: _width, ...kept } = held;
+        let rebuilt: JsonValue | undefined;
+        if (next !== undefined && next !== "") {
+          rebuilt = { ...kept, src: next };
+        }
+        args.onChange(rebuilt);
+      },
+      value: isString(src) ? src : undefined,
+    };
+  };
+  return {
+    mount(host, args) {
+      const handle = media.mount(host, srcArgs(args));
+      return {
+        dispose: () => handle.dispose(),
+        update: (next) => handle.update(srcArgs(next)),
+      };
+    },
+  };
+}
+
+/** The text row an image object's `alt` is edited in. */
+function imageAltRow(prop: string, args: DeriveArgs): SchemaFormFieldView {
+  const key = `${prop}/alt`;
+  const held = args.value[prop];
+  const alt = isJsonObject(held) ? held["alt"] : undefined;
+  const row = deriveField(key, { type: "string" }, { ...args, required: false });
+  const plan = args.plans.get(key);
+  if (plan) {
+    plan.prop = prop;
+    plan.member = "alt";
+  }
+  return {
+    ...row,
+    label: `${args.opts.ui?.[prop]?.label ?? prop} alt text`,
+    value: isString(alt) ? alt : "",
+  };
+}
+
 interface DeriveArgs {
   ctx: SchemaFormContext;
   opts: RenderFormOptions;
   plans: Map<string, FieldPlan>;
   required: boolean;
-  sources: SignalOption[];
-  value: Record<string, unknown>;
+  sources: SurfaceOption[];
+  value: JsonObject;
 }
 
 function deriveField(prop: string, ps: JsonSchema, args: DeriveArgs): SchemaFormFieldView {
@@ -914,11 +1057,12 @@ function deriveField(prop: string, ps: JsonSchema, args: DeriveArgs): SchemaForm
     invalid: error !== "",
     key: prop,
     kind: "text",
-    label: prop,
+    label: opts.ui?.[prop]?.label ?? prop,
     max: "",
     min: "",
     mono: false,
     multiline: false,
+    inputType: "text",
     options: [],
     placeholder: "",
     prop: ps.name || prop,
@@ -938,7 +1082,10 @@ function deriveField(prop: string, ps: JsonSchema, args: DeriveArgs): SchemaForm
     const mode = effectiveSlotMode(fieldKey, current);
     /* A From data… rung with nothing to point at is a dead end — but this engine only ladders a
        field once the host has named a source, so the rung always has something in it. */
-    const offered = slotCaps({ schema: configFieldSchema(ps) });
+    /* SAFETY: `JsonSchema` names only the keywords this engine acts on; the node itself is a schema
+       read from JSON (a settings fragment, a collection or plugin schema), so it and every keyword
+       it carries beyond the named ones are JSON, which is all the ladder's walk reads it as. */
+    const offered = slotCaps({ schema: configFieldSchema(ps as ReadonlyJsonObject) });
     plan.ladder = { fieldKey, mode, offered, sources };
     row.hasChip = true;
     row.sourceLabel = VALUE_SOURCE_LABELS[mode];
@@ -1002,7 +1149,33 @@ function deriveField(prop: string, ps: JsonSchema, args: DeriveArgs): SchemaForm
     }
   }
 
-  const enumValues = resolveFormEnum(opts.ui?.[prop]?.enum ?? ps.enum, ctx, value);
+  /* An image field (`format: "image"`) is the registered `media` control: the same field, Upload and
+     Browse the page's Icon and OG Image rows draw (`surfaces/media-field.json`), so a collection
+     entry's picture is picked from the project's media rather than typed as a path. Unregistered
+     (a bare-Bun import of this engine), it falls through to the text control below. */
+  if (ps.format === "image") {
+    const media = controlRegistry.get("media");
+    if (media) {
+      plan.commit = "none";
+      plan.control = media;
+      row.kind = "control";
+      return row;
+    }
+  }
+  /* An image OBJECT (`{ src, alt, width, height }`) is the same media field over its `src`; its
+     `alt` is a text row of its own (`deriveFields`). Unregistered, it falls through to JSON. */
+  const imageMedia = isImageObjectSchema(ps) ? controlRegistry.get("media") : undefined;
+  if (imageMedia) {
+    plan.commit = "none";
+    plan.control = imageObjectControl(imageMedia);
+    row.kind = "control";
+    return row;
+  }
+
+  /* SAFETY: both sources are read from JSON — the descriptor's `$studio.settings.entry.ui` and the
+     field schema — so whichever `enum` is present is a JSON value. */
+  const enumSource = (opts.ui?.[prop]?.enum ?? ps.enum) as JsonValue | undefined;
+  const enumValues = resolveFormEnum(enumSource, ctx, value);
   if (enumValues) {
     plan.commit = "select";
     plan.debounceMs = 0;
@@ -1041,13 +1214,16 @@ function deriveField(prop: string, ps: JsonSchema, args: DeriveArgs): SchemaForm
     row.kind = "json";
     row.value = current !== undefined ? JSON.stringify(current, null, 2) : "";
     row.placeholder = ps.description ?? "JSON Schema defining the data shape…";
-    row.chips = shapeChips(current);
+    row.chips = schemaPropertyChips(current);
     row.hasChips = row.chips.length > 0;
     return row;
   }
   if (ps.type === "array" && ps.items?.type === "object" && ps.items.properties) {
     return arrayOfObjects(prop, ps.items.properties, args, plan, row);
   }
+  if (ps.type === "array" && isSingleValueSchema(ps.items)) {
+    return arrayOfSingleValues(prop, ps.items, args, plan, row);
+  }
   /* A union with an object or a list in it (`alerts` is an object of types or `false`) is JSON too:
      a text box would store what is typed as a string, which is none of the members. */
   const types = Array.isArray(ps.type) ? ps.type : [ps.type];
@@ -1062,21 +1238,41 @@ function deriveField(prop: string, ps: JsonSchema, args: DeriveArgs): SchemaForm
   row.kind = "text";
   row.value = asText(current);
   row.placeholder = ps.default !== undefined ? String(ps.default) : (ps.examples?.[0] ?? "");
+  row.inputType = TEXT_INPUT_TYPES.get(ps.format ?? "") ?? "text";
+  /* A date input shows nothing for a value it cannot read, so a timestamp is shown as its day. YAML
+     reads an unquoted date as a Date, which reaches here as its quoted JSON. */
+  const day = /^"?(\d{4}-\d{2}-\d{2})/.exec(row.value);
+  if (row.inputType === "date" && day) {
+    row.value = day[1] ?? row.value;
+  }
   return row;
 }
 
+/**
+ * The native input a string format is typed in. `date` is the one that changes what can be typed: a
+ * date picker, and a value that is always `YYYY-MM-DD`, the `full-date` JSON Schema's `date` names.
+ * `email` and `uri` only change the keyboard a phone shows, and the value stays the text typed.
+ */
+const TEXT_INPUT_TYPES: ReadonlyMap<string, string> = new Map([
+  ["date", "date"],
+  ["email", "email"],
+  ["uri", "url"],
+]);
+
 /** The property chips above a JSON-Schema field: what shape is in there right now. */
-function shapeChips(current: unknown): { key: string; label: string }[] {
-  if (!current || typeof current !== "object") {
+function schemaPropertyChips(current: JsonValue | undefined): { key: string; label: string }[] {
+  // An array names no `properties`, so it has no chips either.
+  if (!isJsonObject(current)) {
     return [];
   }
-  const held = current as Record<string, unknown>;
-  if (held.$ref || typeof held.properties !== "object" || held.properties === null) {
+  const { properties } = current;
+  if (current.$ref || properties === null || !isNonNullObject(properties)) {
     return [];
   }
-  return Object.entries(held.properties as Record<string, Record<string, unknown>>).map(
-    ([key, spec]) => ({ key, label: `${key}: ${String(spec.type ?? "any")}` }),
-  );
+  return Object.entries(properties).map(([key, spec]) => ({
+    key,
+    label: `${key}: ${String((isJsonObject(spec) ? spec.type : undefined) ?? "any")}`,
+  }));
 }
 
 /** An array whose items have a declared shape: one row per item, one cell per property. */
@@ -1088,7 +1284,10 @@ function arrayOfObjects(
   row: SchemaFormFieldView,
 ): SchemaFormFieldView {
   const held = args.value[prop];
-  const rows = Array.isArray(held) ? (held as Record<string, unknown>[]) : [];
+  /* SAFETY: the caller dispatches here only for a property whose schema declares
+     `items.type: "object"`, so a conforming record holds an object per item; a malformed item is
+     still drawn as the row it should be, as it always was, rather than silently dropped. */
+  const rows = Array.isArray(held) ? (held as JsonObject[]) : [];
   plan.commit = "none";
   plan.itemProps = itemProps;
   plan.rows = rows;
@@ -1099,10 +1298,73 @@ function arrayOfObjects(
   return row;
 }
 
+/** The one cell key a row of an array of single values is drawn under. */
+const SCALAR_CELL = "value";
+
+/**
+ * Whether an array's items are single values a cell can edit: text, a number, a yes/no, one of an
+ * enum, or an entry of another collection. A picture is text with `format: "image"`, so it is one.
+ */
+function isSingleValueSchema(items: JsonSchema | undefined): items is JsonSchema {
+  if (items === undefined || items.format === "json-schema") {
+    return false;
+  }
+  if (referenceTarget(items) !== null || Array.isArray(items.enum)) {
+    return true;
+  }
+  return (
+    items.type === "string" ||
+    items.type === "number" ||
+    items.type === "integer" ||
+    items.type === "boolean"
+  );
+}
+
+/**
+ * An array of single values (`categories: string[]`, a gallery's picture paths): one row per item,
+ * each a single cell drawn by the item schema, with the same remove and add an array of objects
+ * gets. A value that is not yet a list (a CSV cell holding one category) is shown as its one item,
+ * and becomes a list the moment it is edited; the field's own check still says it is not one.
+ */
+function arrayOfSingleValues(
+  prop: string,
+  items: JsonSchema,
+  args: DeriveArgs,
+  plan: FieldPlan,
+  row: SchemaFormFieldView,
+): SchemaFormFieldView {
+  const held = args.value[prop];
+  let list: JsonValue[] = [];
+  if (Array.isArray(held)) {
+    list = held;
+  } else if (held !== undefined && held !== null && held !== "") {
+    list = [held];
+  }
+  const rows: JsonObject[] = list.map((item) => ({ [SCALAR_CELL]: item }));
+  const itemProps = { [SCALAR_CELL]: items };
+  const label = args.opts.ui?.[prop]?.label ?? prop;
+  plan.commit = "none";
+  plan.itemProps = itemProps;
+  plan.rows = rows;
+  plan.scalarItems = true;
+  plan.cellControls = new Map();
+  plan.refCells = new Set();
+  row.kind = "rows";
+  row.rows = rows.map((item, idx) => {
+    const drawn = deriveRow(prop, String(idx), item, itemProps, args, plan);
+    // A row has one cell, so the cell is named by its place in the list rather than by `value`.
+    for (const cell of drawn.cells) {
+      cell.label = `${label} ${idx + 1}`;
+    }
+    return drawn;
+  });
+  return row;
+}
+
 function deriveRow(
   prop: string,
   key: string,
-  item: Record<string, unknown>,
+  item: JsonObject,
   itemProps: Record<string, JsonSchema>,
   args: DeriveArgs,
   plan: FieldPlan,
@@ -1122,7 +1384,7 @@ function deriveCell(
   rowKey: string,
   cellKey: string,
   cellSchema: JsonSchema,
-  held: unknown,
+  held: JsonValue | undefined,
   args: DeriveArgs,
   plan: FieldPlan,
 ): SchemaFormCellView {
@@ -1144,10 +1406,10 @@ function deriveCell(
     return cell;
   }
   if (referenceTarget(cellSchema) !== null) {
-    /* A CELL's control is mounted into a host of the cell's own, exactly as a field's is: the one
-       control a cell is ever given is the reference picker, and that is a document now
-       (`surfaces/reference-field.json`). What the cell host must never become is a second writer of
-       a node the document already owns. */
+    /* A CELL's control is mounted into a host of the cell's own, exactly as a field's is: the
+       reference picker is a document now (`surfaces/reference-field.json`), as the media field
+       below is. What the cell host must never become is a second writer of a node the document
+       already owns. */
     const reference = controlRegistry.get("reference");
     if (reference) {
       cell.kind = "control";
@@ -1160,13 +1422,26 @@ function deriveCell(
       return cell;
     }
   }
-  const enumValues = resolveFormEnum(cellSchema.enum, args.ctx, args.value);
+  /* A picture cell (`format: "image"`, a gallery's item) is the media control a picture FIELD
+     gets, mounted into the cell's host by the same dispatch. */
+  const media = cellSchema.format === "image" ? controlRegistry.get("media") : undefined;
+  if (media) {
+    cell.kind = "control";
+    plan.cellControls?.set(id, { control: media, key: cellKey, row: rowKey, schema: cellSchema });
+    return cell;
+  }
+  // SAFETY: an item property's schema is read from JSON, so its `enum` is a JSON value.
+  const enumValues = resolveFormEnum(
+    cellSchema.enum as JsonValue | undefined,
+    args.ctx,
+    args.value,
+  );
   if (enumValues) {
     cell.kind = "select";
     cell.value = held !== undefined ? String(held) : NONE;
     cell.options = [
       { label: "—", value: NONE },
-      ...enumValues.map((v: string): SchemaFormOption => ({ label: v, value: v })),
+      ...enumValues.map((v: string): SurfaceOption => ({ label: v, value: v })),
     ];
     return cell;
   }