@xemahq/ui-kernel 0.6.0 → 0.7.0

package/src/session-kit/approvals/Obligation.tsx

@@ -1,5 +1,5 @@
 /**
- * Obligation chip + quorum dots (HANDOFF §6).
+ * Obligation chip + quorum dots.
  *
  * `Obligation` renders one obligation as a chip: host-supplied icon (via
  * `renderIcon` from the stable `ObligationIcon` key) + label + optional

package/src/session-kit/approvals/ScopedBody.tsx

@@ -1,5 +1,5 @@
 /**
- * Scoped approval bodies (HANDOFF §6) — the biome-supplied typed detail
+ * Scoped approval bodies — the biome-supplied typed detail
  * that renders UNDER the generic frame.
  *
  * `ScopedBody` is an EXHAUSTIVE switch over `ApprovalScopeKind`. A scope

package/src/session-kit/approvals/approval-model.ts

@@ -1,6 +1,5 @@
 /**
- * Approval primitive — generic frame model + scoped-body payloads
- * (Pillar 3 of the Xema Portals design handoff; HANDOFF §6).
+ * Approval primitive — generic frame model + scoped-body payloads.
  *
  * The approval is the runtime face of a kernel policy decision: a
  * capability call returns `allow | deny | needs_approval`
@@ -9,7 +8,7 @@
  * (risk pill + capability ref + obligations + quorum + actions); each
  * biome supplies a typed `scope` body for rich detail — the same
  * generic-frame + biome-body pattern as the in-chat widget registry
- * (HANDOFF §3.2) and the preview-tab kinds (HANDOFF §5).
+ * and the preview-tab kinds.
  *
  * This module REUSES the kernel contracts rather than redefining them:
  *   • `CapabilityRiskTier` (low/medium/high/critical) — risk pill + accent
@@ -24,7 +23,7 @@ import type { CapabilityRiskTier } from '@xemahq/kernel-contracts/capability';
 import type { PolicyObligationKind } from '@xemahq/kernel-contracts/policy';
 
 /**
- * Closed set of biome-supplied scoped-body kinds (HANDOFF §6). This is the
+ * Closed set of biome-supplied scoped-body kinds. This is the
  * approval analogue of `ChatWidgetKind` — a typed, versioned catalogue of
  * rich bodies that render UNDER the generic frame. The renderer
  * (`ScopedBody`) switches on `kind`; an unknown kind fails SAFE to a
@@ -165,7 +164,7 @@ export interface ApprovalRequest {
  * "allow once" vs "approve & remember" distinction is a UI affordance on
  * top of the same `Approved` decision (the remember flag is carried
  * separately when the backend supports it); both resolve the suspended
- * call. The denied/override-rationale path is DEFERRED (HANDOFF §6).
+ * call. The denied/override-rationale path is not yet implemented.
  */
 export enum ApprovalDecision {
   Approved = 'approved',
@@ -175,14 +174,14 @@ export enum ApprovalDecision {
 /**
  * A pending approval as it appears in the cross-portal Approvals Center —
  * the request plus the portal/session context it was raised in. The
- * portal fields are first-class so Pillar 4 (Portals) can batch and group
+ * portal fields are first-class so the Portals surface can batch and group
  * approvals across portals without reshaping this model.
  */
 export interface ApprovalCenterItem {
   /** Mirrors `request.id`; kept distinct so a Center may track its own row id. */
   readonly id: string;
   readonly request: ApprovalRequest;
-  /** Portal the approval was raised in (Pillar 4 cross-portal context). */
+  /** Portal the approval was raised in (cross-portal context). */
   readonly portalId?: string;
   readonly portalName?: string;
   /** Portal accent token (`var(--p-*)`) for the row glyph; optional. */
@@ -194,7 +193,7 @@ export interface ApprovalCenterItem {
 
 /** True when the tier always demands an explicit Approve (no allow-once). */
 export function isExplicitApprovalTier(tier: CapabilityRiskTier): boolean {
-  // `critical` and `high` are explicit-only (HANDOFF §6: critical always
+  // `critical` and `high` are explicit-only (critical always
   // explicit; high uses the warning accent and skips allow-once-remember).
   return tier === 'critical' || tier === 'high';
 }

package/src/session-kit/approvals/index.ts

@@ -1,6 +1,6 @@
 /**
  * `@xemahq/ui-kernel/session-kit` approvals — the generic approval
- * primitive (Pillar 3 of the Xema Portals design handoff; HANDOFF §6).
+ * primitive.
  *
  * Generic frame + scoped bodies + sticky bar + Approvals Center. Models on
  * the kernel contracts (`CapabilityRiskTier`, `PolicyObligationKind`) and

package/src/session-kit/approvals/obligation-display.ts

@@ -1,5 +1,5 @@
 /**
- * Obligation → display metadata map (HANDOFF §6).
+ * Obligation → display metadata map.
  *
  * Covers ALL NINE obligation kinds in the kernel closed taxonomy —
  * `audit`, `redact-secrets`, `require-runner-kind`,

package/src/session-kit/approvals/risk-accent.ts

@@ -1,6 +1,6 @@
 /**
  * Risk-tier → colour expressions for the approval frame's accent rail and
- * the sticky bar (HANDOFF §6). RiskPill owns the PILL styling; this map is
+ * the sticky bar. RiskPill owns the PILL styling; this map is
  * the matching surface accent (foreground / soft background / border) the
  * frame and bar paint with. Both read the SAME kernel `CapabilityRiskTier`
  * enum so the pill and the rail can never disagree on a tier's colour.

package/src/session-kit/combobox/Combobox.tsx

@@ -1,5 +1,5 @@
 /**
- * Generic searchable picker (HANDOFF §7). Use it wherever a closed set
+ * Generic searchable picker. Use it wherever a closed set
  * is selected (agents, models, skills/tools, …).
  *
  * - Shows a search field when `items.length > searchThreshold` (default

package/src/session-kit/display/MessageTurn.tsx

@@ -2,7 +2,7 @@
  * A single message turn. User turns render a right-aligned soft bubble;
  * agent turns render a thin gutter + role caption + flowing body.
  *
- * The body is rendered by `renderMarkdown` when supplied (Pillar 2 wires
+ * The body is rendered by `renderMarkdown` when supplied (host shells wire
  * the host's full `MarkdownRenderer` here) and falls back to the kit's
  * built-in `MD` otherwise — so the kit is self-contained but never
  * forces its tiny renderer on a host that has a richer one.

package/src/session-kit/display/TokenMeter.tsx

@@ -1,6 +1,6 @@
 /**
  * Token/cost meter — input & output token counts plus a running dollar
- * cost. Used both inside the ContextHeader and (in Pillar 2) absolute
+ * cost. Used both inside the ContextHeader and (in host shells) absolute
  * top-right of the composer.
  */
 import { SessionSkin } from '../lib/enums';

package/src/session-kit/index.ts

@@ -1,7 +1,7 @@
 /**
  * `@xemahq/ui-kernel/session-kit` — the thin, prop-driven generic
  * component substrate for agent-session surfaces and the Portals
- * chrome (Pillar 1 of the Xema Portals design handoff).
+ * chrome.
  *
  * Everything here is presentational and icon-agnostic: components take
  * data + host-supplied icon nodes and emit inline-styled markup against
@@ -9,7 +9,7 @@
  * subscriptions, no framework imports — so the same kit renders inside
  * the host shell and inside a biome's own surfaces.
  *
- * Pillar 2 consumes these via `import { … } from '@xemahq/ui-kernel/session-kit'`.
+ * Host shells consume these via `import { … } from '@xemahq/ui-kernel/session-kit'`.
  */
 
 // Closed-set enums + the authoritative status-dot map.
@@ -39,6 +39,6 @@ export * from './display/TodoChecklist';
 export * from './combobox/Combobox';
 export * from './combobox/use-click-outside';
 
-// Approvals primitive (Pillar 3 — generic frame + scoped bodies + sticky
+// Approvals primitive — generic frame + scoped bodies + sticky
 // bar + cross-portal Approvals Center).
 export * from './approvals';

package/src/session-kit/lib/enums.ts

@@ -17,7 +17,7 @@ export enum ToolStatus {
 }
 
 /**
- * The four authoritative transcript status-dot states (HANDOFF §3.1).
+ * The four authoritative transcript status-dot states.
  * `Narration` is the hollow dot used by a `say` event — it is not a
  * tool, so it sits outside `ToolStatus`.
  */

package/src/session-kit/lib/status-dot.ts

@@ -1,5 +1,5 @@
 /**
- * Authoritative transcript status-dot colour map (HANDOFF §3.1).
+ * Authoritative transcript status-dot colour map.
  *
  *   pending / running → amber, PULSING   (--warning)
  *   done / success    → green            (--success)

package/src/session-kit/primitives/RiskPill.tsx

@@ -4,7 +4,7 @@
  * string union. Critical renders an optional caller-supplied alert icon
  * (the kit carries no icon dependency, matching the rest of ui-kernel).
  *
- * Risk → colour (HANDOFF §6):
+ * Risk → colour:
  *   low      → ink / muted
  *   medium   → --info
  *   high     → --warning

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

@@ -0,0 +1,146 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// AppBrandingProvider — the runtime branding applier
+//
+// Takes a kernel `BrandingConfig` (plus an optional per-sub-tenant override)
+// and APPLIES it at runtime:
+//
+//   • writes `primaryColor` → `--app-primary-color` and every `cssTokens`
+//     entry → `--<key>` as CSS custom properties on its OWN wrapper element,
+//     so they cascade ONLY to the app subtree — never onto
+//     `document.documentElement`, so an app's branding cannot leak into the
+//     host chrome;
+//   • exposes `displayName` / `logoUrl` / `primaryColor` to children through
+//     context (`useAppBranding`) for a branded header to render.
+//
+// Every value crosses `sanitize.ts` first: an unsafe CSS value or a
+// non-`http(s)` logo URL is dropped, never written raw.
+//
+// This is the reusable half of Wave 8.4 — a biome imports it from
+// `@xemahq/ui-kernel/ui`, like `useIsMobile` / `Sheet`.
+// ═══════════════════════════════════════════════════════════════════════════
+import * as React from 'react';
+
+import type { BrandingConfig } from '@xemahq/kernel-contracts/app-runtime';
+
+import { cn } from '../cn';
+
+import {
+  sanitizeCssCustomPropertyName,
+  sanitizeCssValue,
+  sanitizeLogoUrl,
+} from './sanitize';
+
+/** CSS custom property carrying the app's resolved primary brand color. */
+export const APP_PRIMARY_COLOR_VAR = '--app-primary-color';
+
+/** Values a branded header needs — sanitized, safe to render. */
+export interface AppBrandingContextValue {
+  readonly displayName: string;
+  readonly logoUrl?: string;
+  readonly primaryColor?: string;
+}
+
+const AppBrandingContext = React.createContext<AppBrandingContextValue | null>(
+  null,
+);
+
+/**
+ * Resolved branding for the nearest enclosing {@link AppBrandingProvider}.
+ * Throws when used outside one — a header that assumes branding must not
+ * silently render an unbranded surface.
+ */
+export function useAppBranding(): AppBrandingContextValue {
+  const ctx = React.useContext(AppBrandingContext);
+  if (ctx === null) {
+    throw new Error(
+      'useAppBranding must be used within an <AppBrandingProvider>.',
+    );
+  }
+  return ctx;
+}
+
+export interface AppBrandingProviderProps {
+  /** The app's base branding (from the App definition / release). */
+  readonly branding: BrandingConfig;
+  /**
+   * Per-sub-tenant override, resolved from `AppRoleBinding.tenantId`. Each
+   * present field shadows the base; absent fields fall through to `branding`.
+   * Optional — apps with no sub-tenant branding pass nothing.
+   */
+  readonly tenantBranding?: Partial<BrandingConfig>;
+  /** Extra classes for the wrapper element. */
+  readonly className?: string;
+  readonly children: React.ReactNode;
+}
+
+/**
+ * Merge base branding with an optional per-sub-tenant override (override wins
+ * per field), then sanitize every applied value.
+ */
+function resolveBranding(
+  branding: BrandingConfig,
+  tenantBranding: Partial<BrandingConfig> | undefined,
+): {
+  readonly context: AppBrandingContextValue;
+  readonly cssVars: Record<string, string>;
+} {
+  const displayName = tenantBranding?.displayName ?? branding.displayName;
+  const rawPrimary = tenantBranding?.primaryColor ?? branding.primaryColor;
+  const rawLogo = tenantBranding?.logoUrl ?? branding.logoUrl;
+  const cssTokens = { ...branding.cssTokens, ...tenantBranding?.cssTokens };
+
+  const primaryColor =
+    rawPrimary !== undefined
+      ? (sanitizeCssValue(rawPrimary) ?? undefined)
+      : undefined;
+  const logoUrl = sanitizeLogoUrl(rawLogo);
+
+  const cssVars: Record<string, string> = {};
+  if (primaryColor !== undefined) {
+    cssVars[APP_PRIMARY_COLOR_VAR] = primaryColor;
+  }
+  for (const [rawKey, rawValue] of Object.entries(cssTokens)) {
+    const name = sanitizeCssCustomPropertyName(rawKey);
+    const value = sanitizeCssValue(rawValue);
+    if (name !== null && value !== null) {
+      cssVars[name] = value;
+    }
+  }
+
+  return {
+    context: { displayName, logoUrl, primaryColor },
+    cssVars,
+  };
+}
+
+/**
+ * Scopes an app's branding to its subtree. Renders a wrapper element carrying
+ * the CSS custom properties inline, so they cascade to the app content and
+ * nowhere else. On unmount the element (and its properties) simply disappear —
+ * no cleanup, no global mutation.
+ */
+export function AppBrandingProvider({
+  branding,
+  tenantBranding,
+  className,
+  children,
+}: AppBrandingProviderProps): React.ReactElement {
+  const { context, cssVars } = React.useMemo(
+    () => resolveBranding(branding, tenantBranding),
+    [branding, tenantBranding],
+  );
+
+  return (
+    <AppBrandingContext.Provider value={context}>
+      <div
+        data-app-branding=""
+        className={cn(className)}
+        // Custom properties are not part of `React.CSSProperties`; the cast is
+        // the standard way to set `--*` vars inline.
+        style={cssVars as React.CSSProperties}
+      >
+        {children}
+      </div>
+    </AppBrandingContext.Provider>
+  );
+}

package/src/ui/branding/sanitize.ts

@@ -0,0 +1,77 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// Branding DOM-boundary sanitizers
+//
+// A `BrandingConfig` is validated server-side (hex/rgb(a) `primaryColor`, a
+// URL `logoUrl`), but the runtime applier writes those values into the live
+// DOM — a CSS custom-property value and an `<img src>`. This module is the
+// fail-closed boundary: a value that could break out of the property it is
+// written into, or a URL scheme that could execute, is DROPPED (returns
+// `null` / `undefined`), never written raw. Pure functions, no React — unit
+// tested directly.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Characters that could terminate a CSS declaration/value and inject a new
+ * declaration or rule (`;`, `{`, `}`), close a surrounding context (`<`, `>`),
+ * escape (`\`), or open/close a CSS comment. React writes custom properties
+ * through the CSSOM, which already treats the string as a single value — this
+ * is defence in depth so a crafted value is refused at the seam.
+ */
+const CSS_VALUE_UNSAFE = /[;{}<>\\]|\/\*|\*\//;
+
+/**
+ * A CSS custom-property name (without the leading `--`): a CSS identifier. A
+ * `cssTokens` key becomes `--<key>`, so a key with breakout characters would be
+ * a foothold; anything that is not a plain ident is refused.
+ */
+const CSS_CUSTOM_PROPERTY_NAME = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
+
+/** True when the string contains any ASCII control character (0x00–0x1f, 0x7f). */
+function hasControlChar(value: string): boolean {
+  for (let i = 0; i < value.length; i += 1) {
+    const code = value.charCodeAt(i);
+    if (code < 0x20 || code === 0x7f) return true;
+  }
+  return false;
+}
+
+/**
+ * Sanitize a value destined for a CSS custom property (`--app-primary-color`
+ * or a `cssTokens` value). Returns the trimmed value, or `null` to DROP it.
+ */
+export function sanitizeCssValue(raw: string): string | null {
+  const value = raw.trim();
+  if (value.length === 0) return null;
+  if (CSS_VALUE_UNSAFE.test(value)) return null;
+  if (hasControlChar(value)) return null;
+  return value;
+}
+
+/**
+ * Sanitize a `cssTokens` KEY into a `--<name>` custom-property name. Returns
+ * the full property name (`--<name>`), or `null` to DROP the token.
+ */
+export function sanitizeCssCustomPropertyName(rawKey: string): string | null {
+  const name = rawKey.trim();
+  if (!CSS_CUSTOM_PROPERTY_NAME.test(name)) return null;
+  return `--${name}`;
+}
+
+/**
+ * Sanitize a logo URL destined for an `<img src>`. Only absolute `http(s)`
+ * URLs pass; a `javascript:`, `data:`, or otherwise-schemed / unparseable value
+ * is refused (returns `undefined`) so it never reaches `src`.
+ */
+export function sanitizeLogoUrl(raw: string | undefined): string | undefined {
+  if (raw === undefined) return undefined;
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    return undefined;
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return undefined;
+  }
+  return parsed.href;
+}

package/src/ui/breakpoints.ts

@@ -0,0 +1,14 @@
+/**
+ * Responsive breakpoint token — the single source of truth shared by the
+ * JS side (`useIsMobile`) and Tailwind's `md` utility.
+ *
+ * Tailwind's default `md` breakpoint is `min-width: 768px`. Anything narrower
+ * than that is "mobile". Binding the JS constant to that exact value is what
+ * lets a component decide table-vs-cards in JS and stay in lockstep with the
+ * `md:` classes the same component (or its siblings) use — there is exactly
+ * ONE breakpoint system, not two.
+ *
+ * If the Tailwind `md` screen is ever re-tuned, change it HERE and in the
+ * Tailwind theme in the same commit — they are two faces of one token.
+ */
+export const MOBILE_BREAKPOINT = 768;

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,59 @@
+// 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);
+  });
+});