@xemahq/ui-kernel 0.8.0 → 0.9.1

package/src/lib/biome-host/biome-registry.ts

@@ -1,6 +1,11 @@
 import { Registry } from '@xemahq/registry';
 import { useSyncExternalStore } from 'react';
 
+import {
+  DuplicateContributionPolicy,
+  createContributionRegistry,
+} from '../contribution-registry';
+
 import type {
   FrontendBiome,
   FrontendBiomeFactory,
@@ -153,23 +158,38 @@ class FrontendBiomeRegistry extends Registry<string, FrontendBiome & { key: stri
    * light up the moment the biome's frontend loads. Duplicate kinds
    * across biomes are surfaced as a console error and the first
    * registration wins (deterministic + fail-loud, not silent).
+   *
+   * Built on the shared `createContributionRegistry` core — the same
+   * closed+open two-layer bookkeeping the ChatWidget, reply-variant and
+   * Vista-surface registries use. This overlay is rebuilt on every call
+   * (it is read during render), so it takes the `FirstWins` duplicate
+   * policy rather than `Throw`: a duplicate must not take down a render.
+   * `FirstWins` still REQUIRES the `onDuplicate` reporter below — the
+   * rejected contribution is never dropped silently.
    */
   outputRenderers(): ReadonlyMap<string, OutputRendererContribution> {
-    const out = new Map<string, OutputRendererContribution>();
-    if (!this.enabled) return out;
+    if (!this.enabled) return new Map<string, OutputRendererContribution>();
+    // `onDuplicate` fires SYNCHRONOUSLY from inside `register()`, so this
+    // cursor always names the biome whose contribution was rejected — the
+    // contribution object itself does not carry its owner.
+    let contributingBiomeId = '';
+    const overlay = createContributionRegistry<OutputRendererContribution>({
+      name: 'biome outputRenderer',
+      duplicatePolicy: DuplicateContributionPolicy.FirstWins,
+      onDuplicate: (outputKind) => {
+        console.error(
+          `[xema-ui-kernel] duplicate outputRenderer for kind '${outputKind}' ` +
+            `from biome '${contributingBiomeId}'; first registration wins.`,
+        );
+      },
+    });
     for (const biome of this.list()) {
+      contributingBiomeId = biome.id;
       for (const entry of biome.outputRenderers ?? []) {
-        if (out.has(entry.outputKind)) {
-          console.error(
-            `[xema-ui-kernel] duplicate outputRenderer for kind '${entry.outputKind}' ` +
-              `from biome '${biome.id}'; first registration wins.`,
-          );
-          continue;
-        }
-        out.set(entry.outputKind, entry);
+        overlay.register(entry.outputKind, entry);
       }
     }
-    return out;
+    return overlay.entries();
   }
 
   private notify(): void {

package/src/lib/contribution-registry/contribution-registry.spec.ts

@@ -0,0 +1,141 @@
+/**
+ * Guards the shared closed+open contribution registry core — the ONE
+ * implementation behind the ChatWidget, biome output-renderer, reply-variant
+ * and Vista-surface planes. Every property the hand-written copies had must
+ * survive the extraction.
+ *
+ * Runs under the host-web vitest mirror (this package carries no vitest dep).
+ */
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  ContributionFallbackReason,
+  DuplicateContributionPolicy,
+  createContributionRegistry,
+  createRenderableContributionRegistry,
+} from './index';
+
+function makeRegistry(): ReturnType<typeof createContributionRegistry<string>> {
+  return createContributionRegistry<string>({
+    name: 'test',
+    reservedKinds: ['plan', 'diff'],
+  });
+}
+
+describe('createContributionRegistry', () => {
+  it('resolves first-party before open, and lists both', () => {
+    const registry = makeRegistry();
+    registry.registerFirstParty('plan', 'builtin-plan');
+    registry.register('acme:gantt', 'acme-gantt');
+    expect(registry.get('plan')).toBe('builtin-plan');
+    expect(registry.get('acme:gantt')).toBe('acme-gantt');
+    expect(registry.has('nope')).toBe(false);
+    expect(registry.list()).toEqual(['acme:gantt', 'plan']);
+    expect(registry.listOpen()).toEqual(['acme:gantt']);
+    expect([...registry.entries().keys()].sort()).toEqual(['acme:gantt', 'plan']);
+  });
+
+  it('refuses to let the open set claim a reserved first-party kind', () => {
+    const registry = makeRegistry();
+    expect(registry.isReserved('diff')).toBe(true);
+    expect(() => registry.register('diff', 'hijack')).toThrow(/reserved/);
+    // The namespaced form is fine.
+    expect(() => registry.register('acme:diff', 'ok')).not.toThrow();
+  });
+
+  it('is idempotent for the identical entry and throws for a different one', () => {
+    const registry = makeRegistry();
+    registry.register('acme:gantt', 'entry');
+    expect(() => registry.register('acme:gantt', 'entry')).not.toThrow();
+    expect(() => registry.register('acme:gantt', 'other')).toThrow(
+      /already registered/,
+    );
+    registry.registerFirstParty('plan', 'builtin');
+    expect(() => registry.registerFirstParty('plan', 'builtin')).not.toThrow();
+    expect(() => registry.registerFirstParty('plan', 'other')).toThrow(
+      /already registered/,
+    );
+  });
+
+  it('resets only the OPEN set', () => {
+    const registry = makeRegistry();
+    registry.registerFirstParty('plan', 'builtin');
+    registry.register('acme:gantt', 'entry');
+    registry.__resetOpenForTests();
+    expect(registry.list()).toEqual(['plan']);
+  });
+
+  it('reports — never swallows — a duplicate under FirstWins', () => {
+    const onDuplicate = vi.fn();
+    const registry = createContributionRegistry<string>({
+      name: 'overlay',
+      duplicatePolicy: DuplicateContributionPolicy.FirstWins,
+      onDuplicate,
+    });
+    registry.register('k', 'first');
+    registry.register('k', 'second');
+    expect(registry.get('k')).toBe('first');
+    expect(onDuplicate).toHaveBeenCalledWith('k', 'first', 'second');
+  });
+
+  it('refuses FirstWins without a reporter', () => {
+    expect(() =>
+      createContributionRegistry<string>({
+        name: 'overlay',
+        duplicatePolicy: DuplicateContributionPolicy.FirstWins,
+      }),
+    ).toThrow(/onDuplicate/);
+  });
+});
+
+describe('createRenderableContributionRegistry', () => {
+  const registry = createRenderableContributionRegistry<string>({
+    name: 'renderable',
+    reservedKinds: ['plan'],
+  });
+  registry.registerFirstParty<{ label: string }>('plan', {
+    version: 2,
+    validate: (payload) =>
+      typeof payload === 'object' &&
+      payload !== null &&
+      typeof (payload as { label?: unknown }).label === 'string'
+        ? (payload as { label: string })
+        : null,
+    render: (payload) => `plan:${payload.label}`,
+  });
+
+  it('renders a matching envelope', () => {
+    const resolution = registry.resolve({
+      kind: 'plan',
+      version: 1,
+      payload: { label: 'ship it' },
+    });
+    expect(resolution).toEqual({
+      matched: true,
+      kind: 'plan',
+      version: 2,
+      rendered: 'plan:ship it',
+    });
+  });
+
+  it('never throws — it returns a typed reason instead', () => {
+    expect(
+      registry.resolve({ kind: 'nope', version: 1, payload: {} }),
+    ).toMatchObject({
+      matched: false,
+      reason: ContributionFallbackReason.UnknownKind,
+    });
+    expect(
+      registry.resolve({ kind: 'plan', version: 99, payload: {} }),
+    ).toMatchObject({
+      matched: false,
+      reason: ContributionFallbackReason.UnsupportedVersion,
+    });
+    expect(
+      registry.resolve({ kind: 'plan', version: 1, payload: { label: 7 } }),
+    ).toMatchObject({
+      matched: false,
+      reason: ContributionFallbackReason.InvalidPayload,
+    });
+  });
+});

package/src/lib/contribution-registry/contribution-registry.ts

@@ -0,0 +1,202 @@
+/**
+ * `createContributionRegistry` — the ONE two-layer closed+open registry core
+ * the Xema frontend uses everywhere a biome may contribute into a set the
+ * platform also ships a closed first-party version of.
+ *
+ * Before this module the exact same bookkeeping was hand-written four times
+ * (in-chat widgets, biome output renderers, open reply variants, and — next —
+ * Vista surfaces), each with slightly different guards. This is that core,
+ * extracted once (reuse register U1).
+ *
+ * ── The two layers ──────────────────────────────────────────────────────────
+ *   • a CLOSED first-party set, registered at module load and keyed by a
+ *     platform enum value;
+ *   • an OPEN biome set, registered at runtime (a biome registers from its
+ *     `FrontendBiome.init()` hook) and keyed by a namespaced `<biomeId>:<kind>`
+ *     slug.
+ *
+ * ── The invariants (all fail-loud, none silent) ─────────────────────────────
+ *   • RESERVED KINDS. Every first-party kind is reserved: `register()` throws
+ *     if a biome tries to claim one. The open set can never shadow the closed
+ *     one.
+ *   • DUPLICATE GUARD. Registering the EXACT same entry object twice is a
+ *     no-op (this is what tolerates React Fast Refresh / a double-invoked
+ *     `init()`); registering a DIFFERENT entry for a kind that is already
+ *     taken is an error — two biomes cannot silently shadow each other.
+ *   • The one exception is {@link DuplicateContributionPolicy.FirstWins}, for
+ *     registries rebuilt on a hot path where a throw would crash a render
+ *     (the biome output-renderer overlay). It is NOT a silent fallback: an
+ *     `onDuplicate` reporter is REQUIRED, and the registry factory throws at
+ *     construction if it is missing.
+ *
+ * Resolution itself lives in the caller (or in `renderable-registry.ts` for the
+ * versioned + payload-validated flavour) and NEVER throws.
+ */
+
+/** What to do when a DIFFERENT entry is registered for an already-taken kind. */
+export enum DuplicateContributionPolicy {
+  /**
+   * Throw. The default, and correct for every registry whose registrations
+   * happen once at module load or once per biome `init()`.
+   */
+  Throw = 'throw',
+  /**
+   * Keep the first registration and report the loser through `onDuplicate`.
+   * For registries REBUILT on a hot path (e.g. per render) where throwing
+   * would take down the UI. Requires `onDuplicate` — there is no silent mode.
+   */
+  FirstWins = 'first-wins',
+}
+
+/** Options for {@link createContributionRegistry}. */
+export interface ContributionRegistryOptions<TEntry> {
+  /** Registry name, used verbatim in every thrown message. */
+  readonly name: string;
+  /**
+   * The CLOSED first-party kinds. Reserved: `register()` refuses them so a
+   * biome can never shadow a platform kind. Typically `Object.values(SomeEnum)`.
+   */
+  readonly reservedKinds?: Iterable<string>;
+  /** Duplicate handling. Defaults to {@link DuplicateContributionPolicy.Throw}. */
+  readonly duplicatePolicy?: DuplicateContributionPolicy;
+  /**
+   * Reporter for a rejected duplicate under
+   * {@link DuplicateContributionPolicy.FirstWins}. REQUIRED under that policy.
+   */
+  readonly onDuplicate?: (
+    kind: string,
+    existing: TEntry,
+    rejected: TEntry,
+  ) => void;
+}
+
+/** The two-layer registry surface. */
+export interface ContributionRegistry<TEntry> {
+  /** Registry name (diagnostics). */
+  readonly name: string;
+  /**
+   * Register a FIRST-PARTY entry for a closed platform kind. Called once per
+   * kind at module load.
+   */
+  registerFirstParty(kind: string, entry: TEntry): void;
+  /**
+   * OPEN seam: register a biome entry under its namespaced `<biomeId>:<kind>`
+   * slug. Throws when the slug is a reserved first-party kind.
+   */
+  register(kind: string, entry: TEntry): void;
+  /** True when SOME entry (first-party or biome) is registered for the kind. */
+  has(kind: string): boolean;
+  /** The entry for a kind — first-party wins — or `undefined`. */
+  get(kind: string): TEntry | undefined;
+  /** True when the kind belongs to the closed first-party set. */
+  isReserved(kind: string): boolean;
+  /** Every registered kind (sorted) — diagnostics + tests. */
+  list(): readonly string[];
+  /** Only the OPEN (biome-contributed) kinds (sorted). */
+  listOpen(): readonly string[];
+  /** Flattened `kind -> entry` view, first-party wins. Diagnostics + overlays. */
+  entries(): ReadonlyMap<string, TEntry>;
+  /** Test-only: clear the OPEN set (the first-party set stays). */
+  __resetOpenForTests(): void;
+}
+
+export function createContributionRegistry<TEntry>(
+  options: ContributionRegistryOptions<TEntry>,
+): ContributionRegistry<TEntry> {
+  const {
+    name,
+    reservedKinds,
+    duplicatePolicy = DuplicateContributionPolicy.Throw,
+    onDuplicate,
+  } = options;
+
+  if (
+    duplicatePolicy === DuplicateContributionPolicy.FirstWins &&
+    onDuplicate === undefined
+  ) {
+    throw new Error(
+      `${name} registry: DuplicateContributionPolicy.FirstWins requires an ` +
+        `'onDuplicate' reporter — a dropped contribution must never be silent.`,
+    );
+  }
+
+  const reserved = new Set<string>(reservedKinds ?? []);
+  const firstParty = new Map<string, TEntry>();
+  const open = new Map<string, TEntry>();
+
+  /**
+   * Idempotent for the IDENTICAL entry (Fast Refresh / double-invoked
+   * `init()`); an error for a DIFFERENT one. Returns whether the entry landed.
+   */
+  function put(target: Map<string, TEntry>, kind: string, entry: TEntry): void {
+    const existing = target.get(kind);
+    if (existing === undefined) {
+      target.set(kind, entry);
+      return;
+    }
+    if (existing === entry) return;
+    if (duplicatePolicy === DuplicateContributionPolicy.FirstWins) {
+      // `onDuplicate` is guaranteed present under this policy (checked above).
+      (onDuplicate as (k: string, e: TEntry, r: TEntry) => void)(
+        kind,
+        existing,
+        entry,
+      );
+      return;
+    }
+    throw new Error(
+      `${name} registry: a DIFFERENT entry is already registered for kind ` +
+        `'${kind}'. Two contributors cannot claim the same slug.`,
+    );
+  }
+
+  return {
+    name,
+
+    registerFirstParty(kind: string, entry: TEntry): void {
+      put(firstParty, kind, entry);
+    },
+
+    register(kind: string, entry: TEntry): void {
+      if (reserved.has(kind)) {
+        throw new Error(
+          `${name} registry: '${kind}' is a reserved first-party kind and ` +
+            `cannot be overridden by a biome. Use a namespaced ` +
+            `'<biomeId>:${kind}' slug.`,
+        );
+      }
+      put(open, kind, entry);
+    },
+
+    has(kind: string): boolean {
+      return firstParty.has(kind) || open.has(kind);
+    },
+
+    get(kind: string): TEntry | undefined {
+      return firstParty.get(kind) ?? open.get(kind);
+    },
+
+    isReserved(kind: string): boolean {
+      return reserved.has(kind);
+    },
+
+    list(): readonly string[] {
+      return [...firstParty.keys(), ...open.keys()].sort();
+    },
+
+    listOpen(): readonly string[] {
+      return [...open.keys()].sort();
+    },
+
+    entries(): ReadonlyMap<string, TEntry> {
+      // First-party last so it wins on a key present in both (which `register`
+      // already forbids for reserved kinds, but `entries()` must not depend on
+      // that to be correct).
+      return new Map<string, TEntry>([...open, ...firstParty]);
+    },
+
+    __resetOpenForTests(): void {
+      open.clear();
+    },
+  };
+}

package/src/lib/contribution-registry/index.ts

@@ -0,0 +1,9 @@
+/**
+ * The shared two-layer (closed first-party + open biome) contribution registry
+ * core, and its versioned/validated renderable flavour.
+ *
+ * One implementation, four consumers: in-chat ChatWidgets, biome output
+ * renderers, open reply variants, and Vista surfaces.
+ */
+export * from './contribution-registry';
+export * from './renderable-registry';

package/src/lib/contribution-registry/renderable-registry.ts

@@ -0,0 +1,142 @@
+/**
+ * The RENDERABLE flavour of {@link createContributionRegistry}: a two-layer
+ * closed+open registry whose entries are versioned renderers with a narrowing
+ * payload validator, plus the fail-safe resolution every such plane needs.
+ *
+ * This is the shape the in-chat ChatWidget plane and the Vista render plane
+ * both want: an envelope `{ kind, version, payload }` arrives from an agent,
+ * and the frontend must turn it into something drawable WITHOUT ever throwing
+ * and WITHOUT ever silently drawing a coerced half-widget. Resolution returns a
+ * typed reason instead, which the caller renders as a safe fallback card.
+ */
+import {
+  createContributionRegistry,
+  type ContributionRegistry,
+  type ContributionRegistryOptions,
+} from './contribution-registry';
+
+/**
+ * Why an envelope fell back to the safe card. Populated on the resolution so
+ * the Studio debugger (and dev logs) can see WHY — mirrors the Model Resolution
+ * Matrix's `ResolvedModelDecision`. Closed set.
+ */
+export enum ContributionFallbackReason {
+  UnknownKind = 'unknown-kind',
+  InvalidPayload = 'invalid-payload',
+  UnsupportedVersion = 'unsupported-version',
+}
+
+/** The minimum an agent-emitted envelope must carry to be resolvable. */
+export interface ContributionEnvelope {
+  readonly kind: string;
+  readonly version: number;
+  readonly payload: unknown;
+}
+
+/**
+ * A versioned renderer. `validate` narrows the wire payload to the renderer's
+ * own type (returning `null` routes to the fallback with `InvalidPayload`) and
+ * MUST NOT throw; `render` draws from the narrowed payload.
+ */
+export interface RenderableContributionEntry<TRendered, TPayload = unknown> {
+  /** Highest schema version this renderer supports. */
+  readonly version: number;
+  /** Narrowing validator. Returns the typed payload, or `null`. MUST NOT throw. */
+  validate(payload: unknown): TPayload | null;
+  /** Draw from the narrowed payload. */
+  render(payload: TPayload): TRendered;
+}
+
+/** The outcome of resolving an envelope — inspectable for the Studio debugger. */
+export type RenderableResolution<TRendered> =
+  | {
+      readonly matched: true;
+      readonly kind: string;
+      readonly version: number;
+      readonly rendered: TRendered;
+    }
+  | {
+      readonly matched: false;
+      readonly kind: string;
+      readonly reason: ContributionFallbackReason;
+    };
+
+/** A {@link ContributionRegistry} of versioned renderers, plus `resolve`. */
+export interface RenderableContributionRegistry<TRendered>
+  extends Omit<
+    ContributionRegistry<RenderableContributionEntry<TRendered>>,
+    'registerFirstParty' | 'register'
+  > {
+  registerFirstParty<TPayload>(
+    kind: string,
+    entry: RenderableContributionEntry<TRendered, TPayload>,
+  ): void;
+  register<TPayload>(
+    kind: string,
+    entry: RenderableContributionEntry<TRendered, TPayload>,
+  ): void;
+  /**
+   * Resolve an envelope. Pure + deterministic so it can run in render, and it
+   * NEVER throws — an unknown kind, a payload the entry rejects, or a `version`
+   * newer than the entry supports ALL yield `matched: false` with a typed
+   * reason the caller renders as the safe fallback card.
+   */
+  resolve(envelope: ContributionEnvelope): RenderableResolution<TRendered>;
+}
+
+export function createRenderableContributionRegistry<TRendered>(
+  options: ContributionRegistryOptions<RenderableContributionEntry<TRendered>>,
+): RenderableContributionRegistry<TRendered> {
+  const registry =
+    createContributionRegistry<RenderableContributionEntry<TRendered>>(options);
+
+  return {
+    ...registry,
+
+    registerFirstParty<TPayload>(
+      kind: string,
+      entry: RenderableContributionEntry<TRendered, TPayload>,
+    ): void {
+      registry.registerFirstParty(kind, entry);
+    },
+
+    register<TPayload>(
+      kind: string,
+      entry: RenderableContributionEntry<TRendered, TPayload>,
+    ): void {
+      registry.register(kind, entry);
+    },
+
+    resolve(envelope: ContributionEnvelope): RenderableResolution<TRendered> {
+      const entry = registry.get(envelope.kind);
+      if (entry === undefined) {
+        return {
+          matched: false,
+          kind: envelope.kind,
+          reason: ContributionFallbackReason.UnknownKind,
+        };
+      }
+      if (envelope.version > entry.version) {
+        return {
+          matched: false,
+          kind: envelope.kind,
+          reason: ContributionFallbackReason.UnsupportedVersion,
+        };
+      }
+      const narrowed = entry.validate(envelope.payload);
+      if (narrowed === null) {
+        return {
+          matched: false,
+          kind: envelope.kind,
+          reason: ContributionFallbackReason.InvalidPayload,
+        };
+      }
+      return {
+        matched: true,
+        kind: envelope.kind,
+        version: entry.version,
+        rendered: entry.render(narrowed),
+      };
+    },
+  };
+}

package/src/pdf/index.ts

@@ -0,0 +1,11 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// @xemahq/ui-kernel/pdf — canvas-rendered PDF preview surface
+//
+// Split into a DEDICATED subpath (out of the `/ui` barrel) because it pulls in
+// `react-pdf` → `pdfjs-dist` (~1.9 MB). Keeping it here lets `@xemahq/ui-kernel/ui`
+// (and therefore `@xemahq/app-ui`'s AppShell) stay tree-shakeable: a consumer
+// that never renders a PDF never bundles pdf.js. Import from this subpath only
+// when you actually need the viewer.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export { PdfPreview, type PdfPreviewProps } from '../ui/pdf/pdf-preview';

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

@@ -43,10 +43,30 @@ function scalarSchema(field: CaptureFieldSpec): z.ZodTypeAny {
   }
 }
 
+/** True when `value` parses as JSON. Total — never throws. */
+export function isParsableJson(value: string): boolean {
+  try {
+    JSON.parse(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function fieldSchema(field: CaptureFieldSpec): z.ZodTypeAny {
   let base: z.ZodTypeAny;
   if (field.type === CaptureFieldType.Object) {
     base = objectSchema(field.fields ?? []);
+  } else if (field.type === CaptureFieldType.Json) {
+    // A JSON blob is carried as TEXT and validated as parseable. `''` passes
+    // the shape check so an optional blank field stays valid; requiredness is
+    // enforced by the `.min(1)` below, not by the parse rule.
+    const text = field.required
+      ? z.string().min(1, { message: `${field.label} is required` })
+      : z.string();
+    base = text.refine((v) => v === '' || isParsableJson(v), {
+      message: `${field.label} must be valid JSON`,
+    });
   } 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)` });
@@ -58,6 +78,8 @@ function fieldSchema(field: CaptureFieldSpec): z.ZodTypeAny {
       field.required &&
       (field.type === CaptureFieldType.String ||
         field.type === CaptureFieldType.Text ||
+        field.type === CaptureFieldType.Email ||
+        field.type === CaptureFieldType.Url ||
         field.type === CaptureFieldType.User ||
         field.type === CaptureFieldType.Reference ||
         field.type === CaptureFieldType.Datetime ||