@xemahq/ui-kernel 0.6.1 → 0.8.0

package/src/offline/types.ts

@@ -0,0 +1,77 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// @xemahq/ui-kernel/offline — types
+//
+// A generic offline field-capture kit: an IndexedDB-backed outbox that queues
+// mutations while disconnected and drains them (with retry + idempotency) on
+// reconnect. Provider-agnostic — any mutation (an app-forge record submit, a
+// status change, …) is enqueued by a stable `kind` whose executor is registered
+// once. The motivating case is field/trade-fair capture with no signal.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Lifecycle of a queued mutation. */
+export enum OutboxEntryStatus {
+  /** Waiting to be sent (offline, or not yet attempted). */
+  Pending = 'pending',
+  /** Currently being sent. */
+  Inflight = 'inflight',
+  /** Failed transiently; will be retried (attempts < maxAttempts). */
+  Retrying = 'retrying',
+  /** Exhausted retries — needs manual retry or discard (dead-letter). */
+  Failed = 'failed',
+}
+
+/** One queued mutation. `payload` is opaque to the outbox; the executor for
+ *  `kind` interprets it. */
+export interface OutboxEntry<TPayload = unknown> {
+  /** Stable entry id (also the default idempotency key). */
+  id: string;
+  /** Registered executor key (e.g. "app-forge:create-record"). */
+  kind: string;
+  payload: TPayload;
+  /** Sent to the backend so a redelivered mutation is not double-applied. */
+  idempotencyKey: string;
+  status: OutboxEntryStatus;
+  attempts: number;
+  createdAt: number;
+  updatedAt: number;
+  /** Last error message (for the dead-letter UI). */
+  lastError?: string;
+  /** Optional human label for the pending-items UI. */
+  label?: string;
+}
+
+/** Persistence backend for the outbox. IndexedDB in the browser; in-memory for
+ *  SSR / tests. */
+export interface OutboxStorage {
+  getAll(): Promise<OutboxEntry[]>;
+  put(entry: OutboxEntry): Promise<void>;
+  delete(id: string): Promise<void>;
+  clear(): Promise<void>;
+}
+
+/** Context passed to an executor when a queued mutation is sent. */
+export interface OutboxExecuteContext {
+  /** Pass to the backend (e.g. as an `Idempotency-Key` header). */
+  idempotencyKey: string;
+  /** How many times this entry has now been attempted (1-based). */
+  attempt: number;
+  entryId: string;
+}
+
+/** Sends one queued mutation. Throwing schedules a retry (see
+ *  {@link OutboxOptions.isRetriable}). */
+export type OutboxExecutor<TPayload = unknown> = (
+  payload: TPayload,
+  ctx: OutboxExecuteContext,
+) => Promise<void>;
+
+/** Snapshot of outbox state for UI (offline badge, pending count, dead-letter). */
+export interface OutboxSnapshot {
+  entries: OutboxEntry[];
+  pendingCount: number;
+  failedCount: number;
+  /** True while a drain is in progress. */
+  draining: boolean;
+  /** Current connectivity (from the outbox's online controller). */
+  online: boolean;
+}

package/src/ui/branding/app-branding-provider.tsx

@@ -20,7 +20,7 @@
 // ═══════════════════════════════════════════════════════════════════════════
 import * as React from 'react';
 
-import type { BrandingConfig } from '@xemahq/kernel-contracts/app-runtime';
+import type { BrandingConfig } from '@xemahq/kernel-contracts/app-platform';
 
 import { cn } from '../cn';
 

package/src/ui/capture/document-preview.tsx

@@ -0,0 +1,101 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// <DocumentPreview> — read-only "final document" view for the review step
+//
+// Renders a structured record as the document it will become — grouped by
+// section, one labelled row per field, nested objects/lists expanded inline.
+// Presentational + theme-aware (semantic tokens, light/dark) + responsive.
+// Feed it the SAME schema you gave `<SchemaForm>` so the review mirrors input.
+// ═══════════════════════════════════════════════════════════════════════════
+import { type ReactNode } from 'react';
+
+import { cn } from '../cn';
+
+import { CaptureFieldType, type CaptureFieldSpec, type CaptureSchema, type CaptureSection, type CaptureValues, toSections } from './field-spec';
+import { formatScalar } from './value-format';
+
+export interface DocumentPreviewProps {
+  readonly fields?: readonly CaptureFieldSpec[];
+  readonly sections?: readonly CaptureSection[];
+  readonly schema?: CaptureSchema;
+  readonly values: CaptureValues;
+  readonly title?: string;
+  /** Text shown for an unset field (default "—"). */
+  readonly emptyText?: string;
+  readonly className?: string;
+}
+
+/**
+ * @example
+ * <DocumentPreview title="Review" sections={sections} values={values} />
+ */
+export function DocumentPreview({ fields, sections, schema, values, title, emptyText = '—', className }: DocumentPreviewProps) {
+  const resolved = toSections(sections ?? (fields ? fields : schema) ?? []);
+  return (
+    <article className={cn('rounded-xl border border-border bg-card p-5 text-card-foreground shadow-sm sm:p-6', className)}>
+      {title ? <h2 className="mb-4 text-title font-semibold tracking-tight text-ink">{title}</h2> : null}
+      <div className="space-y-6">
+        {resolved.map((section) => (
+          <section key={section.key}>
+            {section.title ? <h3 className="mb-2 border-b border-rule pb-1 text-caption font-semibold uppercase tracking-wider text-ink-3">{section.title}</h3> : null}
+            <dl className="grid grid-cols-1 gap-x-6 gap-y-3 sm:grid-cols-[minmax(8rem,12rem)_1fr]">
+              {section.fields.map((field) => (
+                <FieldRow key={field.key} field={field} value={values[field.key]} emptyText={emptyText} />
+              ))}
+            </dl>
+          </section>
+        ))}
+      </div>
+    </article>
+  );
+}
+
+function FieldRow({ field, value, emptyText }: { field: CaptureFieldSpec; value: unknown; emptyText: string }) {
+  return (
+    <>
+      <dt className="text-body-1 font-medium text-ink-3 sm:text-right">{field.label}</dt>
+      <dd className="min-w-0 text-body-1 text-ink">{renderValue(field, value, emptyText)}</dd>
+    </>
+  );
+}
+
+function renderValue(field: CaptureFieldSpec, value: unknown, emptyText: string): ReactNode {
+  if (field.type === CaptureFieldType.Object) {
+    const record = (value && typeof value === 'object' && !Array.isArray(value) ? value : null) as CaptureValues | null;
+    if (!record) return <span className="text-ink-3">{emptyText}</span>;
+    return (
+      <dl className="space-y-1 rounded-md border border-rule bg-paper-elev/40 p-2">
+        {(field.fields ?? []).map((child) => (
+          <div key={child.key} className="flex flex-wrap gap-2">
+            <dt className="text-caption font-medium text-ink-3">{child.label}:</dt>
+            <dd className="text-caption text-ink">{renderValue(child, record[child.key], emptyText)}</dd>
+          </div>
+        ))}
+      </dl>
+    );
+  }
+  if (field.type === CaptureFieldType.List) {
+    const items = (Array.isArray(value) ? value : []) as CaptureValues[];
+    if (items.length === 0) return <span className="text-ink-3">{emptyText}</span>;
+    return (
+      <ol className="space-y-2">
+        {items.map((item, index) => (
+          <li key={index} className="rounded-md border border-rule bg-paper-elev/40 p-2">
+            <p className="mb-1 text-caption font-medium text-ink-3">
+              {field.label} #{index + 1}
+            </p>
+            <dl className="space-y-1">
+              {(field.fields ?? []).map((child) => (
+                <div key={child.key} className="flex flex-wrap gap-2">
+                  <dt className="text-caption font-medium text-ink-3">{child.label}:</dt>
+                  <dd className="text-caption text-ink">{renderValue(child, item[child.key], emptyText)}</dd>
+                </div>
+              ))}
+            </dl>
+          </li>
+        ))}
+      </ol>
+    );
+  }
+  const text = formatScalar(field, value, emptyText);
+  return <span className={cn(text === emptyText && 'text-ink-3')}>{text}</span>;
+}

package/src/ui/capture/field-spec-to-zod.test.ts

@@ -0,0 +1,81 @@
+// Pure-logic proofs for the CaptureFieldSpec → zod adapter. Runs under the
+// host-web vitest runner (this package carries no vitest dep — see tsconfig
+// exclude), mirroring the repo convention used by i18n-port.test.ts.
+import { describe, expect, it } from 'vitest';
+
+import { CaptureFieldType, type CaptureFieldSpec } from './field-spec';
+import { fieldSpecToZod, isEmptyValue } from './field-spec-to-zod';
+
+describe('isEmptyValue', () => {
+  it('treats undefined/null/empty-string/empty-array as absent', () => {
+    expect(isEmptyValue(undefined)).toBe(true);
+    expect(isEmptyValue(null)).toBe(true);
+    expect(isEmptyValue('')).toBe(true);
+    expect(isEmptyValue([])).toBe(true);
+    expect(isEmptyValue('x')).toBe(false);
+    expect(isEmptyValue(0)).toBe(false);
+    expect(isEmptyValue(false)).toBe(false);
+  });
+});
+
+describe('fieldSpecToZod', () => {
+  const fields: CaptureFieldSpec[] = [
+    { key: 'title', label: 'Title', type: CaptureFieldType.String, required: true },
+    { key: 'count', label: 'Count', type: CaptureFieldType.Number, required: false, min: 0 },
+    { key: 'status', label: 'Status', type: CaptureFieldType.Enum, enumValues: ['open', 'closed'], required: true },
+    {
+      key: 'tags',
+      label: 'Tags',
+      type: CaptureFieldType.List,
+      min: 1,
+      fields: [{ key: 'name', label: 'Name', type: CaptureFieldType.String, required: true }],
+    },
+  ];
+
+  it('accepts a valid record', () => {
+    const r = fieldSpecToZod(fields).safeParse({ title: 'Hi', count: 3, status: 'open', tags: [{ name: 'a' }] });
+    expect(r.success).toBe(true);
+  });
+
+  it('rejects an empty required string', () => {
+    const r = fieldSpecToZod(fields).safeParse({ title: '', status: 'open', tags: [{ name: 'a' }] });
+    expect(r.success).toBe(false);
+  });
+
+  it('allows an omitted optional field', () => {
+    const r = fieldSpecToZod(fields).safeParse({ title: 'Hi', status: 'closed', tags: [{ name: 'a' }] });
+    expect(r.success).toBe(true);
+  });
+
+  it('rejects an enum value outside the set', () => {
+    const r = fieldSpecToZod(fields).safeParse({ title: 'Hi', status: 'bogus', tags: [{ name: 'a' }] });
+    expect(r.success).toBe(false);
+  });
+
+  it('enforces list min and nested required item fields', () => {
+    expect(fieldSpecToZod(fields).safeParse({ title: 'Hi', status: 'open', tags: [] }).success).toBe(false);
+    expect(fieldSpecToZod(fields).safeParse({ title: 'Hi', status: 'open', tags: [{ name: '' }] }).success).toBe(false);
+  });
+});
+
+describe('media fields (image/file/audio)', () => {
+  const media: CaptureFieldSpec[] = [
+    { key: 'photo', label: 'Photo', type: CaptureFieldType.Image, required: true },
+    { key: 'attachment', label: 'Attachment', type: CaptureFieldType.File },
+    { key: 'memo', label: 'Voice memo', type: CaptureFieldType.Audio },
+  ];
+  const dataUrl = 'data:image/png;base64,AAAA';
+
+  it('accepts a captured data-URL for a required media field', () => {
+    expect(fieldSpecToZod(media).safeParse({ photo: dataUrl }).success).toBe(true);
+  });
+
+  it('rejects an empty required media field', () => {
+    expect(fieldSpecToZod(media).safeParse({ photo: '' }).success).toBe(false);
+    expect(fieldSpecToZod(media).safeParse({}).success).toBe(false);
+  });
+
+  it('allows omitted optional media fields', () => {
+    expect(fieldSpecToZod(media).safeParse({ photo: dataUrl }).success).toBe(true);
+  });
+})

package/src/ui/capture/field-spec-to-zod.ts

@@ -0,0 +1,104 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// CaptureFieldSpec → Zod adapter
+//
+// Bridges the JSON-Schema-like field spec (name/type/required/enum, and the
+// nested object/list composites) to a `zod` schema so `useSchemaValidation`
+// works with app definitions, not only hand-written zod. Deterministic and
+// pure — no side effects, safe to memoize on the spec identity.
+// ═══════════════════════════════════════════════════════════════════════════
+import { z } from 'zod';
+
+import { CaptureFieldType, type CaptureFieldSpec, type CaptureSchema, type CaptureSection, toFieldList } from './field-spec';
+
+/** `''`, `null`, `undefined` all mean "absent" at the capture boundary. */
+export function isEmptyValue(value: unknown): boolean {
+  return value === undefined || value === null || value === '' || (Array.isArray(value) && value.length === 0);
+}
+
+function scalarSchema(field: CaptureFieldSpec): z.ZodTypeAny {
+  switch (field.type) {
+    case CaptureFieldType.Number: {
+      let s = z.number({ message: `${field.label} must be a number` });
+      if (typeof field.min === 'number') s = s.min(field.min, { message: `${field.label} must be ≥ ${field.min}` });
+      if (typeof field.max === 'number') s = s.max(field.max, { message: `${field.label} must be ≤ ${field.max}` });
+      return s;
+    }
+    case CaptureFieldType.Boolean:
+      return z.boolean({ message: `${field.label} must be true or false` });
+    case CaptureFieldType.Decimal:
+      // NUMERIC carried as a string to avoid float precision loss.
+      return z.string().regex(/^-?\d+(\.\d+)?$/, { message: `${field.label} must be a decimal number` });
+    case CaptureFieldType.Enum: {
+      const values = [...(field.enumValues ?? [])];
+      if (values.length === 0) return z.string();
+      return z.enum(values as [string, ...string[]]);
+    }
+    case CaptureFieldType.Date:
+      return z.string().regex(/^\d{4}-\d{2}-\d{2}$/, { message: `${field.label} must be a date` });
+    case CaptureFieldType.Datetime:
+      return z.string().min(1, { message: `${field.label} must be a date/time` });
+    // string / text / user / reference — plain text.
+    default:
+      return z.string();
+  }
+}
+
+function fieldSchema(field: CaptureFieldSpec): z.ZodTypeAny {
+  let base: z.ZodTypeAny;
+  if (field.type === CaptureFieldType.Object) {
+    base = objectSchema(field.fields ?? []);
+  } else if (field.type === CaptureFieldType.List) {
+    let arr = z.array(objectSchema(field.fields ?? []));
+    if (typeof field.min === 'number') arr = arr.min(field.min, { message: `${field.label} needs at least ${field.min} item(s)` });
+    if (typeof field.max === 'number') arr = arr.max(field.max, { message: `${field.label} allows at most ${field.max} item(s)` });
+    base = arr;
+  } else {
+    base = scalarSchema(field);
+    if (
+      field.required &&
+      (field.type === CaptureFieldType.String ||
+        field.type === CaptureFieldType.Text ||
+        field.type === CaptureFieldType.User ||
+        field.type === CaptureFieldType.Reference ||
+        field.type === CaptureFieldType.Datetime ||
+        // Media fields carry a data-URL string; required = a capture was made.
+        field.type === CaptureFieldType.Image ||
+        field.type === CaptureFieldType.File ||
+        field.type === CaptureFieldType.Audio)
+    ) {
+      base = (base as z.ZodString).min(1, { message: `${field.label} is required` });
+    }
+  }
+
+  if (!field.required) {
+    // Optional: `.optional()` makes the object KEY absent-safe (zod v4 does not
+    // infer that from a union with z.undefined()); the union additionally
+    // accepts the empty-string / null sentinels the inputs emit for "cleared".
+    return z.union([base, z.literal(''), z.null()]).optional();
+  }
+  return base;
+}
+
+function objectSchema(fields: readonly CaptureFieldSpec[]): z.ZodObject<z.ZodRawShape> {
+  const shape: Record<string, z.ZodTypeAny> = {};
+  for (const f of fields) shape[f.key] = fieldSchema(f);
+  // Non-strict: unknown keys are ignored (the server is the strict fence).
+  return z.object(shape);
+}
+
+/**
+ * Build a `zod` object schema from a capture schema (flat fields, sections, or
+ * a `CaptureSchema`). The result validates the whole values record.
+ *
+ * @example
+ * const schema = fieldSpecToZod([
+ *   { key: 'title', label: 'Title', type: 'string', required: true },
+ *   { key: 'tags', label: 'Tags', type: 'list', fields: [{ key: 'name', label: 'Name', type: 'string', required: true }] },
+ * ]);
+ * schema.safeParse({ title: 'Hi', tags: [{ name: 'a' }] }); // { success: true }
+ */
+export function fieldSpecToZod(
+  schema: CaptureSchema | readonly CaptureFieldSpec[] | readonly CaptureSection[],
+): z.ZodObject<z.ZodRawShape> {
+  return objectSchema(toFieldList(schema));
+}

package/src/ui/capture/field-spec.test.ts

@@ -0,0 +1,49 @@
+// Pure-logic proofs for the schema-face normalizers. Runs under host-web
+// vitest (this package carries no vitest dep — see tsconfig exclude).
+import { describe, expect, it } from 'vitest';
+
+import { CaptureFieldType, groupFieldsBySection, toFieldList, toSections, type CaptureFieldSpec, type CaptureSection } from './field-spec';
+
+const fields: CaptureFieldSpec[] = [
+  { key: 'a', label: 'A', type: CaptureFieldType.String, section: 'one' },
+  { key: 'b', label: 'B', type: CaptureFieldType.Number, section: 'one' },
+  { key: 'c', label: 'C', type: CaptureFieldType.Boolean, section: 'two' },
+];
+
+const sections: CaptureSection[] = [
+  { key: 's1', title: 'S1', fields: [{ key: 'a', label: 'A', type: CaptureFieldType.String }] },
+  { key: 's2', title: 'S2', fields: [{ key: 'b', label: 'B', type: CaptureFieldType.String }] },
+];
+
+describe('toFieldList', () => {
+  it('returns a flat field list unchanged', () => {
+    expect(toFieldList(fields).map((f) => f.key)).toEqual(['a', 'b', 'c']);
+  });
+  it('flattens sections to their fields', () => {
+    expect(toFieldList(sections).map((f) => f.key)).toEqual(['a', 'b']);
+  });
+  it('reads the { fields } schema face', () => {
+    expect(toFieldList({ fields }).map((f) => f.key)).toEqual(['a', 'b', 'c']);
+  });
+  it('reads the { sections } schema face', () => {
+    expect(toFieldList({ sections }).map((f) => f.key)).toEqual(['a', 'b']);
+  });
+});
+
+describe('groupFieldsBySection', () => {
+  it('splits a flat list by each field section key, preserving order', () => {
+    const grouped = groupFieldsBySection(fields);
+    expect(grouped.map((s) => s.key)).toEqual(['one', 'two']);
+    expect(grouped[0].fields.map((f) => f.key)).toEqual(['a', 'b']);
+    expect(grouped[1].fields.map((f) => f.key)).toEqual(['c']);
+  });
+});
+
+describe('toSections', () => {
+  it('passes explicit sections through', () => {
+    expect(toSections(sections).map((s) => s.title)).toEqual(['S1', 'S2']);
+  });
+  it('derives sections from a flat list', () => {
+    expect(toSections(fields).map((s) => s.key)).toEqual(['one', 'two']);
+  });
+});

package/src/ui/capture/field-spec.ts

@@ -0,0 +1,181 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// Guided-capture field spec — the ONE schema shape the capture kit consumes
+//
+// This is the frontend-agnostic superset of app-forge-web's `AppField`. The
+// wire/definition layer (app-forge-api, its renderer's `AppFieldType`) owns 10
+// closed field types; this kit mirrors those 10 verbatim (same string values,
+// so an `AppField` is structurally assignable to `CaptureFieldSpec`) and ADDS
+// two structural composites — `object` and `list` — plus optional `section`
+// grouping. A workbench therefore extends ONE renderer (`<SchemaForm>`) instead
+// of the three parallel schema→form implementations that exist today.
+//
+// Value shape produced/consumed:
+//   scalar field  → string | number | boolean            (per type)
+//   object field  → Record<string, unknown>              (nested record)
+//   list field    → unknown[]                            (array of item records)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Closed set of capture field types. The first ten are value-identical to
+ * app-forge-web's `AppFieldType` (`string`/`text`/`number`/`decimal`/`boolean`/
+ * `date`/`datetime`/`enum`/`reference`/`user`) so definitions authored for the
+ * App Platform pass straight through. `object`/`list` are the structural
+ * composites this kit adds for nested + repeatable capture.
+ *
+ * The string VALUES are the contract — keep the first ten identical to
+ * `AppFieldType` in `@xemahq/kernel-contracts/app-definition` (the single
+ * source of truth for App Platform field types). Adding a value here that
+ * `AppFieldType` lacks is fine (superset); changing an existing shared value is
+ * not. This kit can't import the enum (it adds members), so the shared values
+ * are mirrored deliberately.
+ */
+export enum CaptureFieldType {
+  String = 'string',
+  Text = 'text',
+  Number = 'number',
+  Decimal = 'decimal',
+  Boolean = 'boolean',
+  Date = 'date',
+  Datetime = 'datetime',
+  Enum = 'enum',
+  Reference = 'reference',
+  User = 'user',
+  Object = 'object',
+  List = 'list',
+  // ── Media capture (field-capture kit) ──
+  // Value is a data-URL string (base64), so it stays JSON-serializable and
+  // flows unchanged through the record model + the offline outbox. `Image`
+  // opens the device camera on mobile (`capture`), `File` attaches any file,
+  // `Audio` records a voice memo via MediaRecorder.
+  Image = 'image',
+  File = 'file',
+  Audio = 'audio',
+}
+
+/**
+ * A single capture field. Structural superset of app-forge's `AppField`:
+ * `key`/`label`/`type`/`required`/`enumValues`/`referenceEntity` carry the
+ * exact same meaning, so `AppField[]` can be handed to this kit unchanged. The
+ * extra props are additive and all optional.
+ *
+ * `type` accepts the {@link CaptureFieldType} enum OR its bare string value, so
+ * `{ type: 'string' }` (app-forge shape) and `{ type: CaptureFieldType.String }`
+ * both type-check.
+ */
+export interface CaptureFieldSpec {
+  readonly key: string;
+  readonly label: string;
+  readonly type: CaptureFieldType | `${CaptureFieldType}`;
+  readonly required?: boolean;
+  /** Helper text rendered under the label. */
+  readonly description?: string;
+  /** Placeholder for text-like inputs. */
+  readonly placeholder?: string;
+  /** Only for `enum` — the allowed values. */
+  readonly enumValues?: readonly string[];
+  /** Only for `reference` — key of the target entity (opaque to this kit). */
+  readonly referenceEntity?: string;
+  /** Only for `object`/`list` — the nested item shape. */
+  readonly fields?: readonly CaptureFieldSpec[];
+  /** `number`/`decimal`: numeric bounds. `list`: min/max item count. */
+  readonly min?: number;
+  readonly max?: number;
+  /**
+   * `image`/`file`/`audio`: the `accept` filter for the file picker (e.g.
+   * `image/*`, `application/pdf`). Defaults per type when omitted.
+   */
+  readonly accept?: string;
+  /**
+   * `image`/`file`: the HTML `capture` hint — `environment` opens the rear
+   * camera, `user` the front camera. Omitted = a normal file picker.
+   */
+  readonly capture?: 'user' | 'environment';
+  /**
+   * Optional section grouping key for FLAT `CaptureFieldSpec[]` schemas. When a
+   * schema is expressed as {@link CaptureSection}[] this is ignored (grouping is
+   * explicit). See {@link groupFieldsBySection}.
+   */
+  readonly section?: string;
+}
+
+/** A titled group of fields — the explicit sectioned schema shape. */
+export interface CaptureSection {
+  readonly key: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly fields: readonly CaptureFieldSpec[];
+}
+
+/**
+ * A capture schema is EITHER a flat field list OR a list of titled sections.
+ * `<SchemaForm>`, `useSchemaValidation`, and `<DocumentPreview>` all accept
+ * either face.
+ */
+export type CaptureSchema =
+  | { readonly fields: readonly CaptureFieldSpec[]; readonly sections?: undefined }
+  | { readonly sections: readonly CaptureSection[]; readonly fields?: undefined };
+
+/** Structured record value the capture kit reads/writes. */
+export type CaptureValues = Record<string, unknown>;
+
+/** True if `x` is the sectioned face of a schema. */
+export function isSectioned(
+  x: CaptureSchema | readonly CaptureFieldSpec[] | readonly CaptureSection[],
+): x is { readonly sections: readonly CaptureSection[] } {
+  return !Array.isArray(x) && 'sections' in (x as object) && Array.isArray((x as { sections?: unknown }).sections);
+}
+
+/**
+ * Normalize any accepted schema face to the flat list of TOP-LEVEL fields.
+ * (Nested `object`/`list` item fields are NOT flattened — they belong to their
+ * parent's value.) Accepts a `CaptureFieldSpec[]`, a `CaptureSection[]`, or a
+ * `CaptureSchema`.
+ */
+export function toFieldList(
+  schema: CaptureSchema | readonly CaptureFieldSpec[] | readonly CaptureSection[],
+): readonly CaptureFieldSpec[] {
+  if (Array.isArray(schema)) {
+    const arr = schema as readonly (CaptureFieldSpec | CaptureSection)[];
+    // A CaptureSection has `title`+`fields`; a CaptureFieldSpec has `type`.
+    if (arr.length > 0 && arr.every((e) => 'title' in e && 'fields' in e && !('type' in e))) {
+      return (arr as readonly CaptureSection[]).flatMap((s) => s.fields);
+    }
+    return arr as readonly CaptureFieldSpec[];
+  }
+  if (isSectioned(schema)) return schema.sections.flatMap((s) => s.fields);
+  return (schema as { fields: readonly CaptureFieldSpec[] }).fields;
+}
+
+/**
+ * Resolve any accepted schema face to `CaptureSection[]`. A flat field list
+ * collapses to a single untitled section (or is split by each field's
+ * `section` key when present).
+ */
+export function toSections(
+  schema: CaptureSchema | readonly CaptureFieldSpec[] | readonly CaptureSection[],
+  fallbackTitle = '',
+): readonly CaptureSection[] {
+  if (Array.isArray(schema) && schema.length > 0 && (schema as readonly object[]).every((e) => 'title' in e && 'fields' in e)) {
+    return schema as readonly CaptureSection[];
+  }
+  if (!Array.isArray(schema) && isSectioned(schema)) return schema.sections;
+  return groupFieldsBySection(toFieldList(schema), fallbackTitle);
+}
+
+/** Split a flat field list into sections by each field's `section` key. */
+export function groupFieldsBySection(
+  fields: readonly CaptureFieldSpec[],
+  fallbackTitle = '',
+): readonly CaptureSection[] {
+  const order: string[] = [];
+  const byKey = new Map<string, CaptureFieldSpec[]>();
+  for (const f of fields) {
+    const key = f.section ?? '';
+    if (!byKey.has(key)) {
+      byKey.set(key, []);
+      order.push(key);
+    }
+    byKey.get(key)!.push(f);
+  }
+  return order.map((key) => ({ key: key || '_', title: key || fallbackTitle, fields: byKey.get(key)! }));
+}

package/src/ui/capture/index.ts

@@ -0,0 +1,43 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// @xemahq/ui-kernel — guided-capture UX kit (B5)
+//
+// Headless engines + presentation-thin primitives for schema-driven, guided
+// data capture: a wizard state machine, live client-side validation, AI/context
+// pre-fill, a single consolidated schema→form renderer, and a review-step
+// document preview. Consolidates the three parallel schema→form implementations
+// so a workbench extends ONE renderer.
+// ═══════════════════════════════════════════════════════════════════════════
+
+// ── field-spec model (aligned superset of app-forge's AppFieldType) ──
+export {
+  CaptureFieldType,
+  isSectioned,
+  toFieldList,
+  toSections,
+  groupFieldsBySection,
+  type CaptureFieldSpec,
+  type CaptureSection,
+  type CaptureSchema,
+  type CaptureValues,
+} from './field-spec';
+
+// ── schema → zod adapter ──
+export { fieldSpecToZod, isEmptyValue } from './field-spec-to-zod';
+
+// ── validation + "missing info" ──
+export { useSchemaValidation, type SchemaValidationResult } from './use-schema-validation';
+
+// ── pre-fill ──
+export { usePrefill, type UsePrefillOptions, type UsePrefillResult } from './use-prefill';
+
+// ── wizard engine + shell ──
+export { useWizard, type WizardApi, type WizardStepDef, type UseWizardOptions } from './use-wizard';
+export { Wizard, WizardStep, type WizardProps, type WizardStepProps } from './wizard';
+
+// ── consolidated schema form ──
+export { SchemaForm, type SchemaFormProps } from './schema-form';
+export { SchemaFieldInput, type SchemaFieldInputProps, type RenderReference } from './schema-field-input';
+export { asString, formatScalar } from './value-format';
+
+// ── review-step document preview ──
+export { DocumentPreview, type DocumentPreviewProps } from './document-preview';