@xemahq/ui-kernel 0.11.1 → 0.12.0

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

package/src/offline/outbox.test.ts

@@ -1,172 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-
-import { OnlineController } from './online-controller';
-import { Outbox, type OutboxOptions } from './outbox';
-import { InMemoryOutboxStorage } from './storage';
-import { OutboxEntryStatus, type OutboxExecuteContext } from './types';
-
-const KIND = 'test:mutation';
-
-function makeOutbox(overrides: Partial<OutboxOptions> = {}): {
-  outbox: Outbox;
-  online: OnlineController;
-} {
-  const online = new OnlineController(); // node: navigator undefined ⇒ online
-  const outbox = new Outbox({
-    storage: new InMemoryOutboxStorage(),
-    online,
-    // Immediate scheduler: retries are driven synchronously within `drain()`.
-    scheduler: (fn) => fn(),
-    ...overrides,
-  });
-  return { outbox, online };
-}
-
-describe('Outbox', () => {
-  it('queues while offline and delivers on reconnect', async () => {
-    const { outbox, online } = makeOutbox();
-    const send = vi.fn(() => Promise.resolve());
-    outbox.registerExecutor(KIND, send);
-
-    online.reportOffline();
-    await outbox.enqueue(KIND, { a: 1 });
-    expect(send).not.toHaveBeenCalled();
-    expect(outbox.getSnapshot().pendingCount).toBe(1);
-
-    online.reportOnline();
-    await outbox.drain();
-    expect(send).toHaveBeenCalledTimes(1);
-    expect(outbox.getSnapshot().entries).toHaveLength(0);
-  });
-
-  it('delivers immediately when online and removes the entry; idempotency key is stable', async () => {
-    const { outbox } = makeOutbox();
-    const keys: string[] = [];
-    outbox.registerExecutor(KIND, (_p, ctx: OutboxExecuteContext) => {
-      keys.push(ctx.idempotencyKey);
-      return Promise.resolve();
-    });
-    await outbox.enqueue(KIND, { a: 1 });
-    await outbox.drain();
-    expect(keys).toHaveLength(1);
-    expect(keys[0]).toMatch(/[0-9a-f-]{36}/);
-    expect(outbox.getSnapshot().entries).toHaveLength(0);
-  });
-
-  it('retries a 5xx and eventually succeeds', async () => {
-    const { outbox } = makeOutbox();
-    let calls = 0;
-    outbox.registerExecutor(KIND, () => {
-      calls += 1;
-      if (calls < 3) {
-        return Promise.reject({ status: 503, message: 'unavailable' });
-      }
-      return Promise.resolve();
-    });
-    await outbox.enqueue(KIND, { a: 1 });
-    await outbox.drain();
-    expect(calls).toBe(3);
-    expect(outbox.getSnapshot().entries).toHaveLength(0);
-  });
-
-  it('dead-letters a 4xx immediately (no pointless retries)', async () => {
-    const { outbox } = makeOutbox();
-    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);
-  });
-
-  it('dead-letters after exhausting retries on persistent 5xx', async () => {
-    const { outbox } = makeOutbox({ maxAttempts: 3 });
-    let calls = 0;
-    outbox.registerExecutor(KIND, () => {
-      calls += 1;
-      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,
-    );
-  });
-
-  it('a network failure never advances the attempt counter or dead-letters', async () => {
-    // Captured scheduler so the offline-retry loop does not run forever.
-    const timers: Array<() => void> = [];
-    const { outbox } = makeOutbox({ scheduler: (fn) => void timers.push(fn) });
-    let succeed = false;
-    outbox.registerExecutor(KIND, () => {
-      if (!succeed) {
-        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];
-    if (!parked) {
-      throw new Error(
-        'the offline entry was dropped from the outbox instead of parked',
-      );
-    }
-    expect(parked.status).toBe(OutboxEntryStatus.Pending);
-    expect(parked.attempts).toBe(0); // offline is not the payload's fault
-    expect(outbox.getSnapshot().failedCount).toBe(0);
-
-    // Reconnect + retry drains it.
-    succeed = true;
-    await outbox.drain();
-    expect(outbox.getSnapshot().entries).toHaveLength(0);
-  });
-
-  it('delivers queued entries in FIFO order', async () => {
-    const { outbox, online } = makeOutbox();
-    const order: number[] = [];
-    outbox.registerExecutor(KIND, (p: { n: number }) => {
-      order.push(p.n);
-      return Promise.resolve();
-    });
-    online.reportOffline();
-    await outbox.enqueue(KIND, { n: 1 });
-    await outbox.enqueue(KIND, { n: 2 });
-    await outbox.enqueue(KIND, { n: 3 });
-    online.reportOnline();
-    await outbox.drain();
-    expect(order).toEqual([1, 2, 3]);
-  });
-
-  it('recovers crash-orphaned inflight entries to pending on start', async () => {
-    const storage = new InMemoryOutboxStorage();
-    const ts = 1;
-    await storage.put({
-      id: 'orphan',
-      kind: KIND,
-      payload: { a: 1 },
-      idempotencyKey: 'k',
-      status: OutboxEntryStatus.Inflight, // died mid-send
-      attempts: 1,
-      createdAt: ts,
-      updatedAt: ts,
-    });
-    const online = new OnlineController();
-    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,
-    );
-    outbox.stop();
-  });
-});