@xemahq/ui-kernel 0.9.0 → 0.9.2

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,
@@ -81,7 +86,6 @@ class FrontendBiomeRegistry extends Registry<string, FrontendBiome & { key: stri
         // because the biome is being torn down anyway.
         void Promise.resolve(entry.dispose()).catch((error: unknown) => {
           // Surface for devtools without crashing the unregister flow.
-          // eslint-disable-next-line no-console
           console.error(`[xema-ui-kernel] dispose() failed for '${id}':`, error);
         });
       }
@@ -153,23 +157,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/biome-host/biome-scope-hooks.ts

@@ -0,0 +1,39 @@
+import { useHostBridge } from './host-bridge';
+
+export interface ProjectScope {
+  readonly orgId: string | null;
+  readonly projectId: string | null;
+}
+
+export interface RequiredProjectScope {
+  readonly orgId: string;
+  readonly projectId: string;
+}
+
+function normalize(value: string | null | undefined): string | null {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+export function useProjectScope(): ProjectScope {
+  const bridge = useHostBridge();
+  const params = bridge.navigation.useRouteParams<{ projectId?: string }>();
+  const orgId = normalize(bridge.auth.getOrgId());
+  const projectId =
+    normalize(params.projectId) ?? normalize(bridge.auth.getProjectId());
+  return { orgId, projectId };
+}
+
+export function useRequiredScope(): RequiredProjectScope {
+  const { orgId, projectId } = useProjectScope();
+  if (!orgId || !projectId) {
+    throw new Error(
+      `[xema-ui-kernel] useRequiredScope() requires both orgId and projectId, ` +
+        `got orgId=${orgId ?? 'null'} projectId=${projectId ?? 'null'}. ` +
+        `Render this component under <ScopeGuard> or use useProjectScope() for ` +
+        `org-scoped surfaces.`,
+    );
+  }
+  return { orgId, projectId };
+}

package/src/lib/biome-host/biome-scope.tsx

@@ -13,74 +13,7 @@
  */
 import { Fragment, type ReactElement, type ReactNode } from 'react';
 
-import { useHostBridge } from './host-bridge';
-
-/**
- * Normalized active scope. Both fields are `null` when absent (never
- * `undefined` and never empty-string) so consumers branch on a single shape.
- */
-export interface ProjectScope {
-  readonly orgId: string | null;
-  readonly projectId: string | null;
-}
-
-/**
- * Like {@link ProjectScope} but with both fields guaranteed present — the
- * resolved shape {@link useRequiredScope} and {@link ScopeGuard} hand to
- * consumers once the scope is known to be complete.
- */
-export interface RequiredProjectScope {
-  readonly orgId: string;
-  readonly projectId: string;
-}
-
-/** Collapse `undefined` / `''` to `null`; trim incidental whitespace. */
-function normalize(value: string | null | undefined): string | null {
-  if (typeof value !== 'string') return null;
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : null;
-}
-
-/**
- * The active `{ orgId, projectId }` for the current biome render.
- *
- * - `orgId` comes from the host (`bridge.auth.getOrgId()`) — the org is owned
- *   by the host shell, never carried in a biome URL.
- * - `projectId` is read from the matcher-bound route params
- *   (`bridge.navigation.useRouteParams().projectId`, set on project-scoped
- *   routes) and falls back to `bridge.auth.getProjectId()` for org-scoped
- *   surfaces that still have an active project selection.
- *
- * Both values are null-normalized. This is the single sanctioned scope read —
- * biomes MUST NOT re-derive org/project from JWT claims or ad-hoc params.
- */
-export function useProjectScope(): ProjectScope {
-  const bridge = useHostBridge();
-  const params = bridge.navigation.useRouteParams<{ projectId?: string }>();
-  const orgId = normalize(bridge.auth.getOrgId());
-  const projectId = normalize(params.projectId) ?? normalize(bridge.auth.getProjectId());
-  return { orgId, projectId };
-}
-
-/**
- * Like {@link useProjectScope} but fail-fast: throws if either `orgId` or
- * `projectId` is absent. Use it in project-scoped components that cannot
- * render without both — wrap them in {@link ScopeGuard} to render a fallback
- * instead of throwing. Returns the {@link RequiredProjectScope} narrowed
- * shape so callers skip null checks.
- */
-export function useRequiredScope(): RequiredProjectScope {
-  const { orgId, projectId } = useProjectScope();
-  if (!orgId || !projectId) {
-    throw new Error(
-      `[xema-ui-kernel] useRequiredScope() requires both orgId and projectId, ` +
-        `got orgId=${orgId ?? 'null'} projectId=${projectId ?? 'null'}. ` +
-        `Render this component under <ScopeGuard> or use useProjectScope() for ` +
-        `org-scoped surfaces.`,
-    );
-  }
-  return { orgId, projectId };
-}
+import { useProjectScope, type ProjectScope } from './biome-scope-hooks';
 
 export interface ScopeGuardProps {
   /**

package/src/lib/biome-host/biome-scoped-query.ts

@@ -18,7 +18,10 @@ import {
   type UseQueryResult,
 } from '@tanstack/react-query';
 
-import { useProjectScope, type ProjectScope } from './biome-scope';
+import {
+  useProjectScope,
+  type ProjectScope,
+} from './biome-scope-hooks';
 
 /**
  * The canonical Xema-platform tenant header. Every platform biome-api reads it

package/src/lib/biome-host/create-biome-orval-config.ts

@@ -66,7 +66,7 @@ export function createBiomeOrvalConfig(
     baseUrl: opts.baseUrl,
     maxRetries: opts.maxRetries ?? 1,
     getAuthToken: () => bridge.auth.ensureFreshToken(),
-    getHeaders: async () => {
+    getHeaders: () => {
       const headers: Record<string, string> = {
         'X-Correlation-Id': crypto.randomUUID(),
       };
@@ -75,7 +75,7 @@ export function createBiomeOrvalConfig(
         // Canonical header read by every Xema-platform service's RequestContext.
         headers['X-Xema-Org-Id'] = orgId;
       }
-      return headers;
+      return Promise.resolve(headers);
     },
     onUnauthorized: () => bridge.auth.onUnauthorized(),
   };

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

@@ -166,7 +166,7 @@ function getOrvalClientErrorMessage(error: OrvalClientErrorLike, fallback: strin
     const payload: WorkflowErrorEnvelope = (() => {
       const message = record['message'];
       if (message && typeof message === 'object') {
-        return message as WorkflowErrorEnvelope;
+        return message;
       }
       return {
         code: typeof record['code'] === 'string' ? record['code'] : undefined,

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

@@ -16,6 +16,7 @@ export * from './frontend-biome';
 export * from './host-bridge';
 export * from './biome-navigation';
 export * from './biome-scope';
+export * from './biome-scope-hooks';
 export * from './biome-scoped-query';
 export * from './biome-builders';
 export * from './define-web-biome';
@@ -31,6 +32,5 @@ export * from './realtime-hooks';
 export * from './i18n-port';
 export * from './i18n-hooks';
 export * from './errors';
-export * from './response-envelope';
 export * from './use-mutation-with-error-toast';
 export * from './use-page-state';

package/src/lib/biome-host/session-profiles.ts

@@ -89,7 +89,13 @@ export function useSessionProfileDescriptor(
     for (const biome of biomeRegistry.list()) {
       for (const profile of biome.session?.profiles ?? []) {
         if (profile.key !== profileKey) continue;
-        if (biomeId != null && profile.biomeId === biomeId) return profile;
+        if (
+          biomeId !== null &&
+          biomeId !== undefined &&
+          profile.biomeId === biomeId
+        ) {
+          return profile;
+        }
         crossPluginMatch ??= profile;
       }
     }

package/src/lib/capabilities/capability-context.ts

@@ -0,0 +1,25 @@
+import { createContext, useContext } from 'react';
+
+import type { MeCapabilitiesSnapshot } from './types';
+
+export interface CapabilityContextValue {
+  readonly snapshot: MeCapabilitiesSnapshot | undefined;
+  readonly isLoading: boolean;
+  readonly error: unknown;
+}
+
+export const CapabilityContext =
+  createContext<CapabilityContextValue | null>(null);
+CapabilityContext.displayName = 'CapabilityContext';
+
+export function useCapabilityContext(): CapabilityContextValue {
+  const ctx = useContext(CapabilityContext);
+  if (!ctx) {
+    throw new Error(
+      '[xema-ui-kernel] useCapability()/useCapabilities() called outside ' +
+        '<CapabilityProvider>. The host (or biome shell) must mount the ' +
+        'capability provider above any capability-gated subtree.',
+    );
+  }
+  return ctx;
+}

package/src/lib/capabilities/capability-provider.tsx

@@ -1,26 +1,14 @@
 import { useQuery } from '@tanstack/react-query';
-import { createContext, useContext, type ReactNode } from 'react';
+import type { ReactNode } from 'react';
 
 import { useHostBridge } from '../biome-host/host-bridge';
+import {
+  CapabilityContext,
+  type CapabilityContextValue,
+} from './capability-context';
 
 import type { CapabilityPort, MeCapabilitiesSnapshot } from './types';
 
-/**
- * The value exposed by {@link CapabilityProvider} through React context.
- * `snapshot` is `undefined` until the first successful fetch; `isLoading`
- * and `error` let callers distinguish "still unknown" and "fetch failed"
- * from "explicitly denied" — the gate hook must NOT treat an errored fetch
- * as "no capabilities".
- */
-export interface CapabilityContextValue {
-  readonly snapshot: MeCapabilitiesSnapshot | undefined;
-  readonly isLoading: boolean;
-  readonly error: unknown;
-}
-
-const CapabilityContext = createContext<CapabilityContextValue | null>(null);
-CapabilityContext.displayName = 'CapabilityContext';
-
 /**
  * Stable query-key root for the capability snapshot. Folded with the active
  * org so each org caches independently and a re-fetch fires when the org
@@ -76,20 +64,3 @@ export function CapabilityProvider(props: CapabilityProviderProps): JSX.Element
 
   return <CapabilityContext.Provider value={value}>{props.children}</CapabilityContext.Provider>;
 }
-
-/**
- * Internal accessor for the capability context. Throws fail-fast if used
- * outside {@link CapabilityProvider} — a missing provider is a wiring bug,
- * not a "deny everything" condition.
- */
-export function useCapabilityContext(): CapabilityContextValue {
-  const ctx = useContext(CapabilityContext);
-  if (!ctx) {
-    throw new Error(
-      '[xema-ui-kernel] useCapability()/useCapabilities() called outside ' +
-        '<CapabilityProvider>. The host (or biome shell) must mount the ' +
-        'capability provider above any capability-gated subtree.',
-    );
-  }
-  return ctx;
-}

package/src/lib/capabilities/index.ts

@@ -12,5 +12,6 @@
  *   import { CapabilityProvider, useCapability } from '@xemahq/ui-kernel';
  */
 export * from './types';
+export * from './capability-context';
 export * from './capability-provider';
 export * from './use-capability';

package/src/lib/capabilities/use-capability.ts

@@ -1,6 +1,9 @@
 import type { ExecutionEnvironmentKind } from '@xemahq/kernel-contracts/execution-environment';
 
-import { useCapabilityContext, type CapabilityContextValue } from './capability-provider';
+import {
+  useCapabilityContext,
+  type CapabilityContextValue,
+} from './capability-context';
 import type { MeCapabilitiesSnapshot } from './types';
 
 export interface UseCapabilityOptions {

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