@xemahq/ui-kernel 0.6.1 → 0.8.0

package/src/lib/biome-host/define-web-biome.spec.ts

@@ -0,0 +1,221 @@
+/**
+ * `defineWebBiome` — define-time scope/access locking, the fail-closed
+ * defaults, and closed-set completeness.
+ *
+ * This suite replaces an earlier `define-web-biome.test.js` written for
+ * Node's test runner against `dist/`. That file ran NOWHERE: the package's
+ * `test` script is a notice (the kernel carries no test runner by design) and
+ * the host-web vitest `include` is `*.{test,spec}.{ts,tsx}` — so a `.js` file
+ * was invisible to both. A security test that never executes reads as
+ * coverage while proving nothing, so it is gone; this vitest spec is synced
+ * into the host mirror by the frontend bridge and runs there with everything
+ * else.
+ *
+ * The invariant under test is the security one: a route is public ONLY when
+ * its author said so twice, explicitly. Nothing defaulted, inferred, or
+ * coerced can produce a public route.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { defineWebBiome } from './define-web-biome';
+import {
+  PAGE_CHROME_VALUES,
+  ROUTE_ACCESS_VALUES,
+  ROUTE_SCOPE_VALUES,
+  type PageChrome,
+  type RouteAccess,
+  type RouteScope,
+} from './frontend-biome';
+
+import type { HostBridge } from './host-bridge';
+
+const load = () => Promise.resolve({ default: () => null });
+const bridge = {} as HostBridge;
+
+describe('defineWebBiome — public/chromeless scope', () => {
+  it('rejects a public page whose access defaults to member', () => {
+    expect(() =>
+      defineWebBiome({
+        id: 'test-biome',
+        displayName: 'Test',
+        pages: [{ slug: 'ext/:id', label: 'Ext', scope: 'public', load }],
+      }),
+    ).toThrow(/a 'public' scope page MUST declare access: 'public'/);
+  });
+
+  it('rejects a public page with an explicit non-public access tier', () => {
+    expect(() =>
+      defineWebBiome({
+        id: 'test-biome',
+        displayName: 'Test',
+        pages: [
+          {
+            slug: 'ext/:id',
+            label: 'Ext',
+            scope: 'public',
+            access: 'org-admin',
+            load,
+          },
+        ],
+      }),
+    ).toThrow(/a 'public' scope page MUST declare access: 'public'/);
+  });
+
+  it('rejects a non-public page that declares access public', () => {
+    expect(() =>
+      defineWebBiome({
+        id: 'test-biome',
+        displayName: 'Test',
+        pages: [{ slug: 'system/x', label: 'X', access: 'public', load }],
+      }),
+    ).toThrow(/access: 'public' is only valid on a 'public' scope page/);
+  });
+
+  it('accepts a public + access:public page and emits no nav item', () => {
+    const biome = defineWebBiome({
+      id: 'test-biome',
+      displayName: 'Test',
+      pages: [
+        {
+          slug: 'ext/:id',
+          label: 'Ext',
+          scope: 'public',
+          access: 'public',
+          load,
+        },
+      ],
+    })(bridge);
+
+    expect(biome.routes).toHaveLength(1);
+    const route = biome.routes?.[0];
+    expect(route?.path).toBe('ext/:id');
+    expect(route?.access).toBe('public');
+    expect(route?.projectScoped).toBe(false);
+    // A public route is un-authenticated; it never belongs in the authed rail.
+    expect(biome.navItems).toHaveLength(0);
+  });
+
+  it('chrome defaults to host and none passes through', () => {
+    const biome = defineWebBiome({
+      id: 'test-biome',
+      displayName: 'Test',
+      pages: [
+        { slug: 'system/a', label: 'A', load },
+        { slug: 'system/b', label: 'B', chrome: 'none', load },
+      ],
+    })(bridge);
+
+    expect(biome.routes?.find((r) => r.path === 'system/a')?.chrome).toBe(
+      'host',
+    );
+    expect(biome.routes?.find((r) => r.path === 'system/b')?.chrome).toBe(
+      'none',
+    );
+  });
+});
+
+describe('defineWebBiome — public is opt-in, never a default', () => {
+  /**
+   * THE fail-closed invariant. An ordinarily-declared page (no `scope`, no
+   * `access`) must emit a route that carries NO `access` marker at all — the
+   * host then applies its own `member` default. If the kernel ever started
+   * defaulting `access` (or `scope`) to `'public'`, every existing biome route
+   * in the fleet would silently become reachable without a session.
+   *
+   * Mutation-proof (recorded 2026-07-22): flipping the emit in
+   * `defineWebBiome` to `access: page.access ?? 'public'` turns this test RED
+   * ("expected 'public' to be undefined"), and flipping the validator default
+   * `page.access ?? 'member'` to `?? 'public'` makes the ordinary page throw
+   * at define time — RED in this test and in the two below. There is no
+   * mutation of a default that makes a route public and keeps the suite green.
+   */
+  it('an ordinary page emits NO access marker (host defaults to member)', () => {
+    const biome = defineWebBiome({
+      id: 'test-biome',
+      displayName: 'Test',
+      pages: [{ slug: 'system/a', label: 'A', load }],
+    })(bridge);
+
+    const route = biome.routes?.[0];
+    expect(route?.access).toBeUndefined();
+    expect(route?.projectScoped).toBe(false);
+    // …and it DOES contribute a nav item, unlike a public route.
+    expect(biome.navItems).toHaveLength(1);
+  });
+
+  it('an authenticated page can be chromeless without becoming public', () => {
+    // Chrome and access are orthogonal axes: the embedded-app case.
+    const biome = defineWebBiome({
+      id: 'test-biome',
+      displayName: 'Test',
+      pages: [
+        {
+          slug: 'apps/:appId/embed',
+          label: 'Embedded app',
+          chrome: 'none',
+          navHidden: true,
+          load,
+        },
+      ],
+    })(bridge);
+
+    const route = biome.routes?.[0];
+    expect(route?.chrome).toBe('none');
+    expect(route?.access).toBeUndefined();
+  });
+
+  it('every non-public access tier is rejected on a public page', () => {
+    for (const access of ROUTE_ACCESS_VALUES.filter((a) => a !== 'public')) {
+      expect(() =>
+        defineWebBiome({
+          id: 'test-biome',
+          displayName: 'Test',
+          pages: [{ slug: 'ext', label: 'Ext', scope: 'public', access, load }],
+        }),
+      ).toThrow(/MUST declare access: 'public'/);
+    }
+  });
+
+  it('every non-public scope rejects access public', () => {
+    for (const scope of ROUTE_SCOPE_VALUES.filter((s) => s !== 'public')) {
+      expect(() =>
+        defineWebBiome({
+          id: 'test-biome',
+          displayName: 'Test',
+          pages: [{ slug: 'x', label: 'X', scope, access: 'public', load }],
+        }),
+      ).toThrow(/only valid on a 'public' scope page/);
+    }
+  });
+});
+
+describe('closed-set completeness', () => {
+  /**
+   * The runtime tuples ARE the types (`RouteAccess = typeof
+   * ROUTE_ACCESS_VALUES[number]`), so a new member cannot be added to the type
+   * without appearing here — which is what makes the exhaustive iteration in
+   * this file, and the host resolver's `default`-less switch, complete by
+   * construction. These assertions are the compile-time proof made executable:
+   * the `satisfies` widening below fails to compile if a tuple ever drifts
+   * from its type.
+   */
+  it('the access tuple enumerates exactly the RouteAccess union', () => {
+    const all: readonly RouteAccess[] =
+      ROUTE_ACCESS_VALUES satisfies readonly RouteAccess[];
+    expect([...all].sort()).toEqual(
+      ['member', 'org-admin', 'platform-admin', 'public'].sort(),
+    );
+  });
+
+  it('the scope tuple enumerates exactly the RouteScope union', () => {
+    const all: readonly RouteScope[] =
+      ROUTE_SCOPE_VALUES satisfies readonly RouteScope[];
+    expect([...all].sort()).toEqual(['org', 'project', 'public'].sort());
+  });
+
+  it('the chrome tuple enumerates exactly the PageChrome union', () => {
+    const all: readonly PageChrome[] =
+      PAGE_CHROME_VALUES satisfies readonly PageChrome[];
+    expect([...all].sort()).toEqual(['host', 'none'].sort());
+  });
+});

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

@@ -50,10 +50,25 @@ export interface NavItemContribution {
  * authenticated route group. It is value-locked to `RouteScope` `'public'`
  * (`defineWebBiome` rejects any other pairing at define time), so a route is
  * public in BOTH senses or in neither. Closed set — a new member is a
- * one-line change here and one `case` in the host resolver's exhaustive
- * `hasRouteAccess` switch.
+ * one-line change to {@link ROUTE_ACCESS_VALUES} and one `case` in the host
+ * resolver's exhaustive `hasRouteAccess` switch (the switch has no `default`,
+ * so an unhandled member is a compile error, never a silent allow).
+ *
+ * The tuple below is the SINGLE source of truth: the type is derived from it,
+ * so a member cannot exist in the type without also being enumerable at
+ * runtime — which is what lets a host prove exhaustiveness in a test rather
+ * than by inspection. Order is least → most privileged; `public` is the
+ * no-auth marker and is deliberately last.
  */
-export type RouteAccess = 'member' | 'org-admin' | 'platform-admin' | 'public';
+export const ROUTE_ACCESS_VALUES = [
+  'member',
+  'org-admin',
+  'platform-admin',
+  'public',
+] as const;
+
+/** Access tier required to render a route. See {@link ROUTE_ACCESS_VALUES}. */
+export type RouteAccess = (typeof ROUTE_ACCESS_VALUES)[number];
 
 /**
  * Where a route mounts in the host's URL/auth topology. Closed set — adding a
@@ -65,8 +80,13 @@ export type RouteAccess = 'member' | 'org-admin' | 'platform-admin' | 'public';
  *   authenticated group.
  * - `public` — mounts OUTSIDE the authenticated group; no Keycloak session,
  *   no login redirect, no org switcher. Locked to `RouteAccess` `'public'`.
+ *
+ * Single source of truth for the closed set; the type is derived from it.
  */
-export type RouteScope = 'org' | 'project' | 'public';
+export const ROUTE_SCOPE_VALUES = ['org', 'project', 'public'] as const;
+
+/** Where a route mounts. See {@link ROUTE_SCOPE_VALUES}. */
+export type RouteScope = (typeof ROUTE_SCOPE_VALUES)[number];
 
 /**
  * Whether a page renders wrapped in the host application shell (app rail,
@@ -78,8 +98,15 @@ export type RouteScope = 'org' | 'project' | 'public';
  *   switcher (a full-bleed surface). `public` routes are structurally
  *   chromeless (their route group ships no shell); `none` also lets an
  *   authenticated route opt out of the shell.
+ *
+ * Single source of truth for the closed set; the type is derived from it.
+ * Chrome is ORTHOGONAL to access: `chrome: 'none'` on an authenticated route
+ * is the embedded-app case and grants no privilege change whatsoever.
  */
-export type PageChrome = 'host' | 'none';
+export const PAGE_CHROME_VALUES = ['host', 'none'] as const;
+
+/** Host-shell mode a page renders in. See {@link PAGE_CHROME_VALUES}. */
+export type PageChrome = (typeof PAGE_CHROME_VALUES)[number];
 
 export interface RouteContribution {
   /** React-router path. May include params. */

package/src/offline/id.ts

@@ -0,0 +1,16 @@
+/** 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

@@ -0,0 +1,52 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// @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,
+  useOutbox,
+  useOutboxSnapshot,
+  useOnlineStatus,
+  type OutboxProviderProps,
+} from './react';
+export {
+  OfflineStatusBadge,
+  type OfflineStatusBadgeProps,
+} from './offline-status-badge';

package/src/offline/mutation.ts

@@ -0,0 +1,75 @@
+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

@@ -0,0 +1,51 @@
+import { useOutboxSnapshot } from './react';
+
+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

@@ -0,0 +1,105 @@
+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')
+  );
+}