@xemahq/ui-kernel 0.11.0 → 0.11.2

package/src/lib/system-bus/palette.ts

@@ -1,78 +0,0 @@
-import { type PaletteEntrySource } from './enums';
-
-import type { CapabilityRef } from '@xemahq/kernel-contracts/capability';
-
-/**
- * Command-palette plane of the SystemBus.
- *
- * The palette is the UNION of two sources (tagged by
- * {@link PaletteEntrySource}):
- *   1. every capability the actor may invoke — sourced from
- *      `capability-registry-api` (the host's capability-registry client);
- *   2. every registered cross-biome intent action — sourced from the
- *      SystemBus `intents` registry.
- *
- * The palette performs NO authorization. The capability source is already
- * actor-scoped server-side (the registry returns only capabilities the
- * subject can see); selecting an entry routes through `capability.invoke`,
- * where the backend router makes the final allow/deny decision. The
- * palette is pure presentation orchestration.
- */
-
-/** A palette entry backed by a capability descriptor. */
-export interface CapabilityPaletteEntry {
-  readonly source: PaletteEntrySource.Capability;
-  /** Stable id (the capability ref doubles as the id). */
-  readonly id: string;
-  /** Human label rendered in the palette row. */
-  readonly label: string;
-  /** Optional one-line description from the capability descriptor. */
-  readonly summary?: string;
-  /** The capability the entry invokes when selected. */
-  readonly capabilityRef: CapabilityRef;
-}
-
-/** A palette entry backed by a registered cross-biome intent. */
-export interface IntentPaletteEntry {
-  readonly source: PaletteEntrySource.Intent;
-  /** Stable id, unique across registered intents. */
-  readonly id: string;
-  /** Human label rendered in the palette row. */
-  readonly label: string;
-  /** Biome that provides the intent action. */
-  readonly biomeId: string;
-}
-
-/** Discriminated union of palette entries. */
-export type PaletteEntry = CapabilityPaletteEntry | IntentPaletteEntry;
-
-/**
- * Query against the palette. `text` is matched by the host's own ranker
- * (the contract does not prescribe a fuzzy algorithm). `sources` narrows
- * to a subset of {@link PaletteEntrySource}; omitted means "all sources".
- */
-export interface PaletteQuery {
-  readonly text: string;
-  readonly sources?: readonly PaletteEntrySource[];
-}
-
-/**
- * The `palette` surface of the SystemBus. Framework-agnostic — no React.
- * The host wires a capability-registry client + the SystemBus intent
- * registry behind `query`. `subscribe` lets a palette UI re-render when
- * either source changes (a biome registers an intent, the registry
- * refreshes).
- */
-export interface PaletteBus {
-  /**
-   * Resolve palette entries matching `query`, ranked by the host. Async
-   * because the capability source may hit `capability-registry-api`.
-   */
-  query(query: PaletteQuery): Promise<readonly PaletteEntry[]>;
-  /**
-   * Subscribe to palette-source changes. Returns an unsubscribe fn. Fires
-   * when a biome registers/unregisters an intent or the capability source
-   * is refreshed — so a palette overlay can re-query without polling.
-   */
-  subscribe(listener: () => void): () => void;
-}

package/src/lib/system-bus/system-bus-builder.ts

@@ -1,159 +0,0 @@
-import {
-  parseDeeplink,
-  type DeeplinkBus,
-  type ParsedDeeplink,
-} from './deeplink';
-import { PaletteEntrySource } from './enums';
-import {
-  type CapabilityInvoker,
-  type DeeplinkResolver,
-  type PaletteSource,
-  type WindowManager,
-} from './host-ports';
-import { IntentRegistry } from './intent-registry';
-import {
-  type IntentPaletteEntry,
-  type PaletteBus,
-  type PaletteEntry,
-  type PaletteQuery,
-} from './palette';
-
-import type { SystemBus } from './system-bus';
-
-/**
- * Host-supplied ports needed to build a real {@link SystemBus}. The kernel
- * ships the framework-agnostic pieces (`IntentRegistry`, `parseDeeplink`);
- * the host supplies the concrete backend + shell behind these ports. NONE
- * are optional — a missing port is a wiring bug and `buildSystemBus` fails
- * fast.
- */
-export interface SystemBusPorts {
-  /** Relays `capability.invoke` to the backend capability-router. */
-  readonly capability: CapabilityInvoker;
-  /** Sources the capability half of the palette from the registry. */
-  readonly palette: PaletteSource;
-  /** Realises the window plane (open / focus / close / arrange). */
-  readonly windows: WindowManager;
-  /** Navigates the running shell to a parsed deeplink target. */
-  readonly deeplink: DeeplinkResolver;
-}
-
-function assertPort<T>(value: T | undefined, name: string): T {
-  if (value === undefined || value === null) {
-    throw new Error(
-      `[xema-ui-kernel] SystemBus port "${name}" was not supplied. ` +
-        'The host MUST provide every SystemBus port (capability / palette / ' +
-        'windows / deeplink) — there is no silent no-op fallback.',
-    );
-  }
-  return value;
-}
-
-/**
- * Build the palette bus by unioning the host's capability source with the
- * SystemBus intent registry. The capability half is already actor-scoped
- * server-side; the intent half is flattened from every registration's
- * provided actions. The host's `PaletteSource.queryCapabilities` applies
- * its own ranking to the capability rows; intent rows are filtered here by
- * a case-insensitive label/biome substring match (the contract leaves the
- * ranker to the host — substring is the deterministic floor).
- *
- * Pure orchestration: no authorization. Selecting a capability entry
- * routes through `capability.invoke` where the backend decides allow/deny.
- */
-function buildPaletteBus(
-  capabilitySource: PaletteSource,
-  intents: IntentRegistry,
-): PaletteBus {
-  function intentEntries(query: PaletteQuery): IntentPaletteEntry[] {
-    if (query.sources && !query.sources.includes(PaletteEntrySource.Intent)) {
-      return [];
-    }
-    const needle = query.text.trim().toLowerCase();
-    const out: IntentPaletteEntry[] = [];
-    // The IntentRegistry exposes registrations only through `resolve(kind)`;
-    // for a palette we want every provided action regardless of kind, so we
-    // read the public snapshot the registry exposes via `snapshot()`.
-    for (const registration of intents.snapshot()) {
-      for (const action of registration.provides) {
-        if (
-          needle.length > 0 &&
-          !action.label.toLowerCase().includes(needle) &&
-          !registration.biomeId.toLowerCase().includes(needle)
-        ) {
-          continue;
-        }
-        out.push({
-          source: PaletteEntrySource.Intent,
-          id: `${registration.biomeId}:${action.id}`,
-          label: action.label,
-          biomeId: registration.biomeId,
-        });
-      }
-    }
-    return out;
-  }
-
-  return {
-    async query(query: PaletteQuery): Promise<readonly PaletteEntry[]> {
-      const wantsCapabilities =
-        !query.sources || query.sources.includes(PaletteEntrySource.Capability);
-      const capabilityEntries = wantsCapabilities
-        ? await capabilitySource.queryCapabilities(query)
-        : [];
-      return [...capabilityEntries, ...intentEntries(query)];
-    },
-    subscribe(listener: () => void): () => void {
-      const offCapabilities = capabilitySource.subscribe(listener);
-      const offIntents = intents.subscribe(listener);
-      return () => {
-        offCapabilities();
-        offIntents();
-      };
-    },
-  };
-}
-
-function buildDeeplinkBus(resolver: DeeplinkResolver): DeeplinkBus {
-  return {
-    parse(raw: string): ParsedDeeplink {
-      return parseDeeplink(raw);
-    },
-    async resolve(target: string | ParsedDeeplink): Promise<void> {
-      // Parse-first so a malformed deeplink fails fast in the kernel parser
-      // before the host navigation ever runs.
-      const parsed =
-        typeof target === 'string' ? parseDeeplink(target) : target;
-      await resolver.resolve(parsed);
-    },
-  };
-}
-
-/**
- * Construct the real {@link SystemBus} from the host's ports plus the
- * kernel's framework-agnostic runtime (`IntentRegistry` + `parseDeeplink`).
- * The `intents` registry is owned by the bus instance so biome
- * registrations and palette intent rows share one source of truth.
- *
- * Fail-fast: every port is required. No port may be silently stubbed. This
- * is the framework-agnostic builder — any host adapter (Next.js, React-
- * Router, …) wires its concrete ports and calls this.
- */
-export function buildSystemBus(ports: SystemBusPorts): SystemBus {
-  const capability = assertPort(ports.capability, 'capability');
-  const paletteSource = assertPort(ports.palette, 'palette');
-  const windows = assertPort(ports.windows, 'windows');
-  const deeplinkResolver = assertPort(ports.deeplink, 'deeplink');
-
-  // Concrete type (not the `IntentBus` interface): the palette builder
-  // reads `intents.snapshot()`, which is an `IntentRegistry` affordance.
-  const intents: IntentRegistry = new IntentRegistry();
-
-  return {
-    capability,
-    intents,
-    palette: buildPaletteBus(paletteSource, intents),
-    deeplink: buildDeeplinkBus(deeplinkResolver),
-    windows,
-  };
-}

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

@@ -1,37 +0,0 @@
-import type { CapabilityBus } from './capability-invoke';
-import type { DeeplinkBus } from './deeplink';
-import type { IntentBus } from './intents';
-import type { PaletteBus } from './palette';
-import type { WindowBus } from './windows';
-
-/**
- * `SystemBus` — the framework-agnostic OS-orchestration plane every
- * frontend biome reaches through its {@link HostBridge}.
- *
- * **Pure orchestration. Zero policy.** The SystemBus routes intent,
- * navigation, capability invocation, palette, and windowing. It NEVER
- * authorizes, denies, or duplicates policy. Every `capability.invoke`
- * routes through the backend capability-router, which is the single
- * authority on auth / tenancy / policy / audit. The SystemBus's job is to
- * carry orchestration metadata faithfully and relay the router's outcome —
- * a denial surfaces as an observable result (`output === undefined` +
- * `auditId`), never a silent swallow.
- *
- * The contract is framework-agnostic on purpose: it imports no Vite, no
- * Next.js, no React-Router, and no generated transport client. A concrete
- * host (Vite SPA today, Next.js tomorrow) implements each sub-bus against
- * its router, its capability-router client, and its window manager. Biome
- * code is identical across hosts.
- */
-export interface SystemBus {
-  /** Capability invocation → backend router (backend enforces; bus adds none). */
-  readonly capability: CapabilityBus;
-  /** Cross-biome "Open with… / Send to…" intent registry. */
-  readonly intents: IntentBus;
-  /** Command palette = capabilities ∪ registered intents. */
-  readonly palette: PaletteBus;
-  /** Typed `xema://` deeplink parse + resolve. */
-  readonly deeplink: DeeplinkBus;
-  /** Host window manager (open / focus / close / arrange). */
-  readonly windows: WindowBus;
-}

package/src/lib/system-bus/windows.ts

@@ -1,51 +0,0 @@
-import { type WindowArrangement, WindowOp } from './enums';
-
-/**
- * Window-management plane of the SystemBus.
- *
- * A "window" is a host-managed surface hosting a biome route or object.
- * The contract is framework-agnostic: the host (desktop shell, tiling WM,
- * tabbed SPA) decides how a window is physically realised, but every host
- * exposes the same closed {@link WindowOp} verb set. The SystemBus carries
- * no authorization here — windowing is pure shell orchestration.
- */
-
-/** Identifier of an open window, minted by the host on `open`. */
-export type WindowId = string;
-
-/** A request to open a new window onto a deeplink target. */
-export interface OpenWindowRequest {
-  /** The `xema://` deeplink the new window should display. */
-  readonly target: string;
-  /** Optional human title; the host falls back to the target's own title. */
-  readonly title?: string;
-}
-
-/** Snapshot of an open window. */
-export interface WindowState {
-  readonly id: WindowId;
-  readonly target: string;
-  readonly title: string;
-  readonly focused: boolean;
-}
-
-/**
- * The `windows` surface of the SystemBus. Each method maps to a closed
- * {@link WindowOp}. Operations a host cannot honour reject fail-fast
- * rather than silently no-op, so callers never assume a window exists
- * when it does not.
- */
-export interface WindowBus {
-  /** {@link WindowOp.Open} — open a new window; resolves with its id. */
-  open(request: OpenWindowRequest): Promise<WindowId>;
-  /** {@link WindowOp.Focus} — bring a window to the foreground. Rejects on unknown id. */
-  focus(id: WindowId): Promise<void>;
-  /** {@link WindowOp.Close} — close a window. Rejects on unknown id. */
-  close(id: WindowId): Promise<void>;
-  /** {@link WindowOp.Arrange} — apply a layout to all open windows. */
-  arrange(arrangement: WindowArrangement): Promise<void>;
-  /** Current snapshot of open windows (for a window-list UI). */
-  list(): readonly WindowState[];
-  /** Subscribe to window-set changes; returns an unsubscribe fn. */
-  subscribe(listener: () => void): () => void;
-}

package/src/offline/id.ts

@@ -1,16 +0,0 @@
-/** RFC-4122 id, using the platform crypto when available (browser + Node 18+),
- *  with a non-cryptographic fallback for exotic runtimes. */
-export function newId(): string {
-  const c = (globalThis as { crypto?: Crypto }).crypto;
-  if (c && typeof c.randomUUID === 'function') {
-    return c.randomUUID();
-  }
-  // Fallback — good enough for an outbox entry id (not a security token).
-  return (
-    'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (ch) => {
-      const r = (Math.floor(Math.random() * 16) + Date.now()) % 16;
-      const v = ch === 'x' ? r : (r & 0x3) | 0x8;
-      return v.toString(16);
-    })
-  );
-}

package/src/offline/index.ts

@@ -1,54 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// @xemahq/ui-kernel/offline — generic offline field-capture kit
-//
-// A durable, provider-agnostic mutation outbox: queue mutations while
-// disconnected (IndexedDB) and drain them on reconnect with retry, backoff, and
-// idempotency. Pairs with the existing guided-capture kit (`../ui/capture`) and
-// the existing mobile off-canvas shell so a form captured in the field (trade
-// fair, no signal) is never lost. The immediate-online path is unchanged; only
-// a failed/offline send is queued.
-// ═══════════════════════════════════════════════════════════════════════════
-
-export { newId } from './id';
-export {
-  OutboxEntryStatus,
-  type OutboxEntry,
-  type OutboxStorage,
-  type OutboxExecutor,
-  type OutboxExecuteContext,
-  type OutboxSnapshot,
-} from './types';
-export {
-  InMemoryOutboxStorage,
-  IndexedDbOutboxStorage,
-  createDefaultOutboxStorage,
-} from './storage';
-export {
-  OnlineController,
-  isNetworkUnavailableError,
-  type OnlineListener,
-} from './online-controller';
-export {
-  Outbox,
-  type OutboxOptions,
-  type OutboxListener,
-  type EnqueueOptions,
-} from './outbox';
-export {
-  createOfflineMutationFn,
-  type OfflineMutationResult,
-  type OfflineMutationOptions,
-} from './mutation';
-export {
-  OutboxProvider,
-  type OutboxProviderProps,
-} from './react';
-export {
-  useOutbox,
-  useOutboxSnapshot,
-  useOnlineStatus,
-} from './react-hooks';
-export {
-  OfflineStatusBadge,
-  type OfflineStatusBadgeProps,
-} from './offline-status-badge';

package/src/offline/mutation.ts

@@ -1,75 +0,0 @@
-import { newId } from './id';
-import { isNetworkUnavailableError } from './online-controller';
-
-import type { Outbox } from './outbox';
-import type { OutboxExecuteContext } from './types';
-
-/** Outcome of an offline-aware mutation. */
-export interface OfflineMutationResult<TResult> {
-  /** True when the mutation was queued for later delivery (offline / network
-   *  failure) instead of applied immediately. */
-  queued: boolean;
-  /** The outbox entry id when queued (for optimistic UI correlation). */
-  entryId?: string;
-  /** The server result when applied immediately (`queued === false`). */
-  result?: TResult;
-}
-
-export interface OfflineMutationOptions<TPayload, TResult> {
-  outbox: Outbox;
-  /** Stable executor key for this mutation type (e.g. "app-forge:create-record"). */
-  kind: string;
-  /** Sends the mutation to the backend. Used BOTH for the immediate online path
-   *  and for draining the queue. Pass `ctx.idempotencyKey` to the backend so a
-   *  redelivered mutation is not double-applied. */
-  send: (payload: TPayload, ctx: OutboxExecuteContext) => Promise<TResult>;
-  /** Optional label for the pending-items UI. */
-  label?: (payload: TPayload) => string | undefined;
-}
-
-/**
- * Build an offline-aware `mutationFn` (drop-in for `@tanstack/react-query`'s
- * `useMutation`). When online it sends immediately; if the send fails because
- * the network is unavailable — or the app is already offline — the payload is
- * durably queued and the promise RESOLVES (queued: true) so the UI can update
- * optimistically. The outbox drains on reconnect. A real server rejection (4xx)
- * still throws so the form shows the validation error.
- *
- * Registers the outbox executor for `kind` once (idempotent).
- */
-export function createOfflineMutationFn<TPayload, TResult>(
-  opts: OfflineMutationOptions<TPayload, TResult>,
-): (payload: TPayload) => Promise<OfflineMutationResult<TResult>> {
-  const { outbox, kind, send, label } = opts;
-
-  if (!outbox.hasExecutor(kind)) {
-    outbox.registerExecutor<TPayload>(kind, async (payload, ctx) => {
-      await send(payload, ctx);
-    });
-  }
-
-  return async (payload: TPayload): Promise<OfflineMutationResult<TResult>> => {
-    const idempotencyKey = newId();
-
-    const queue = async (): Promise<OfflineMutationResult<TResult>> => {
-      const entry = await outbox.enqueue(kind, payload, {
-        idempotencyKey,
-        ...(label ? { label: label(payload) } : {}),
-      });
-      return { queued: true, entryId: entry.id };
-    };
-
-    if (!outbox.isOnline()) {
-      return queue();
-    }
-    try {
-      const result = await send(payload, { idempotencyKey, attempt: 1, entryId: 'direct' });
-      return { queued: false, result };
-    } catch (err) {
-      if (isNetworkUnavailableError(err)) {
-        return queue();
-      }
-      throw err; // genuine server rejection — surface it to the caller
-    }
-  };
-}

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

@@ -1,51 +0,0 @@
-import { useOutboxSnapshot } from './react-hooks';
-
-import type { Outbox } from './outbox';
-
-export interface OfflineStatusBadgeProps {
-  /** Explicit outbox; falls back to the nearest OutboxProvider. */
-  outbox?: Outbox;
-  className?: string;
-}
-
-const BASE =
-  'inline-flex items-center gap-1.5 rounded-full px-2.5 py-0.5 text-body-2 font-medium';
-
-/**
- * A compact connectivity + queue indicator for the offline field-capture kit.
- * Renders nothing when online with an empty queue; otherwise surfaces the
- * offline / syncing / dead-letter state so the user knows captures are safe and
- * will sync. Self-contained (no UI-primitive deps) so it can live in the
- * framework-level offline module.
- */
-export function OfflineStatusBadge({ outbox, className }: OfflineStatusBadgeProps) {
-  const { online, pendingCount, failedCount, draining } = useOutboxSnapshot(outbox);
-
-  if (online && pendingCount === 0 && failedCount === 0) {
-    return null;
-  }
-
-  const cls = (tone: string): string =>
-    `${BASE} ${tone}${className ? ` ${className}` : ''}`;
-
-  if (failedCount > 0) {
-    return (
-      <span className={cls('bg-destructive/10 text-destructive')} role="status">
-        ⚠ {failedCount} failed to sync
-      </span>
-    );
-  }
-  if (!online) {
-    return (
-      <span className={cls('bg-amber-500/10 text-amber-600')} role="status">
-        ● Offline{pendingCount > 0 ? ` — ${pendingCount} queued` : ''}
-      </span>
-    );
-  }
-  // Online with a non-empty queue → actively draining.
-  return (
-    <span className={cls('bg-secondary text-secondary-foreground')} role="status">
-      {draining ? '⟳' : '●'} Syncing {pendingCount}…
-    </span>
-  );
-}

package/src/offline/online-controller.ts

@@ -1,105 +0,0 @@
-export type OnlineListener = (online: boolean) => void;
-
-/**
- * Tracks connectivity via `navigator.onLine` + the window `online`/`offline`
- * events. SSR-safe: when there is no `window`/`navigator` it reports online (so
- * server rendering never queues) and is inert. `navigator.onLine` only knows
- * about the local link, so callers may also mark the controller offline when a
- * request fails as network-unavailable (`reportOffline`) and online again after
- * a successful send (`reportOnline`).
- */
-export class OnlineController {
-  private online: boolean;
-  private readonly listeners = new Set<OnlineListener>();
-  private started = false;
-
-  private readonly onOnline = () => this.set(true);
-  private readonly onOffline = () => this.set(false);
-
-  constructor() {
-    this.online =
-      typeof navigator === 'undefined' || typeof navigator.onLine !== 'boolean'
-        ? true
-        : navigator.onLine;
-  }
-
-  isOnline(): boolean {
-    return this.online;
-  }
-
-  start(): void {
-    if (this.started || typeof window === 'undefined') {
-      return;
-    }
-    this.started = true;
-    window.addEventListener('online', this.onOnline);
-    window.addEventListener('offline', this.onOffline);
-  }
-
-  stop(): void {
-    if (!this.started || typeof window === 'undefined') {
-      return;
-    }
-    this.started = false;
-    window.removeEventListener('online', this.onOnline);
-    window.removeEventListener('offline', this.onOffline);
-  }
-
-  /** Force offline after a network-unavailable request failure. */
-  reportOffline(): void {
-    this.set(false);
-  }
-
-  /** Force online after a successful send (recovers from a stale offline flag). */
-  reportOnline(): void {
-    this.set(true);
-  }
-
-  subscribe(listener: OnlineListener): () => void {
-    this.listeners.add(listener);
-    return () => this.listeners.delete(listener);
-  }
-
-  private set(online: boolean): void {
-    if (this.online === online) {
-      return;
-    }
-    this.online = online;
-    for (const l of this.listeners) {
-      l(online);
-    }
-  }
-}
-
-/**
- * Best-effort classifier for "the request failed because the network was
- * unavailable" (offline, DNS, connection refused) vs a real server rejection.
- * A fetch that never reaches the server rejects with a TypeError ("Failed to
- * fetch"); an aborted request has name AbortError. Anything with an HTTP status
- * is a server response, NOT a network failure.
- */
-export function isNetworkUnavailableError(err: unknown): boolean {
-  if (typeof navigator !== 'undefined' && navigator.onLine === false) {
-    return true;
-  }
-  if (!err || typeof err !== 'object') {
-    return false;
-  }
-  const e = err as { name?: string; message?: string; status?: number; response?: unknown };
-  // A response with a status is a server answer, not a transport failure.
-  if (typeof e.status === 'number' || e.response !== undefined) {
-    return false;
-  }
-  if (e.name === 'AbortError') {
-    return false;
-  }
-  const msg = (e.message ?? '').toLowerCase();
-  return (
-    e.name === 'TypeError' ||
-    msg.includes('failed to fetch') ||
-    msg.includes('network') ||
-    msg.includes('load failed') ||
-    msg.includes('econnrefused') ||
-    msg.includes('enotfound')
-  );
-}