@xemahq/ui-kernel 0.11.1 → 0.11.2

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

@@ -1,210 +0,0 @@
-import { DeeplinkTargetKind } from './enums';
-
-/**
- * Typed parse/resolve of the SystemBus `xema://` deeplink scheme.
- *
- * The deeplink scheme addresses *places in the running shell*. It is a
- * distinct, narrower grammar from the kernel's `XemaObjectRef`
- * (`xema://<scope>/<kind>/<slug>`): a deeplink's first segment is a
- * {@link DeeplinkTargetKind} discriminator, not a scope path. The two
- * schemes share the `xema://` scheme prefix but never the same body —
- * `parseDeeplink` rejects anything whose head is not a known target kind,
- * so an `XemaObjectRef` is only valid as a deeplink when wrapped as
- * `xema://object/<XemaObjectRef-without-scheme>`.
- *
- * Grammar:
- *   xema://biome/<biomeId>/<route...>?<ctx>     → BiomeRoute
- *   xema://object/<scope>/<kind>/<slug>[@<ver>] → Object
- *   xema://capability/<capability-ref>?<input>  → Capability
- *   xema://window/<windowId>                    → Window
- *
- * Every parse is fail-fast: an unknown target kind, a missing required
- * segment, or a malformed query is a {@link DeeplinkParseError}, never a
- * silent fallback.
- */
-
-const DEEPLINK_SCHEME = 'xema://';
-
-/** Structured, fail-fast error raised by `parseDeeplink`. */
-export class DeeplinkParseError extends Error {
-  public readonly code = 'DEEPLINK_INVALID';
-  public readonly raw: string;
-  public readonly reason: string;
-
-  public constructor(raw: string, reason: string) {
-    super(`Invalid deeplink "${raw}": ${reason}`);
-    this.name = 'DeeplinkParseError';
-    this.raw = raw;
-    this.reason = reason;
-  }
-}
-
-/** A parsed `xema://biome/...` deeplink. */
-export interface BiomeRouteDeeplink {
-  readonly kind: DeeplinkTargetKind.BiomeRoute;
-  readonly biomeId: string;
-  /** The route path within the biome, with a leading slash. */
-  readonly route: string;
-  /** Parsed `?ctx` query params, empty when absent. */
-  readonly ctx: Readonly<Record<string, string>>;
-}
-
-/** A parsed `xema://object/...` deeplink. The body is the scheme-less
- * `XemaObjectRef` (e.g. `system/capability/kb.page.read@1`). */
-export interface ObjectDeeplink {
-  readonly kind: DeeplinkTargetKind.Object;
-  /** Full `XemaObjectRef` (`xema://` re-prefixed) for handing to the
-   * kernel object resolver. */
-  readonly objectRef: `xema://${string}`;
-}
-
-/** A parsed `xema://capability/...` deeplink. */
-export interface CapabilityDeeplink {
-  readonly kind: DeeplinkTargetKind.Capability;
-  /** The raw capability ref string (validated by the kernel
-   * `parseCapabilityRef` when the host launches it). */
-  readonly capabilityRef: string;
-  /** Parsed `?...` query params used as launch input, empty when absent. */
-  readonly input: Readonly<Record<string, string>>;
-}
-
-/** A parsed `xema://window/...` deeplink. */
-export interface WindowDeeplink {
-  readonly kind: DeeplinkTargetKind.Window;
-  readonly windowId: string;
-}
-
-/** Discriminated union of every deeplink target. */
-export type ParsedDeeplink =
-  | BiomeRouteDeeplink
-  | ObjectDeeplink
-  | CapabilityDeeplink
-  | WindowDeeplink;
-
-function parseQuery(search: string): Record<string, string> {
-  const out: Record<string, string> = {};
-  if (search.length === 0) {
-    return out;
-  }
-  for (const pair of search.split('&')) {
-    if (pair.length === 0) {
-      continue;
-    }
-    const eq = pair.indexOf('=');
-    if (eq === -1) {
-      out[decodeURIComponent(pair)] = '';
-    } else {
-      out[decodeURIComponent(pair.slice(0, eq))] = decodeURIComponent(
-        pair.slice(eq + 1),
-      );
-    }
-  }
-  return out;
-}
-
-/**
- * Parse a `xema://` deeplink string into a typed, discriminated
- * {@link ParsedDeeplink}. Throws {@link DeeplinkParseError} on any
- * malformed input — never returns null, never coerces.
- */
-export function parseDeeplink(raw: string): ParsedDeeplink {
-  if (typeof raw !== 'string' || !raw.startsWith(DEEPLINK_SCHEME)) {
-    throw new DeeplinkParseError(
-      String(raw),
-      `must start with "${DEEPLINK_SCHEME}"`,
-    );
-  }
-  const afterScheme = raw.slice(DEEPLINK_SCHEME.length);
-  if (afterScheme.length === 0) {
-    throw new DeeplinkParseError(raw, 'empty body after scheme');
-  }
-
-  const qIndex = afterScheme.indexOf('?');
-  const path = qIndex === -1 ? afterScheme : afterScheme.slice(0, qIndex);
-  const search = qIndex === -1 ? '' : afterScheme.slice(qIndex + 1);
-  const segments = path.split('/').filter((s) => s.length > 0);
-
-  const head = segments[0];
-  if (head === undefined) {
-    throw new DeeplinkParseError(raw, 'missing target-kind head segment');
-  }
-
-  switch (head) {
-    case DeeplinkTargetKind.BiomeRoute: {
-      const biomeId = segments[1];
-      if (biomeId === undefined) {
-        throw new DeeplinkParseError(raw, 'biome deeplink missing <biomeId>');
-      }
-      const routeSegments = segments.slice(2);
-      const route = `/${routeSegments.join('/')}`;
-      return {
-        kind: DeeplinkTargetKind.BiomeRoute,
-        biomeId,
-        route,
-        ctx: parseQuery(search),
-      };
-    }
-    case DeeplinkTargetKind.Object: {
-      const body = segments.slice(1).join('/');
-      if (body.length === 0) {
-        throw new DeeplinkParseError(
-          raw,
-          'object deeplink missing <XemaObjectRef>',
-        );
-      }
-      return {
-        kind: DeeplinkTargetKind.Object,
-        objectRef: `${DEEPLINK_SCHEME}${body}`,
-      };
-    }
-    case DeeplinkTargetKind.Capability: {
-      const capabilityRef = segments.slice(1).join('/');
-      if (capabilityRef.length === 0) {
-        throw new DeeplinkParseError(
-          raw,
-          'capability deeplink missing <capability-ref>',
-        );
-      }
-      return {
-        kind: DeeplinkTargetKind.Capability,
-        capabilityRef,
-        input: parseQuery(search),
-      };
-    }
-    case DeeplinkTargetKind.Window: {
-      const windowId = segments[1];
-      if (windowId === undefined) {
-        throw new DeeplinkParseError(raw, 'window deeplink missing <windowId>');
-      }
-      return { kind: DeeplinkTargetKind.Window, windowId };
-    }
-    default:
-      throw new DeeplinkParseError(
-        raw,
-        `unknown deeplink target kind "${head}" (expected one of: ${Object.values(
-          DeeplinkTargetKind,
-        ).join(', ')})`,
-      );
-  }
-}
-
-/**
- * The `deeplink` surface of the SystemBus. `parse` is pure
- * (framework-agnostic) and re-exported from the runtime as
- * {@link parseDeeplink}. `resolve` navigates the running shell to the
- * parsed target; the host supplies the concrete navigation. Resolution
- * is orchestration only — for a capability target the actual auth check
- * happens when `capability.invoke` reaches the backend router.
- */
-export interface DeeplinkBus {
-  /** Parse a `xema://` deeplink string. Throws on malformed input. */
-  parse(raw: string): ParsedDeeplink;
-  /**
-   * Navigate the running shell to the deeplink target. The host
-   * implements the actual navigation (biome route push, object detail
-   * open, capability launch, window focus). Rejects if the target cannot
-   * be resolved (e.g. unknown biome / window) — fail-fast, no silent
-   * no-op.
-   */
-  resolve(target: string | ParsedDeeplink): Promise<void>;
-}

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

@@ -1,86 +0,0 @@
-/**
- * Closed sets for the `SystemBus` contract.
- *
- * Every closed domain the SystemBus exposes is a real TypeScript enum so
- * the contract is stable across hosts and serialises predictably. The
- * `ObjectKind` domain deliberately REUSES the kernel's
- * {@link XemaObjectKind} rather than re-declaring a parallel set — see
- * `intents.ts`. The enums below describe SystemBus-specific closed
- * domains that have no kernel equivalent.
- */
-
-/**
- * The kind of target a `xema://` deeplink addresses. The deeplink scheme
- * is intentionally narrower than the full `XemaObjectRef` grammar — a
- * deeplink resolves to a *place in the running shell* (a biome route, an
- * object detail page, a capability launcher, a window), not to every
- * addressable object. New target kinds are added here by one-line kernel
- * change; an unknown target kind is a fail-fast parse error.
- */
-export enum DeeplinkTargetKind {
-  /** `xema://biome/<biomeId>/<route>?<ctx>` — navigate to a biome route. */
-  BiomeRoute = 'biome-route',
-  /** `xema://object/<xema-object-ref>` — open an object's detail surface. */
-  Object = 'object',
-  /** `xema://capability/<capability-ref>?<input>` — launch a capability. */
-  Capability = 'capability',
-  /** `xema://window/<windowId>` — focus an already-open window. */
-  Window = 'window',
-}
-
-/**
- * Window operations the host window manager exposes through
- * `SystemBus.windows`. Closed set — a host that cannot honour an op
- * (e.g. a single-window mobile shell) fails fast rather than silently
- * degrading; the SystemBus never invents a partial window model.
- */
-export enum WindowOp {
-  Open = 'open',
-  Focus = 'focus',
-  Close = 'close',
-  Arrange = 'arrange',
-}
-
-/**
- * Layout arrangements a host may apply to its open windows when
- * `WindowOp.Arrange` is requested. Closed set so the contract is stable
- * across desktop / tiling / tabbed shells.
- */
-export enum WindowArrangement {
-  /** Tile all open windows in a grid. */
-  Tile = 'tile',
-  /** Stack windows with the focused one on top. */
-  Stack = 'stack',
-  /** Cascade windows with a fixed offset. */
-  Cascade = 'cascade',
-  /** Maximise the focused window, hide the rest. */
-  Maximize = 'maximize',
-}
-
-/**
- * The kind of action an intent provides. An intent contributes either a
- * cross-biome *capability* launch ("Send to Slack" → a capability ref)
- * or an in-shell *deeplink* navigation ("Open with Document Buddy" → a
- * biome route). Closed set — these are the only two ways one biome can
- * hand an object to another without importing it.
- */
-export enum ActionRefKind {
-  /** Resolves to a `CapabilityRef` invoked through `capability.invoke`. */
-  Capability = 'capability',
-  /** Resolves to a `xema://` deeplink navigated through `deeplink`. */
-  Deeplink = 'deeplink',
-}
-
-/**
- * The source that contributed a palette entry. The palette is the union
- * of (a) every capability the actor may invoke (sourced from
- * `capability-registry-api`) and (b) every registered cross-biome intent
- * action. This enum tags each entry's provenance so the UI can group /
- * filter and so the host knows which subsystem resolves the entry.
- */
-export enum PaletteEntrySource {
-  /** Backed by a capability descriptor from `capability-registry-api`. */
-  Capability = 'capability',
-  /** Backed by a registered intent (`intents.register`). */
-  Intent = 'intent',
-}

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

@@ -1,93 +0,0 @@
-import type {
-  CapabilityInvokeMeta,
-  CapabilityInvokeResult,
-} from './capability-invoke';
-import type { ParsedDeeplink } from './deeplink';
-import type { WindowArrangement } from './enums';
-import type { PaletteEntry, PaletteQuery } from './palette';
-import type { OpenWindowRequest, WindowId, WindowState } from './windows';
-import type { CapabilityRef } from '@xemahq/kernel-contracts/capability';
-
-/**
- * Framework-agnostic host ports the concrete host implements so the
- * SystemBus sub-buses can be constructed by the framework-agnostic
- * `buildSystemBus` assembler (shipped by this kernel).
- *
- * These ports carry NO React, NO router, NO transport client — they are
- * the seam between "the SystemBus contract" (kernel) and "this host's
- * real backend + shell" (the Next.js App Router host). The assembler wires a
- * `SystemBus` out of `IntentRegistry` + `parseDeeplink` (both already in
- * the kernel) PLUS these three host-supplied ports. A missing port is a
- * wiring bug and MUST fail fast at bridge construction — never a silent
- * no-op.
- *
- * None of these ports authorize. `CapabilityInvoker` relays to the
- * backend capability-router (the single authority); `PaletteSource`
- * indexes an already-actor-scoped registry; `WindowManager` is pure
- * shell orchestration; `DeeplinkResolver` navigates. Policy lives in the
- * backend, full stop.
- */
-
-/**
- * Port the host implements to relay a `capability.invoke` to the backend
- * capability-router. The adapter wraps this into `SystemBus.capability`.
- *
- * The host implementation POSTs the router's invoke endpoint with the
- * Gate-E `ExecutionContext` built from {@link CapabilityInvokeMeta}. It
- * MUST surface a policy denial as the typed result (`output === undefined`
- * + populated `auditId`) and MUST reject on transport failure (fail-fast).
- * It adds NO authorization of its own.
- */
-export interface CapabilityInvoker {
-  invoke<TInput = unknown, TOutput = unknown>(
-    ref: CapabilityRef,
-    input: TInput,
-    meta: CapabilityInvokeMeta,
-  ): Promise<CapabilityInvokeResult<TOutput>>;
-}
-
-/**
- * Port the host implements to source the capability half of the command
- * palette from `capability-registry-api` (already actor-scoped
- * server-side). The intent half is sourced by the adapter from the
- * SystemBus `IntentRegistry`; the adapter merges both behind
- * `SystemBus.palette`.
- *
- * `queryCapabilities` returns ONLY capability-backed entries; the adapter
- * unions them with intent entries and applies the host ranker.
- * `subscribe` fires when the capability source refreshes so a palette
- * overlay can re-query without polling. Returns an unsubscribe fn.
- */
-export interface PaletteSource {
-  queryCapabilities(query: PaletteQuery): Promise<readonly PaletteEntry[]>;
-  subscribe(listener: () => void): () => void;
-}
-
-/**
- * Port the host implements to realise the window plane. The adapter
- * exposes it verbatim as `SystemBus.windows`. Every op maps to a closed
- * {@link WindowArrangement}/`WindowOp`; an op a host cannot honour MUST
- * reject fail-fast rather than silently no-op.
- */
-export interface WindowManager {
-  open(request: OpenWindowRequest): Promise<WindowId>;
-  focus(id: WindowId): Promise<void>;
-  close(id: WindowId): Promise<void>;
-  arrange(arrangement: WindowArrangement): Promise<void>;
-  list(): readonly WindowState[];
-  subscribe(listener: () => void): () => void;
-}
-
-/**
- * Port the host implements to navigate the running shell to a parsed
- * deeplink target. The adapter combines kernel `parseDeeplink` (pure)
- * with this host-supplied `resolve` to build `SystemBus.deeplink`.
- *
- * `resolve` receives the ALREADY-PARSED, validated target (the adapter
- * parses first, so a malformed deeplink fails fast before the host sees
- * it). It MUST reject when the target cannot be resolved (unknown biome /
- * window) — fail-fast, never a silent no-op.
- */
-export interface DeeplinkResolver {
-  resolve(target: ParsedDeeplink): Promise<void>;
-}

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

@@ -1,16 +0,0 @@
-/**
- * SystemBus — the framework-agnostic OS-orchestration contract plane
- * Pure types + a small framework-agnostic runtime
- * ({@link IntentRegistry} + {@link parseDeeplink}). No React, no Vite, no
- * Next.js, no React-Router, no transport client.
- */
-export * from './enums';
-export * from './capability-invoke';
-export * from './intents';
-export * from './intent-registry';
-export * from './deeplink';
-export * from './palette';
-export * from './windows';
-export * from './host-ports';
-export * from './system-bus';
-export * from './system-bus-builder';

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

@@ -1,109 +0,0 @@
-import {
-  parseXemaObjectRef,
-  type XemaObjectKind,
-  type XemaObjectRef,
-} from '@xemahq/kernel-contracts/object';
-
-import { ActionRefKind } from './enums';
-
-import type { IntentBus, IntentRegistration, ResolvedIntent } from './intents';
-
-const VALID_ACTION_KINDS: ReadonlySet<ActionRefKind> = new Set([
-  ActionRefKind.Capability,
-  ActionRefKind.Deeplink,
-]);
-
-function assertValidRegistration(registration: IntentRegistration): void {
-  if (!registration.biomeId) {
-    throw new Error('[xema-ui-kernel] IntentRegistration.biomeId is required.');
-  }
-  for (const action of registration.provides) {
-    if (!VALID_ACTION_KINDS.has(action.kind)) {
-      throw new Error(
-        `[xema-ui-kernel] IntentRegistration from "${registration.biomeId}" ` +
-          `has an ActionRef with unknown kind "${action.kind}". ` +
-          `Expected one of: ${[...VALID_ACTION_KINDS].join(', ')}.`,
-      );
-    }
-  }
-}
-
-/**
- * Framework-agnostic, in-memory implementation of {@link IntentBus}.
- *
- * No React, no router — a plain registry a host can instantiate once and
- * expose through `SystemBus.intents`. Registration order is preserved so
- * `resolve` returns actions deterministically (first-registered first).
- * Re-registering the same `biomeId` REPLACES its prior contribution while
- * keeping its original ordering slot (HMR / re-bootstrap safe).
- *
- * Pure orchestration: it indexes and resolves contributions and performs
- * no authorization. Whether the actor may run a resolved action is decided
- * when the action fires.
- */
-export class IntentRegistry implements IntentBus {
-  /** Insertion-ordered map: biomeId → its registration. */
-  private readonly registrations = new Map<string, IntentRegistration>();
-  private readonly listeners = new Set<() => void>();
-
-  register(registration: IntentRegistration): void {
-    assertValidRegistration(registration);
-    // Map preserves first-insertion order; deleting then setting on an
-    // update would move it to the end, so only delete when truly replacing.
-    this.registrations.set(registration.biomeId, registration);
-    this.notify();
-  }
-
-  unregister(biomeId: string): boolean {
-    const removed = this.registrations.delete(biomeId);
-    if (removed) {
-      this.notify();
-    }
-    return removed;
-  }
-
-  resolve(kind: XemaObjectKind): readonly ResolvedIntent[] {
-    const out: ResolvedIntent[] = [];
-    for (const registration of this.registrations.values()) {
-      if (!registration.handles.includes(kind)) {
-        continue;
-      }
-      for (const action of registration.provides) {
-        out.push({ biomeId: registration.biomeId, action });
-      }
-    }
-    return out;
-  }
-
-  resolveForObject(ref: XemaObjectRef): readonly ResolvedIntent[] {
-    // Fail-fast on a malformed ref rather than returning an empty menu —
-    // a bad ref is a wiring bug, not "no handlers".
-    const { kind } = parseXemaObjectRef(ref);
-    return this.resolve(kind);
-  }
-
-  /**
-   * Insertion-ordered snapshot of every current registration. The command
-   * palette needs every provided action regardless of object kind (unlike
-   * `resolve`, which filters by a single kind), so it reads this snapshot
-   * and flattens `provides`. Returns a defensive shallow copy — callers
-   * MUST NOT mutate the registry through it.
-   */
-  snapshot(): readonly IntentRegistration[] {
-    return [...this.registrations.values()];
-  }
-
-  /** Subscribe to registry changes; returns an unsubscribe fn. */
-  subscribe(listener: () => void): () => void {
-    this.listeners.add(listener);
-    return () => {
-      this.listeners.delete(listener);
-    };
-  }
-
-  private notify(): void {
-    for (const listener of this.listeners) {
-      listener();
-    }
-  }
-}

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

@@ -1,113 +0,0 @@
-import { type ActionRefKind } from './enums';
-
-import type { CapabilityRef } from '@xemahq/kernel-contracts/capability';
-import type {
-  XemaObjectKind,
-  XemaObjectRef,
-} from '@xemahq/kernel-contracts/object';
-
-/**
- * Cross-biome intent registry — the "Open with… / Send to…" plane.
- *
- * A biome registers the object kinds it can *handle* and the actions it
- * *provides*. When the user invokes "Open with… / Send to…" on an object,
- * `intents.resolve(kind)` returns every action any biome registered for
- * that kind. This is how one biome hands an object to another WITHOUT
- * importing it — the macOS "Open With" / Share-Sheet analogy from the
- * platform design.
- *
- * The registry is pure orchestration: it indexes contributions and
- * resolves them. It performs NO authorization — whether the actor may
- * actually run a resolved action is decided when the action fires
- * (`capability.invoke` → backend router for capability actions; the host
- * navigation guard for deeplink actions).
- */
-
-/**
- * A resolvable cross-biome action. Discriminated on {@link ActionRefKind}
- * so a single resolved list can mix capability launches and deeplink
- * navigations. Closed via the enum — there is no third way to hand an
- * object across biomes.
- */
-export type ActionRef =
-  | {
-      readonly kind: ActionRefKind.Capability;
-      /** Stable id, unique within the providing biome. */
-      readonly id: string;
-      /** Human label rendered in the "Send to…" menu. */
-      readonly label: string;
-      /** The capability the action invokes. */
-      readonly capabilityRef: CapabilityRef;
-    }
-  | {
-      readonly kind: ActionRefKind.Deeplink;
-      /** Stable id, unique within the providing biome. */
-      readonly id: string;
-      /** Human label rendered in the "Open with…" menu. */
-      readonly label: string;
-      /**
-       * Deeplink template the action navigates to. The host substitutes
-       * the selected object's ref into the template before navigating
-       * (e.g. `xema://biome/document-buddy/edit?object={ref}`).
-       */
-      readonly deeplinkTemplate: string;
-    };
-
-/**
- * One biome's intent contribution. `handles` is the closed set of object
- * kinds this biome can receive; `provides` is the set of actions it
- * offers for those kinds. Both reference the kernel's {@link XemaObjectKind}
- * so the contract never drifts from the canonical object universe.
- */
-export interface IntentRegistration {
-  /** Biome that owns this registration (provenance + dedup key). */
-  readonly biomeId: string;
-  /** Object kinds this biome can be a target of ("Open with…"). */
-  readonly handles: readonly XemaObjectKind[];
-  /** Actions this biome provides for the handled kinds. */
-  readonly provides: readonly ActionRef[];
-}
-
-/**
- * A resolved intent action for a specific object kind — an {@link ActionRef}
- * tagged with the biome that provides it. Returned by `intents.resolve`.
- */
-export interface ResolvedIntent {
-  readonly biomeId: string;
-  readonly action: ActionRef;
-}
-
-/**
- * The `intents` surface of the SystemBus. Framework-agnostic runtime
- * registry — no React, no router. Hosts drive it at biome bootstrap
- * (`register`) and at "Open with…" menu build time (`resolve`).
- */
-export interface IntentBus {
-  /**
-   * Register a biome's intent contribution. Idempotent per `biomeId`:
-   * re-registering the same biome REPLACES its prior contribution (HMR /
-   * re-bootstrap safe). Fail-fast on a malformed registration (e.g. an
-   * `ActionRef` whose `kind` is outside {@link ActionRefKind}).
-   */
-  register(registration: IntentRegistration): void;
-
-  /**
-   * Remove a biome's intent contribution (admin disable / unregister).
-   * Returns `true` if a registration was removed.
-   */
-  unregister(biomeId: string): boolean;
-
-  /**
-   * Resolve every action any biome registered for `kind`, in stable
-   * registration order. Returns an empty array when no biome handles the
-   * kind — the caller renders an empty "Open with…" menu, never an error.
-   */
-  resolve(kind: XemaObjectKind): readonly ResolvedIntent[];
-
-  /**
-   * Resolve actions for a concrete object ref. Convenience over
-   * `resolve(kind)` that parses the kind out of the `XemaObjectRef` and
-   * is the entry point the "Open with…" menu uses on a selected object.
-   */
-  resolveForObject(ref: XemaObjectRef): readonly ResolvedIntent[];
-}