@xemahq/ui-kernel 0.8.0 → 0.9.1

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

@@ -0,0 +1,147 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// Total runtime validator for a `CaptureFieldSpec[]` arriving from the wire
+//
+// `fieldSpecToZod` validates the VALUES a form produces. This validates the
+// SCHEMA itself, for the case where the field list is not authored in TypeScript
+// but carried in an envelope (a Vista `form` surface payload, a biome
+// contribution, an agent-authored capture step).
+//
+// Contract: TOTAL and NEVER throws — it returns the narrowed specs or `null`,
+// exactly like the Vista payload validators, so a malformed schema degrades to
+// a visible typed fallback instead of a half-rendered form.
+// ═══════════════════════════════════════════════════════════════════════════
+import { CaptureFieldTransform, CaptureFieldType, type CaptureFieldSpec } from './field-spec';
+
+const FIELD_TYPES: ReadonlySet<string> = new Set(Object.values(CaptureFieldType));
+const TRANSFORMS: ReadonlySet<string> = new Set(Object.values(CaptureFieldTransform));
+
+type UnknownRecord = Readonly<Record<string, unknown>>;
+
+function asRecord(value: unknown): UnknownRecord | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as UnknownRecord)
+    : null;
+}
+
+/** `undefined` passes through; a present non-string is a rejection (`null`). */
+function optionalString(value: unknown): string | undefined | null {
+  if (value === undefined) return undefined;
+  return typeof value === 'string' ? value : null;
+}
+
+/** `undefined` passes through; a present non-boolean is a rejection (`null`). */
+function optionalBoolean(value: unknown): boolean | undefined | null {
+  if (value === undefined) return undefined;
+  return typeof value === 'boolean' ? value : null;
+}
+
+/** `undefined` passes through; a present non-number is a rejection (`null`). */
+function optionalNumber(value: unknown): number | undefined | null {
+  if (value === undefined) return undefined;
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+/** Narrow ONE field spec. Returns `null` for anything malformed. */
+export function validateCaptureField(raw: unknown): CaptureFieldSpec | null {
+  const record = asRecord(raw);
+  if (record === null) return null;
+  if (typeof record.key !== 'string' || record.key.length === 0) return null;
+  if (typeof record.label !== 'string' || record.label.length === 0) return null;
+  if (typeof record.type !== 'string' || !FIELD_TYPES.has(record.type)) return null;
+
+  const required = optionalBoolean(record.required);
+  if (required === null) return null;
+  const isSecret = optionalBoolean(record.isSecret);
+  if (isSecret === null) return null;
+  const description = optionalString(record.description);
+  if (description === null) return null;
+  const placeholder = optionalString(record.placeholder);
+  if (placeholder === null) return null;
+  const section = optionalString(record.section);
+  if (section === null) return null;
+  const referenceEntity = optionalString(record.referenceEntity);
+  if (referenceEntity === null) return null;
+  const accept = optionalString(record.accept);
+  if (accept === null) return null;
+  const min = optionalNumber(record.min);
+  if (min === null) return null;
+  const max = optionalNumber(record.max);
+  if (max === null) return null;
+
+  let transform: CaptureFieldTransform | undefined;
+  if (record.transform !== undefined) {
+    if (typeof record.transform !== 'string' || !TRANSFORMS.has(record.transform)) return null;
+    transform = record.transform as CaptureFieldTransform;
+  }
+
+  let enumValues: readonly string[] | undefined;
+  if (record.enumValues !== undefined) {
+    if (!Array.isArray(record.enumValues)) return null;
+    if (!record.enumValues.every((v) => typeof v === 'string')) return null;
+    enumValues = record.enumValues;
+  }
+
+  let capture: 'user' | 'environment' | undefined;
+  if (record.capture !== undefined) {
+    if (record.capture !== 'user' && record.capture !== 'environment') return null;
+    capture = record.capture;
+  }
+
+  let fields: readonly CaptureFieldSpec[] | undefined;
+  if (record.fields !== undefined) {
+    const nested = validateCaptureFields(record.fields);
+    if (nested === null) return null;
+    fields = nested;
+  }
+
+  const spec: {
+    key: string;
+    label: string;
+    type: CaptureFieldType;
+    required?: boolean;
+    isSecret?: boolean;
+    transform?: CaptureFieldTransform;
+    description?: string;
+    placeholder?: string;
+    section?: string;
+    referenceEntity?: string;
+    accept?: string;
+    capture?: 'user' | 'environment';
+    enumValues?: readonly string[];
+    fields?: readonly CaptureFieldSpec[];
+    min?: number;
+    max?: number;
+  } = { key: record.key, label: record.label, type: record.type as CaptureFieldType };
+
+  if (required !== undefined) spec.required = required;
+  if (isSecret !== undefined) spec.isSecret = isSecret;
+  if (transform !== undefined) spec.transform = transform;
+  if (description !== undefined) spec.description = description;
+  if (placeholder !== undefined) spec.placeholder = placeholder;
+  if (section !== undefined) spec.section = section;
+  if (referenceEntity !== undefined) spec.referenceEntity = referenceEntity;
+  if (accept !== undefined) spec.accept = accept;
+  if (capture !== undefined) spec.capture = capture;
+  if (enumValues !== undefined) spec.enumValues = enumValues;
+  if (fields !== undefined) spec.fields = fields;
+  if (min !== undefined) spec.min = min;
+  if (max !== undefined) spec.max = max;
+
+  return spec;
+}
+
+/**
+ * Narrow a whole field list. An EMPTY array is valid and narrows to `[]` — an
+ * empty schema is a real, meaningful state (the server is the authority on
+ * whether a form with no fields may be submitted), not a validation failure.
+ */
+export function validateCaptureFields(raw: unknown): readonly CaptureFieldSpec[] | null {
+  if (!Array.isArray(raw)) return null;
+  const out: CaptureFieldSpec[] = [];
+  for (const entry of raw) {
+    const spec = validateCaptureField(entry);
+    if (spec === null) return null;
+    out.push(spec);
+  }
+  return out;
+}

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

@@ -50,6 +50,53 @@ export enum CaptureFieldType {
   Image = 'image',
   File = 'file',
   Audio = 'audio',
+  // ── Scalar text refinements (absorbed from the connector credential form) ──
+  // These change only the NATIVE INPUT TYPE (keyboard + browser affordances);
+  // the value is a plain string. `Json` additionally renders as a mono textarea
+  // and is validated as parseable JSON.
+  Email = 'email',
+  Url = 'url',
+  Json = 'json',
+}
+
+/**
+ * Normalization applied to a captured STRING value at the input boundary.
+ *
+ * Value-identical in meaning to the connector `CredentialFieldTransform`
+ * (`NONE`/`UPPERCASE`/`LOWERCASE`/`TRIM`) but named in this kit's lowercase
+ * vocabulary, because the capture kit is domain-agnostic and must not import a
+ * connector contract. The connector→capture adapter lives at the consuming
+ * seam, not here.
+ *
+ * This is the ONLY normalization the kit performs. There is deliberately no
+ * blanket trim on submit: an undeclared transform would silently override a
+ * field that declared {@link CaptureFieldTransform.None}.
+ */
+export enum CaptureFieldTransform {
+  None = 'none',
+  Uppercase = 'uppercase',
+  Lowercase = 'lowercase',
+  Trim = 'trim',
+}
+
+/** Apply a declared transform to a string value. Total; absent = unchanged. */
+export function applyCaptureTransform(
+  value: string,
+  transform: CaptureFieldTransform | `${CaptureFieldTransform}` | undefined,
+): string {
+  switch (transform) {
+    case CaptureFieldTransform.Uppercase:
+      return value.toUpperCase();
+    case CaptureFieldTransform.Lowercase:
+      return value.toLowerCase();
+    case CaptureFieldTransform.Trim:
+      return value.trim();
+    case CaptureFieldTransform.None:
+    case undefined:
+      return value;
+    default:
+      return value;
+  }
 }
 
 /**
@@ -96,6 +143,21 @@ export interface CaptureFieldSpec {
    * explicit). See {@link groupFieldsBySection}.
    */
   readonly section?: string;
+  /**
+   * DECLARED write-only secrecy. When true the input is masked, never
+   * pre-filled from a read, and never echoed back by any read path.
+   *
+   * Secrecy is DECLARED, never inferred from {@link type}: a plain-`string`
+   * field can be a secret and a `password`-shaped field can be public. The
+   * renderer reads this flag and nothing else — do not re-introduce a
+   * `type === password` inference.
+   */
+  readonly isSecret?: boolean;
+  /**
+   * Declared normalization applied to the string value at the input boundary.
+   * Absent = {@link CaptureFieldTransform.None}.
+   */
+  readonly transform?: CaptureFieldTransform | `${CaptureFieldTransform}`;
 }
 
 /** A titled group of fields — the explicit sectioned schema shape. */

package/src/ui/capture/index.ts

@@ -11,6 +11,8 @@
 // ── field-spec model (aligned superset of app-forge's AppFieldType) ──
 export {
   CaptureFieldType,
+  CaptureFieldTransform,
+  applyCaptureTransform,
   isSectioned,
   toFieldList,
   toSections,
@@ -21,8 +23,14 @@ export {
   type CaptureValues,
 } from './field-spec';
 
+// ── total runtime validator for a wire-carried schema ──
+export { validateCaptureField, validateCaptureFields } from './field-spec-validate';
+
 // ── schema → zod adapter ──
-export { fieldSpecToZod, isEmptyValue } from './field-spec-to-zod';
+export { fieldSpecToZod, isEmptyValue, isParsableJson } from './field-spec-to-zod';
+
+// ── values → wire payload ──
+export { captureValuesToStringMap, captureValuesToSubmitPayload } from './submit-values';
 
 // ── validation + "missing info" ──
 export { useSchemaValidation, type SchemaValidationResult } from './use-schema-validation';

package/src/ui/capture/schema-field-input.tsx

@@ -6,8 +6,14 @@
 // items) composites. `reference` is source-agnostic here: it defaults to a text
 // input, but a caller can inject a picker via `renderReference` (that is the
 // seam app-forge uses to plug its record-backed `ReferenceSelect`).
+//
+// This is the ONE schema→input renderer in the tree. The connector-specific
+// `CredentialFormRenderer` was folded in here: a DECLARED-secret field
+// (`spec.isSecret`) renders the write-only masked input, and `email`/`url`/
+// `json` are ordinary capture field types. Secrecy is never inferred from the
+// field type.
 // ═══════════════════════════════════════════════════════════════════════════
-import { Plus, Trash2 } from 'lucide-react';
+import { Eye, EyeOff, Plus, Trash2 } from 'lucide-react';
 import { useCallback, useRef, useState, type ReactNode } from 'react';
 
 import { cn } from '../cn';
@@ -17,7 +23,7 @@ import { Input } from '../primitives/input';
 import { Label } from '../primitives/label';
 import { Textarea } from '../primitives/textarea';
 
-import { CaptureFieldType, type CaptureFieldSpec, type CaptureValues } from './field-spec';
+import { applyCaptureTransform, CaptureFieldType, type CaptureFieldSpec, type CaptureValues } from './field-spec';
 import { asString } from './value-format';
 
 const SELECT_CLASS =
@@ -44,42 +50,78 @@ export interface SchemaFieldInputProps {
   readonly renderReference?: RenderReference;
 }
 
+/** Native `type` for the single-line text-ish capture types. */
+function nativeInputType(type: CaptureFieldSpec['type']): 'text' | 'email' | 'url' {
+  switch (type) {
+    case CaptureFieldType.Email:
+      return 'email';
+    case CaptureFieldType.Url:
+      return 'url';
+    default:
+      return 'text';
+  }
+}
+
 export function SchemaFieldInput(props: SchemaFieldInputProps) {
   const { field, value, onChange, disabled, path, renderReference } = props;
   const inputId = `field-${path}`;
 
+  // The ONE place a captured string is normalized. Composites (object/list)
+  // emit records/arrays and pass through untouched.
+  const emit = (next: unknown): void =>
+    onChange(typeof next === 'string' ? applyCaptureTransform(next, field.transform) : next);
+
+  // DECLARED secrecy wins over the field type: a secret is always write-only
+  // and masked, whatever shape it has. Never inferred from `type`.
+  if (field.isSecret === true) {
+    return <SecretFieldInput field={field} value={value} onChange={emit} disabled={disabled} inputId={inputId} />;
+  }
+
   switch (field.type) {
     case CaptureFieldType.Text:
-      return <Textarea id={inputId} value={asString(value)} onChange={(e) => onChange(e.target.value)} disabled={disabled} rows={4} placeholder={field.placeholder} />;
+      return <Textarea id={inputId} value={asString(value)} onChange={(e) => emit(e.target.value)} disabled={disabled} rows={4} placeholder={field.placeholder} />;
+    case CaptureFieldType.Json:
+      return (
+        <Textarea
+          id={inputId}
+          value={asString(value)}
+          onChange={(e) => emit(e.target.value)}
+          disabled={disabled}
+          rows={6}
+          spellCheck={false}
+          className="min-h-[120px] font-mono"
+          placeholder={field.placeholder}
+        />
+      );
     case CaptureFieldType.Number:
       return (
         <Input
           id={inputId}
           type="number"
           value={asString(value)}
-          onChange={(e) => onChange(e.target.value === '' ? '' : Number(e.target.value))}
+          onChange={(e) => emit(e.target.value === '' ? '' : Number(e.target.value))}
           disabled={disabled}
           placeholder={field.placeholder}
         />
       );
     case CaptureFieldType.Decimal:
       // NUMERIC carried verbatim as text — never Number()-coerced (precision).
-      return <Input id={inputId} type="text" inputMode="decimal" value={asString(value)} onChange={(e) => onChange(e.target.value)} disabled={disabled} placeholder={field.placeholder ?? '0.00'} />;
+      return <Input id={inputId} type="text" inputMode="decimal" value={asString(value)} onChange={(e) => emit(e.target.value)} disabled={disabled} placeholder={field.placeholder ?? '0.00'} />;
     case CaptureFieldType.User:
-      return <Input id={inputId} value={asString(value)} onChange={(e) => onChange(e.target.value)} disabled={disabled} placeholder={field.placeholder ?? 'subject id'} />;
+      return <Input id={inputId} value={asString(value)} onChange={(e) => emit(e.target.value)} disabled={disabled} placeholder={field.placeholder ?? 'subject id'} />;
     case CaptureFieldType.Boolean:
       return (
         <div className="mt-1">
-          <Checkbox id={inputId} checked={value === true} onCheckedChange={(checked) => onChange(checked === true)} disabled={disabled} />
+          <Checkbox id={inputId} checked={value === true} onCheckedChange={(checked) => emit(checked === true)} disabled={disabled} />
         </div>
       );
     case CaptureFieldType.Date:
-      return <Input id={inputId} type="date" value={asString(value)} onChange={(e) => onChange(e.target.value)} disabled={disabled} />;
+      return <Input id={inputId} type="date" value={asString(value)} onChange={(e) => emit(e.target.value)} disabled={disabled} />;
     case CaptureFieldType.Datetime:
-      return <Input id={inputId} type="datetime-local" value={asString(value)} onChange={(e) => onChange(e.target.value)} disabled={disabled} />;
+      return <Input id={inputId} type="datetime-local" value={asString(value)} onChange={(e) => emit(e.target.value)} disabled={disabled} />;
     case CaptureFieldType.Enum:
       return (
-        <select id={inputId} className={SELECT_CLASS} value={asString(value)} onChange={(e) => onChange(e.target.value)} disabled={disabled}>
+        <select id={inputId} className={SELECT_CLASS} value={asString(value)} onChange={(e) => emit(e.target.value)} disabled={disabled}>
           <option value="">— select —</option>
           {(field.enumValues ?? []).map((v) => (
             <option key={v} value={v}>
@@ -90,9 +132,9 @@ export function SchemaFieldInput(props: SchemaFieldInputProps) {
       );
     case CaptureFieldType.Reference:
       return renderReference ? (
-        <>{renderReference({ field, value, onChange, disabled, inputId })}</>
+        <>{renderReference({ field, value, onChange: emit, disabled, inputId })}</>
       ) : (
-        <Input id={inputId} value={asString(value)} onChange={(e) => onChange(e.target.value)} disabled={disabled} placeholder={field.placeholder ?? 'reference id'} />
+        <Input id={inputId} value={asString(value)} onChange={(e) => emit(e.target.value)} disabled={disabled} placeholder={field.placeholder ?? 'reference id'} />
       );
     case CaptureFieldType.Object:
       return <ObjectInput {...props} />;
@@ -103,10 +145,88 @@ export function SchemaFieldInput(props: SchemaFieldInputProps) {
       return <MediaFieldInput {...props} />;
     case CaptureFieldType.Audio:
       return <AudioFieldInput {...props} />;
-    // string (and any unknown) — plain single-line input.
+    // string / email / url (and any unknown) — single-line input.
     default:
-      return <Input id={inputId} value={asString(value)} onChange={(e) => onChange(e.target.value)} disabled={disabled} placeholder={field.placeholder} />;
+      return <Input id={inputId} type={nativeInputType(field.type)} value={asString(value)} onChange={(e) => emit(e.target.value)} disabled={disabled} placeholder={field.placeholder} />;
+  }
+}
+
+/**
+ * Write-only input for a DECLARED-secret field.
+ *
+ * `autoComplete="off"` + `data-lpignore` keep password managers and the browser
+ * credential store from persisting the value; the reveal toggle is local and
+ * transient. The component holds no cache: it renders exactly the value the
+ * caller passes and nothing else, so a read path that returns no secret
+ * material (the only kind this kit is used with) can never repopulate it.
+ */
+function SecretFieldInput({
+  field,
+  value,
+  onChange,
+  disabled,
+  inputId,
+}: Readonly<{
+  field: CaptureFieldSpec;
+  value: unknown;
+  onChange: (next: unknown) => void;
+  disabled?: boolean;
+  inputId: string;
+}>) {
+  const [reveal, setReveal] = useState(false);
+  const multiline = field.type === CaptureFieldType.Json || field.type === CaptureFieldType.Text;
+
+  if (multiline && reveal) {
+    return (
+      <div className="relative">
+        <Textarea
+          id={inputId}
+          value={asString(value)}
+          onChange={(e) => onChange(e.target.value)}
+          disabled={disabled}
+          rows={6}
+          spellCheck={false}
+          autoComplete="off"
+          className="min-h-[120px] pr-9 font-mono"
+          placeholder={field.placeholder}
+        />
+        <RevealToggle reveal={reveal} onToggle={() => setReveal((v) => !v)} />
+      </div>
+    );
   }
+
+  return (
+    <div className="relative">
+      <Input
+        id={inputId}
+        type={reveal ? 'text' : 'password'}
+        value={asString(value)}
+        onChange={(e) => onChange(e.target.value)}
+        disabled={disabled}
+        autoComplete="off"
+        spellCheck={false}
+        data-lpignore="true"
+        className="pr-9 font-mono"
+        placeholder={field.placeholder}
+      />
+      <RevealToggle reveal={reveal} onToggle={() => setReveal((v) => !v)} />
+    </div>
+  );
+}
+
+function RevealToggle({ reveal, onToggle }: Readonly<{ reveal: boolean; onToggle: () => void }>) {
+  return (
+    <Button
+      type="button"
+      size="sm"
+      variant="ghost"
+      className="absolute right-0 top-0 h-9 w-9 p-0"
+      onClick={onToggle}
+      aria-label={reveal ? 'Hide value' : 'Show value'}
+    >
+      {reveal ? <EyeOff className="h-4 w-4" /> : <Eye className="h-4 w-4" />}
+    </Button>
+  );
 }
 
 const FILE_INPUT_CLASS =

package/src/ui/capture/submit-values.test.ts

@@ -0,0 +1,70 @@
+// Pure-logic proofs for the ONE values→wire projection and the declared
+// transform. Runs under the host-web vitest runner (this package carries no
+// vitest dep — see tsconfig exclude).
+import { describe, expect, it } from 'vitest';
+
+import { applyCaptureTransform, CaptureFieldTransform, CaptureFieldType, type CaptureFieldSpec } from './field-spec';
+import { fieldSpecToZod } from './field-spec-to-zod';
+import { captureValuesToStringMap, captureValuesToSubmitPayload } from './submit-values';
+
+const fields: CaptureFieldSpec[] = [
+  { key: 'apiKey', label: 'API key', type: CaptureFieldType.String, required: true, isSecret: true },
+  { key: 'baseUrl', label: 'Base URL', type: CaptureFieldType.Url, required: true },
+  { key: 'serviceAccount', label: 'Service account', type: CaptureFieldType.Json, required: false },
+];
+
+describe('applyCaptureTransform', () => {
+  it('applies only the DECLARED transform', () => {
+    expect(applyCaptureTransform(' a ', CaptureFieldTransform.Trim)).toBe('a');
+    expect(applyCaptureTransform('a', CaptureFieldTransform.Uppercase)).toBe('A');
+    expect(applyCaptureTransform('A', CaptureFieldTransform.Lowercase)).toBe('a');
+    expect(applyCaptureTransform(' a ', CaptureFieldTransform.None)).toBe(' a ');
+    // Absent = no normalization. There is no implicit blanket trim.
+    expect(applyCaptureTransform(' a ', undefined)).toBe(' a ');
+  });
+});
+
+describe('captureValuesToStringMap', () => {
+  it('projects ONLY declared keys, as strings', () => {
+    expect(
+      captureValuesToStringMap(fields, {
+        apiKey: 'sk-1',
+        baseUrl: 'https://acme.test',
+        rogue: 'should not travel',
+      }),
+    ).toEqual({ apiKey: 'sk-1', baseUrl: 'https://acme.test', serviceAccount: '' });
+  });
+});
+
+describe('captureValuesToSubmitPayload', () => {
+  it('parses a json field and leaves the rest untouched', () => {
+    expect(
+      captureValuesToSubmitPayload(fields, {
+        apiKey: 'sk-1',
+        baseUrl: 'https://acme.test',
+        serviceAccount: '{"a":1}',
+      }),
+    ).toEqual({ apiKey: 'sk-1', baseUrl: 'https://acme.test', serviceAccount: { a: 1 } });
+  });
+
+  it('does not drop an unparseable json value — validation is the gate', () => {
+    expect(captureValuesToSubmitPayload(fields, { serviceAccount: '{' }).serviceAccount).toBe('{');
+  });
+});
+
+describe('json field validation', () => {
+  const schema = fieldSpecToZod(fields);
+
+  it('rejects an unparseable json blob', () => {
+    expect(schema.safeParse({ apiKey: 'k', baseUrl: 'u', serviceAccount: '{' }).success).toBe(false);
+  });
+
+  it('accepts a parseable json blob and an omitted optional one', () => {
+    expect(schema.safeParse({ apiKey: 'k', baseUrl: 'u', serviceAccount: '{"a":1}' }).success).toBe(true);
+    expect(schema.safeParse({ apiKey: 'k', baseUrl: 'u' }).success).toBe(true);
+  });
+
+  it('requires a non-empty url/email field when required', () => {
+    expect(schema.safeParse({ apiKey: 'k', baseUrl: '' }).success).toBe(false);
+  });
+});

package/src/ui/capture/submit-values.ts

@@ -0,0 +1,63 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// Capture values → submit payload
+//
+// The ONE projection from the form's in-memory `CaptureValues` to what goes on
+// the wire. Two faces, because two wire contracts exist and neither should grow
+// its own inline projection:
+//
+//   • `captureValuesToStringMap` — every field as a STRING (the shape a
+//     credential submit takes: `fields: Record<string, string>`).
+//   • `captureValuesToSubmitPayload` — same, except a `json` field is PARSED
+//     into its structured value (the shape the connection credential write
+//     takes: `credentials: Record<string, unknown>`).
+//
+// Both are field-driven: only DECLARED keys are projected, so a stray key in
+// the values record can never reach the wire. Neither performs an undeclared
+// normalization — trimming/casing is `CaptureFieldTransform`, applied once at
+// the input boundary. A blanket trim here would silently override a field that
+// declared `transform: none`.
+// ═══════════════════════════════════════════════════════════════════════════
+import { CaptureFieldType, toFieldList, type CaptureFieldSpec, type CaptureSchema, type CaptureSection, type CaptureValues } from './field-spec';
+import { asString } from './value-format';
+
+type Schema = CaptureSchema | readonly CaptureFieldSpec[] | readonly CaptureSection[];
+
+/** Project the declared fields to a flat `string` map (fields-only wire). */
+export function captureValuesToStringMap(
+  schema: Schema,
+  values: CaptureValues,
+): Record<string, string> {
+  const payload: Record<string, string> = {};
+  for (const field of toFieldList(schema)) {
+    payload[field.key] = asString(values[field.key]);
+  }
+  return payload;
+}
+
+/**
+ * Project the declared fields, parsing `json` fields into structured values.
+ *
+ * A `json` field that does not parse is left as its raw string — validation is
+ * `useSchemaValidation`'s job and it must run first; this projection does not
+ * silently drop a value it cannot parse.
+ */
+export function captureValuesToSubmitPayload(
+  schema: Schema,
+  values: CaptureValues,
+): CaptureValues {
+  const payload: CaptureValues = {};
+  for (const field of toFieldList(schema)) {
+    const raw = values[field.key];
+    if (field.type !== CaptureFieldType.Json) {
+      payload[field.key] = raw;
+      continue;
+    }
+    const text = asString(raw);
+    try {
+      payload[field.key] = JSON.parse(text);
+    } catch {
+      payload[field.key] = text;
+    }
+  }
+  return payload;
+}

package/src/ui/index.ts

@@ -54,6 +54,10 @@ export {
   PreviewDeviceFrame,
   type PreviewDevice,
 } from './primitives/preview-device-frame';
+export {
+  UrlPreviewChrome,
+  type UrlPreviewChromeProps,
+} from './primitives/url-preview-chrome';
 
 // ── chart primitives (Wave 9.2 — pure SVG, no external chart lib) ──
 export * from './charts';
@@ -87,7 +91,10 @@ export { default as PageHeader, PageToolbar } from './chrome/PageHeader';
 export { default as LoadingState, type LoadingStateVariant } from './chrome/LoadingState';
 export { default as AsyncBoundary } from './chrome/AsyncBoundary';
 
-export { PdfPreview, type PdfPreviewProps } from './pdf/pdf-preview';
+// NOTE: `PdfPreview` intentionally does NOT live in this barrel. It pulls in
+// `react-pdf` → `pdfjs-dist` (~1.9 MB), so it ships from the dedicated subpath
+// `@xemahq/ui-kernel/pdf` to keep this `/ui` surface (and app-ui's AppShell)
+// tree-shakeable. Import it from `@xemahq/ui-kernel/pdf`.
 
 // ── guided-capture UX kit (B5 — wizard, validation, prefill, schema form) ──
 export * from './capture';