@xemahq/ui-kernel 0.9.0 → 0.9.1

package/dist/vista/vista-tools.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import type { VistaTabsController } from './use-vista-tabs';
+export declare enum VistaToolName {
+    Open = "vista_open",
+    Update = "vista_update",
+    Close = "vista_close",
+    List = "vista_list"
+}
+export declare const VistaOpenArgsSchema: z.ZodType<import("@xemahq/kernel-contracts/surface").VistaSurface, unknown, z.core.$ZodTypeInternals<import("@xemahq/kernel-contracts/surface").VistaSurface, unknown>>;
+export type VistaOpenArgs = z.infer<typeof VistaOpenArgsSchema>;
+export declare const VistaUpdateArgsSchema: z.ZodObject<{
+    tabId: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    payload: z.ZodOptional<z.ZodUnknown>;
+    pinned: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type VistaUpdateArgs = z.infer<typeof VistaUpdateArgsSchema>;
+export declare const VistaCloseArgsSchema: z.ZodObject<{
+    tabId: z.ZodString;
+}, z.core.$strip>;
+export type VistaCloseArgs = z.infer<typeof VistaCloseArgsSchema>;
+export declare const VistaListArgsSchema: z.ZodObject<{}, z.core.$strip>;
+export type VistaListArgs = z.infer<typeof VistaListArgsSchema>;
+export declare enum VistaToolError {
+    NoPanel = "no-panel",
+    InvalidArgs = "invalid-args",
+    UnknownTool = "unknown-tool",
+    UnknownTab = "unknown-tab",
+    TabRefused = "tab-refused"
+}
+export type VistaToolResult<TValue = unknown> = {
+    readonly ok: true;
+    readonly value: TValue;
+} | {
+    readonly ok: false;
+    readonly error: VistaToolError;
+    readonly detail?: string;
+};
+export declare const VistaToolResultSchema: z.ZodType<VistaToolResult>;
+export declare function dispatchVistaTool(controller: VistaTabsController | null, tool: string, args: unknown): VistaToolResult;
+//# sourceMappingURL=vista-tools.d.ts.map

package/dist/vista/vista-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vista-tools.d.ts","sourceRoot":"","sources":["../../src/vista/vista-tools.ts"],"names":[],"mappings":"AAkCA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAqB,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAG/E,oBAAY,aAAa;IACvB,IAAI,eAAe;IACnB,MAAM,iBAAiB;IACvB,KAAK,gBAAgB;IACrB,IAAI,eAAe;CACpB;AAUD,eAAO,MAAM,mBAAmB,yKAAqB,CAAC;AACtD,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAWhE,eAAO,MAAM,qBAAqB;;;;;iBAKhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAGpE,eAAO,MAAM,oBAAoB;;iBAAyC,CAAC;AAC3E,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAGlE,eAAO,MAAM,mBAAmB,gCAAe,CAAC;AAChD,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAGhE,oBAAY,cAAc;IAExB,OAAO,aAAa;IAEpB,WAAW,iBAAiB;IAE5B,WAAW,iBAAiB;IAE5B,UAAU,gBAAgB;IAM1B,UAAU,gBAAgB;CAC3B;AAGD,MAAM,MAAM,eAAe,CAAC,MAAM,GAAG,OAAO,IACxC;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC7C;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAQN,eAAO,MAAM,qBAAqB,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAO7B,CAAC;AAWjC,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,mBAAmB,GAAG,IAAI,EACtC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,eAAe,CAsDjB"}

package/dist/vista/vista-tools.js

@@ -0,0 +1,113 @@
+import { VistaSurfaceSchema } from '@xemahq/kernel-contracts/surface';
+import { z } from 'zod';
+export var VistaToolName;
+(function (VistaToolName) {
+    VistaToolName["Open"] = "vista_open";
+    VistaToolName["Update"] = "vista_update";
+    VistaToolName["Close"] = "vista_close";
+    VistaToolName["List"] = "vista_list";
+})(VistaToolName || (VistaToolName = {}));
+export const VistaOpenArgsSchema = VistaSurfaceSchema;
+export const VistaUpdateArgsSchema = z.object({
+    tabId: z.string().min(1),
+    title: z.string().min(1).optional(),
+    payload: z.unknown().optional(),
+    pinned: z.boolean().optional(),
+});
+export const VistaCloseArgsSchema = z.object({ tabId: z.string().min(1) });
+export const VistaListArgsSchema = z.object({});
+export var VistaToolError;
+(function (VistaToolError) {
+    VistaToolError["NoPanel"] = "no-panel";
+    VistaToolError["InvalidArgs"] = "invalid-args";
+    VistaToolError["UnknownTool"] = "unknown-tool";
+    VistaToolError["UnknownTab"] = "unknown-tab";
+    VistaToolError["TabRefused"] = "tab-refused";
+})(VistaToolError || (VistaToolError = {}));
+export const VistaToolResultSchema = z.union([
+    z.object({ ok: z.literal(true), value: z.unknown() }),
+    z.object({
+        ok: z.literal(false),
+        error: z.nativeEnum(VistaToolError),
+        detail: z.string().optional(),
+    }),
+]);
+export function dispatchVistaTool(controller, tool, args) {
+    if (controller === null) {
+        return { ok: false, error: VistaToolError.NoPanel };
+    }
+    switch (tool) {
+        case VistaToolName.Open: {
+            const parsed = VistaOpenArgsSchema.safeParse(args);
+            if (!parsed.success)
+                return invalid(parsed.error);
+            return { ok: true, value: { tabId: controller.open(parsed.data) } };
+        }
+        case VistaToolName.Update: {
+            const parsed = VistaUpdateArgsSchema.safeParse(args);
+            if (!parsed.success)
+                return invalid(parsed.error);
+            const { tabId, ...patch } = parsed.data;
+            const refusal = refusalFor(controller, tabId);
+            if (refusal !== null)
+                return refusal;
+            if (!controller.update(tabId, patch)) {
+                return {
+                    ok: false,
+                    error: VistaToolError.TabRefused,
+                    detail: `Tab "${tabId}" is host-owned; its content is driven by the host, not by vista_update.`,
+                };
+            }
+            return { ok: true, value: { updated: true } };
+        }
+        case VistaToolName.Close: {
+            const parsed = VistaCloseArgsSchema.safeParse(args);
+            if (!parsed.success)
+                return invalid(parsed.error);
+            const { tabId } = parsed.data;
+            const refusal = refusalFor(controller, tabId);
+            if (refusal !== null)
+                return refusal;
+            if (!controller.close(tabId)) {
+                return {
+                    ok: false,
+                    error: VistaToolError.TabRefused,
+                    detail: `Tab "${tabId}" is pinned and cannot be closed.`,
+                };
+            }
+            return { ok: true, value: { closed: true } };
+        }
+        case VistaToolName.List: {
+            const parsed = VistaListArgsSchema.safeParse(args ?? {});
+            if (!parsed.success)
+                return invalid(parsed.error);
+            return { ok: true, value: { tabs: controller.list() } };
+        }
+        default:
+            return {
+                ok: false,
+                error: VistaToolError.UnknownTool,
+                detail: `'${tool}' is not a Vista tool.`,
+            };
+    }
+}
+function refusalFor(controller, tabId) {
+    if (controller.list().some((tab) => tab.tabId === tabId)) {
+        return null;
+    }
+    return {
+        ok: false,
+        error: VistaToolError.UnknownTab,
+        detail: `No tab "${tabId}" is open.`,
+    };
+}
+function invalid(error) {
+    return {
+        ok: false,
+        error: VistaToolError.InvalidArgs,
+        detail: error.issues
+            .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+            .join('; '),
+    };
+}
+//# sourceMappingURL=vista-tools.js.map

package/dist/vista/vista-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vista-tools.js","sourceRoot":"","sources":["../../src/vista/vista-tools.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/ui-kernel",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "type": "module",
   "sideEffects": false,
   "description": "Host-framework-agnostic UI kernel for the Xema OS. Defines the SystemBus orchestration contract (capability.invoke, cross-biome intents, command palette, xema:// deeplinks, window manager) AND the biome-host contract surface (FrontendBiome/FrontendBiomeFactory, HostBridge, the singleton biomeRegistry, session contributions) that every frontend biome composes against. No Vite, Next.js, or React-Router — React itself IS allowed as the shared component model (the contracts traffic in ReactNode/ComponentType and a React context). Concrete host adapters (router/auth/toast wiring) live in separate packages that consume this kernel. The SystemBus is pure orchestration: it never authorizes, the backend capability-router enforces all policy.",
@@ -63,7 +63,7 @@
   "peerDependencies": {
     "@tanstack/react-query": "^5.0.0",
     "react": "^18.3.1",
-    "@xemahq/kernel-contracts": ">=0.13.0"
+    "@xemahq/kernel-contracts": ">=0.55.0"
   },
   "peerDependenciesMeta": {
     "@tanstack/react-query": {
@@ -77,7 +77,7 @@
     "prettier": "3.6.2",
     "react": "^18.3.1",
     "typescript": "5.9.3",
-    "@xemahq/kernel-contracts": "^0.48.0"
+    "@xemahq/kernel-contracts": "^0.58.0"
   },
   "exports": {
     ".": {

package/src/index.ts

@@ -2,6 +2,11 @@ export * from './lib/system-bus';
 export * from './lib/biome-host';
 export * from './lib/capabilities';
 
+// The shared closed-first-party + open-biome contribution registry core (and
+// its versioned/validated renderable flavour). Every plane that lets a biome
+// contribute into a set the platform also ships builtins for is built on this.
+export * from './lib/contribution-registry';
+
 // Guided-capture UX kit (B5). Also available at the `@xemahq/ui-kernel/ui`
 // subpath alongside the rest of the shared UI surface; re-exported here so the
 // capture primitives are reachable from the package root too.

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';