@xemahq/ui-kernel 0.9.1 → 0.10.0

package/src/lib/system-bus/host-ports.ts

@@ -3,6 +3,7 @@ import type {
   CapabilityInvokeMeta,
   CapabilityInvokeResult,
 } from './capability-invoke';
+import type { ParsedDeeplink } from './deeplink';
 import type { PaletteEntry, PaletteQuery } from './palette';
 import type {
   OpenWindowRequest,
@@ -92,5 +93,5 @@ export interface WindowManager {
  * window) — fail-fast, never a silent no-op.
  */
 export interface DeeplinkResolver {
-  resolve(target: import('./deeplink').ParsedDeeplink): Promise<void>;
+  resolve(target: ParsedDeeplink): Promise<void>;
 }

package/src/lib/system-bus/intent-registry.ts

@@ -5,7 +5,6 @@ import {
 } from '@xemahq/kernel-contracts/object';
 import { ActionRefKind } from './enums';
 import type {
-  ActionRef,
   IntentBus,
   IntentRegistration,
   ResolvedIntent,
@@ -24,7 +23,7 @@ function assertValidRegistration(registration: IntentRegistration): void {
     if (!VALID_ACTION_KINDS.has(action.kind)) {
       throw new Error(
         `[xema-ui-kernel] IntentRegistration from "${registration.biomeId}" ` +
-          `has an ActionRef with unknown kind "${(action as ActionRef).kind}". ` +
+          `has an ActionRef with unknown kind "${action.kind}". ` +
           `Expected one of: ${[...VALID_ACTION_KINDS].join(', ')}.`,
       );
     }

package/src/offline/index.ts

@@ -41,11 +41,13 @@ export {
 } from './mutation';
 export {
   OutboxProvider,
+  type OutboxProviderProps,
+} from './react';
+export {
   useOutbox,
   useOutboxSnapshot,
   useOnlineStatus,
-  type OutboxProviderProps,
-} from './react';
+} from './react-hooks';
 export {
   OfflineStatusBadge,
   type OfflineStatusBadgeProps,

package/src/offline/offline-status-badge.tsx

@@ -1,4 +1,4 @@
-import { useOutboxSnapshot } from './react';
+import { useOutboxSnapshot } from './react-hooks';
 
 import type { Outbox } from './outbox';
 

package/src/offline/outbox.test.ts

@@ -25,7 +25,7 @@ function makeOutbox(overrides: Partial<OutboxOptions> = {}): {
 describe('Outbox', () => {
   it('queues while offline and delivers on reconnect', async () => {
     const { outbox, online } = makeOutbox();
-    const send = vi.fn(async () => {});
+    const send = vi.fn(() => Promise.resolve());
     outbox.registerExecutor(KIND, send);
 
     online.reportOffline();
@@ -42,8 +42,9 @@ describe('Outbox', () => {
   it('delivers immediately when online and removes the entry; idempotency key is stable', async () => {
     const { outbox } = makeOutbox();
     const keys: string[] = [];
-    outbox.registerExecutor(KIND, async (_p, ctx: OutboxExecuteContext) => {
+    outbox.registerExecutor(KIND, (_p, ctx: OutboxExecuteContext) => {
       keys.push(ctx.idempotencyKey);
+      return Promise.resolve();
     });
     await outbox.enqueue(KIND, { a: 1 });
     await outbox.drain();
@@ -55,11 +56,12 @@ describe('Outbox', () => {
   it('retries a 5xx and eventually succeeds', async () => {
     const { outbox } = makeOutbox();
     let calls = 0;
-    outbox.registerExecutor(KIND, async () => {
+    outbox.registerExecutor(KIND, () => {
       calls += 1;
       if (calls < 3) {
-        throw { status: 503, message: 'unavailable' };
+        return Promise.reject({ status: 503, message: 'unavailable' });
       }
+      return Promise.resolve();
     });
     await outbox.enqueue(KIND, { a: 1 });
     await outbox.drain();
@@ -69,29 +71,29 @@ describe('Outbox', () => {
 
   it('dead-letters a 4xx immediately (no pointless retries)', async () => {
     const { outbox } = makeOutbox();
-    const send = vi.fn(async () => {
-      throw { status: 400, message: 'bad request' };
-    });
+    const send = vi.fn(() =>
+      Promise.reject({ status: 400, message: 'bad request' }),
+    );
     outbox.registerExecutor(KIND, send);
     await outbox.enqueue(KIND, { a: 1 });
     await outbox.drain();
     expect(send).toHaveBeenCalledTimes(1);
     const snap = outbox.getSnapshot();
     expect(snap.failedCount).toBe(1);
-    expect(snap.entries[0]!.status).toBe(OutboxEntryStatus.Failed);
+    expect(snap.entries[0].status).toBe(OutboxEntryStatus.Failed);
   });
 
   it('dead-letters after exhausting retries on persistent 5xx', async () => {
     const { outbox } = makeOutbox({ maxAttempts: 3 });
     let calls = 0;
-    outbox.registerExecutor(KIND, async () => {
+    outbox.registerExecutor(KIND, () => {
       calls += 1;
-      throw { status: 503 };
+      return Promise.reject({ status: 503 });
     });
     await outbox.enqueue(KIND, { a: 1 });
     await outbox.drain();
     expect(calls).toBe(3);
-    expect(outbox.getSnapshot().entries[0]!.status).toBe(OutboxEntryStatus.Failed);
+    expect(outbox.getSnapshot().entries[0].status).toBe(OutboxEntryStatus.Failed);
   });
 
   it('a network failure never advances the attempt counter or dead-letters', async () => {
@@ -99,15 +101,19 @@ describe('Outbox', () => {
     const timers: Array<() => void> = [];
     const { outbox } = makeOutbox({ scheduler: (fn) => void timers.push(fn) });
     let succeed = false;
-    outbox.registerExecutor(KIND, async () => {
+    outbox.registerExecutor(KIND, () => {
       if (!succeed) {
-        throw { name: 'TypeError', message: 'Failed to fetch' };
+        return Promise.reject({
+          name: 'TypeError',
+          message: 'Failed to fetch',
+        });
       }
+      return Promise.resolve();
     });
 
     await outbox.enqueue(KIND, { a: 1 });
     await outbox.drain();
-    const parked = outbox.getSnapshot().entries[0]!;
+    const parked = outbox.getSnapshot().entries[0];
     expect(parked.status).toBe(OutboxEntryStatus.Pending);
     expect(parked.attempts).toBe(0); // offline is not the payload's fault
     expect(outbox.getSnapshot().failedCount).toBe(0);
@@ -121,8 +127,9 @@ describe('Outbox', () => {
   it('delivers queued entries in FIFO order', async () => {
     const { outbox, online } = makeOutbox();
     const order: number[] = [];
-    outbox.registerExecutor(KIND, async (p: { n: number }) => {
+    outbox.registerExecutor(KIND, (p: { n: number }) => {
       order.push(p.n);
+      return Promise.resolve();
     });
     online.reportOffline();
     await outbox.enqueue(KIND, { n: 1 });
@@ -150,7 +157,7 @@ describe('Outbox', () => {
     online.reportOffline(); // keep it queued so we can observe the recovery
     const outbox = new Outbox({ storage, online, scheduler: (fn) => fn() });
     await outbox.start();
-    expect(outbox.getSnapshot().entries[0]!.status).toBe(OutboxEntryStatus.Pending);
+    expect(outbox.getSnapshot().entries[0].status).toBe(OutboxEntryStatus.Pending);
     outbox.stop();
   });
 });

package/src/offline/outbox.ts

@@ -159,7 +159,7 @@ export class Outbox {
       updatedAt: ts,
       ...(opts.label !== undefined ? { label: opts.label } : {}),
     };
-    await this.storage.put(entry as OutboxEntry);
+    await this.storage.put(entry);
     await this.refresh();
     void this.drain();
     return entry;

package/src/offline/react-hooks.ts

@@ -0,0 +1,37 @@
+import { createContext, useContext, useSyncExternalStore } from 'react';
+
+import { Outbox } from './outbox';
+
+import type { OutboxSnapshot } from './types';
+
+export const OutboxContext = createContext<Outbox | null>(null);
+
+export function useOutbox(): Outbox {
+  const ctx = useContext(OutboxContext);
+  if (!ctx) {
+    throw new Error('useOutbox must be used within an <OutboxProvider>.');
+  }
+  return ctx;
+}
+
+function resolveOutbox(explicit: Outbox | undefined, ctx: Outbox | null): Outbox {
+  const instance = explicit ?? ctx;
+  if (!instance) {
+    throw new Error('An <OutboxProvider> or an explicit outbox is required.');
+  }
+  return instance;
+}
+
+export function useOutboxSnapshot(outbox?: Outbox): OutboxSnapshot {
+  const ctx = useContext(OutboxContext);
+  const instance = resolveOutbox(outbox, ctx);
+  return useSyncExternalStore(
+    (cb) => instance.subscribe(cb),
+    () => instance.getSnapshot(),
+    () => instance.getSnapshot(),
+  );
+}
+
+export function useOnlineStatus(outbox?: Outbox): boolean {
+  return useOutboxSnapshot(outbox).online;
+}

package/src/offline/react.tsx

@@ -1,18 +1,12 @@
 import {
-  createContext,
-  useContext,
   useEffect,
   useMemo,
   useRef,
-  useSyncExternalStore,
   type ReactNode,
 } from 'react';
 
 import { Outbox, type OutboxOptions } from './outbox';
-
-import type { OutboxSnapshot } from './types';
-
-const OutboxContext = createContext<Outbox | null>(null);
+import { OutboxContext } from './react-hooks';
 
 export interface OutboxProviderProps {
   /** Bring your own Outbox, or let the provider create one from `options`. */
@@ -36,36 +30,3 @@ export function OutboxProvider({ outbox, options, children }: OutboxProviderProp
 
   return <OutboxContext.Provider value={instance}>{children}</OutboxContext.Provider>;
 }
-
-export function useOutbox(): Outbox {
-  const ctx = useContext(OutboxContext);
-  if (!ctx) {
-    throw new Error('useOutbox must be used within an <OutboxProvider>.');
-  }
-  return ctx;
-}
-
-function resolveOutbox(explicit: Outbox | undefined, ctx: Outbox | null): Outbox {
-  const instance = explicit ?? ctx;
-  if (!instance) {
-    throw new Error('An <OutboxProvider> or an explicit outbox is required.');
-  }
-  return instance;
-}
-
-/** Subscribe to the outbox state (offline badge, pending count, dead-letter
- *  list). Re-renders only when the snapshot changes. */
-export function useOutboxSnapshot(outbox?: Outbox): OutboxSnapshot {
-  const ctx = useContext(OutboxContext);
-  const instance = resolveOutbox(outbox, ctx);
-  return useSyncExternalStore(
-    (cb) => instance.subscribe(cb),
-    () => instance.getSnapshot(),
-    () => instance.getSnapshot(),
-  );
-}
-
-/** Current connectivity as tracked by the outbox. */
-export function useOnlineStatus(outbox?: Outbox): boolean {
-  return useOutboxSnapshot(outbox).online;
-}

package/src/offline/storage.ts

@@ -4,20 +4,25 @@ import type { OutboxEntry, OutboxStorage } from './types';
 export class InMemoryOutboxStorage implements OutboxStorage {
   private readonly map = new Map<string, OutboxEntry>();
 
-  async getAll(): Promise<OutboxEntry[]> {
-    return [...this.map.values()].sort((a, b) => a.createdAt - b.createdAt);
+  getAll(): Promise<OutboxEntry[]> {
+    return Promise.resolve(
+      [...this.map.values()].sort((a, b) => a.createdAt - b.createdAt),
+    );
   }
 
-  async put(entry: OutboxEntry): Promise<void> {
+  put(entry: OutboxEntry): Promise<void> {
     this.map.set(entry.id, { ...entry });
+    return Promise.resolve();
   }
 
-  async delete(id: string): Promise<void> {
+  delete(id: string): Promise<void> {
     this.map.delete(id);
+    return Promise.resolve();
   }
 
-  async clear(): Promise<void> {
+  clear(): Promise<void> {
     this.map.clear();
+    return Promise.resolve();
   }
 }
 
@@ -69,7 +74,7 @@ export class IndexedDbOutboxStorage implements OutboxStorage {
       transaction.onabort = () =>
         reject(transaction.error ?? new Error('indexedDB tx aborted'));
       transaction.oncomplete = () =>
-        resolve(request ? (request as IDBRequest<T>).result : undefined);
+        resolve(request ? request.result : undefined);
       transaction.onerror = () =>
         reject(transaction.error ?? new Error('indexedDB tx error'));
     });

package/src/registry/index.ts

@@ -4,5 +4,6 @@ export * from './lib/biome-slot';
 export * from './lib/biomes-enabled-context';
 export * from './lib/session-selectors';
 export * from './lib/session-context-builder';
+export * from './lib/session-context';
 export * from './lib/session-context-provider';
 export * from './lib/primitives';

package/src/registry/lib/primitives/SessionEventCard.tsx

@@ -125,13 +125,15 @@ export function SessionEventCard({
           <span style={{ color: 'hsl(var(--ink, 228 14% 11%))', wordBreak: 'break-word' }}>
             {title}
           </span>
-          {detail != null && (
+          {detail !== null && detail !== undefined && (
             <span style={{ color: 'hsl(var(--ink-3, 228 6% 40%))', wordBreak: 'break-word' }}>
               {detail}
             </span>
           )}
         </div>
-        {children != null && <div style={{ marginTop: 4 }}>{children}</div>}
+        {children !== null && children !== undefined && (
+          <div style={{ marginTop: 4 }}>{children}</div>
+        )}
       </div>
     </div>
   );

package/src/registry/lib/session-context-builder.ts

@@ -2,11 +2,9 @@
  * Single helper hook the host's session shell calls once per render to
  * build the `SessionContext` it passes into every contribution selector.
  *
- * Inputs are the loose, host-shaped session fields (any DTO with these
- * keys); the helper resolves the profile descriptor through the biome
- * registry, frozes a capabilities set, and returns a stable
- * `SessionContext`. Memoised by the underlying selectors — callers can
- * pass the result as a dep without worrying about identity churn.
+ * Inputs are the host's session fields plus the resolved Agent projection.
+ * The helper freezes capability refs and returns a stable `SessionContext`.
+ * It never fabricates a profile or capability fallback.
  *
  * Keeping this helper in the SDK (rather than the host) is what lets
  * biomes also build a context — e.g. from inside a slash command
@@ -14,17 +12,23 @@
  */
 import { useMemo } from 'react';
 
-import {
-  type SessionContext,
-  useSessionProfileDescriptor,
-} from '../../index';
+import type { SessionContext } from '../../index';
+
+export interface SessionResolvedAgentInput {
+  readonly ref: string;
+  readonly requiredCapabilities: readonly string[];
+  readonly mayEditRepositories: boolean;
+  readonly mayWriteKnowledgeBase: boolean;
+  readonly hasOutputSurface: boolean;
+}
 
 export interface BuildSessionContextInput {
   readonly sessionId: string;
   readonly orgId: string;
   readonly projectId: string;
   readonly biomeId?: string;
-  readonly profileKey?: string;
+  readonly repositoryId?: string;
+  readonly agent?: SessionResolvedAgentInput;
   readonly status: string;
   readonly isActive: boolean;
 }
@@ -41,17 +45,29 @@ export function isStatusActive(status: string): boolean {
   return !TERMINAL_STATUSES.has(status);
 }
 
-export function useSessionContext(input: BuildSessionContextInput): SessionContext {
-  const descriptor = useSessionProfileDescriptor(input.biomeId, input.profileKey);
+export function useSessionContext(
+  input: BuildSessionContextInput,
+): SessionContext {
   return useMemo<SessionContext>(
     () => ({
       sessionId: input.sessionId,
       orgId: input.orgId,
       projectId: input.projectId,
-      biomeId: input.biomeId ?? descriptor.biomeId,
-      profileKey: input.profileKey ?? descriptor.key,
+      ...(input.biomeId !== undefined ? { biomeId: input.biomeId } : {}),
+      ...(input.repositoryId !== undefined
+        ? { repositoryId: input.repositoryId }
+        : {}),
+      ...(input.agent !== undefined
+        ? {
+            agent: {
+              ...input.agent,
+              requiredCapabilities: Object.freeze(
+                new Set(input.agent.requiredCapabilities),
+              ),
+            },
+          }
+        : {}),
       status: input.status,
-      capabilities: Object.freeze(new Set(descriptor.capabilities)),
       isActive: input.isActive,
     }),
     [
@@ -59,10 +75,10 @@ export function useSessionContext(input: BuildSessionContextInput): SessionConte
       input.orgId,
       input.projectId,
       input.biomeId,
-      input.profileKey,
+      input.repositoryId,
+      input.agent,
       input.status,
       input.isActive,
-      descriptor,
     ],
   );
 }

package/src/registry/lib/session-context-provider.tsx

@@ -10,12 +10,11 @@
  * stable, importable hook — `import { useCurrentSessionContext } from
  * '@xemahq/ui-kernel/registry'`.
  */
-import { type ReactNode, type ReactElement, createContext, useContext } from 'react';
+import type { ReactElement, ReactNode } from 'react';
 
-import type { SessionContext } from '../../index';
+import { SessionContextValue } from './session-context';
 
-const Ctx = createContext<SessionContext | null>(null);
-Ctx.displayName = 'SessionContext';
+import type { SessionContext } from '../../index';
 
 export interface SessionContextProviderProps {
   readonly value: SessionContext;
@@ -26,25 +25,9 @@ export function SessionContextProvider({
   value,
   children,
 }: SessionContextProviderProps): ReactElement {
-  return <Ctx.Provider value={value}>{children}</Ctx.Provider>;
-}
-
-export function useCurrentSessionContext(): SessionContext {
-  const ctx = useContext(Ctx);
-  if (!ctx) {
-    throw new Error(
-      '[biome-registry-web] useCurrentSessionContext() called outside <SessionContextProvider>. ' +
-        'The host shell must wrap session UI with the provider before any biome reads it.',
-    );
-  }
-  return ctx;
-}
-
-/**
- * Non-throwing variant for components that may render outside a session
- * context (e.g. shared primitives reused on the design-system-builder page).
- * Returns `null` instead of throwing.
- */
-export function useOptionalSessionContext(): SessionContext | null {
-  return useContext(Ctx);
+  return (
+    <SessionContextValue.Provider value={value}>
+      {children}
+    </SessionContextValue.Provider>
+  );
 }

package/src/registry/lib/session-context.ts

@@ -0,0 +1,21 @@
+import { createContext, useContext } from 'react';
+
+import type { SessionContext } from '../../index';
+
+export const SessionContextValue = createContext<SessionContext | null>(null);
+SessionContextValue.displayName = 'SessionContext';
+
+export function useCurrentSessionContext(): SessionContext {
+  const ctx = useContext(SessionContextValue);
+  if (!ctx) {
+    throw new Error(
+      '[biome-registry-web] useCurrentSessionContext() called outside <SessionContextProvider>. ' +
+        'The host shell must wrap session UI with the provider before any biome reads it.',
+    );
+  }
+  return ctx;
+}
+
+export function useOptionalSessionContext(): SessionContext | null {
+  return useContext(SessionContextValue);
+}

package/src/registry/lib/session-selectors.ts

@@ -52,7 +52,9 @@ function applies<T extends { readonly appliesTo?: (...args: never[]) => boolean
   args: Parameters<PredicateOf<T>>,
 ): boolean {
   const predicate = item.appliesTo as PredicateOf<T> | undefined;
-  return predicate == null ? true : predicate(...args);
+  return predicate === null || predicate === undefined
+    ? true
+    : predicate(...args);
 }
 
 // ── Slash commands ────────────────────────────────────────────────────

package/src/ui/branding/app-branding-context.ts

@@ -0,0 +1,20 @@
+import * as React from 'react';
+
+export interface AppBrandingContextValue {
+  readonly displayName: string;
+  readonly logoUrl?: string;
+  readonly primaryColor?: string;
+}
+
+export const AppBrandingContext =
+  React.createContext<AppBrandingContextValue | null>(null);
+
+export function useAppBranding(): AppBrandingContextValue {
+  const ctx = React.useContext(AppBrandingContext);
+  if (ctx === null) {
+    throw new Error(
+      'useAppBranding must be used within an <AppBrandingProvider>.',
+    );
+  }
+  return ctx;
+}

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

@@ -23,6 +23,10 @@ import * as React from 'react';
 import type { BrandingConfig } from '@xemahq/kernel-contracts/app-platform';
 
 import { cn } from '../cn';
+import {
+  AppBrandingContext,
+  type AppBrandingContextValue,
+} from './app-branding-context';
 
 import {
   sanitizeCssCustomPropertyName,
@@ -33,32 +37,6 @@ import {
 /** 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;
@@ -137,7 +115,7 @@ export function AppBrandingProvider({
         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}
+        style={cssVars}
       >
         {children}
       </div>

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

@@ -347,7 +347,13 @@ function AudioFieldInput({ value, onChange, disabled, path }: SchemaFieldInputPr
         ) : null}
       </div>
       {error ? <p className="text-body-2 text-destructive">{error}</p> : null}
-      {current && !recording ? <audio id={inputId} controls src={current} className="w-full" /> : null}
+      {current && !recording ? (
+        <Button asChild variant="outline" size="sm">
+          <a id={inputId} href={current} target="_blank" rel="noreferrer">
+            Open recorded audio
+          </a>
+        </Button>
+      ) : null}
     </div>
   );
 }

package/src/ui/capture/use-prefill.ts

@@ -81,7 +81,10 @@ export function usePrefill<T extends CaptureValues = CaptureValues>(
 
   const setValues = useCallback((updater: Partial<T> | ((prev: T) => T)) => {
     setValuesState((prev) => {
-      const next = typeof updater === 'function' ? (updater as (p: T) => T)(prev) : { ...prev, ...updater };
+      const next =
+        typeof updater === 'function'
+          ? updater(prev)
+          : { ...prev, ...updater };
       const changed = new Set<string>();
       for (const k of Object.keys(next)) {
         if (next[k] !== prev[k]) {

package/src/ui/capture/use-wizard.ts

@@ -8,7 +8,7 @@
 // ═══════════════════════════════════════════════════════════════════════════
 import { useCallback, useMemo, useState } from 'react';
 
-import { FormStepStatus } from '../primitives/form-stepper';
+import { FormStepStatus } from '../primitives/form-stepper.types';
 
 export interface WizardStepDef {
   readonly key: string;
@@ -68,7 +68,7 @@ export function useWizard(options: UseWizardOptions): WizardApi {
 
   const isControlled = step !== undefined;
   const [internal, setInternal] = useState(() => clamp(initialStep));
-  const activeIndex = clamp(isControlled ? (step as number) : internal);
+  const activeIndex = clamp(isControlled ? step : internal);
 
   const gate = useCallback((i: number) => (canAdvance ? canAdvance(i) : true), [canAdvance]);
 

package/src/ui/capture/wizard.tsx

@@ -10,7 +10,8 @@ import { Children, isValidElement, type ReactElement, type ReactNode } from 'rea
 
 import { cn } from '../cn';
 import { Button } from '../primitives/button';
-import { FormStepper, type FormStep } from '../primitives/form-stepper';
+import { FormStepper } from '../primitives/form-stepper';
+import type { FormStep } from '../primitives/form-stepper.types';
 
 import type { WizardApi } from './use-wizard';