@xemahq/ui-kernel 0.1.4

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

@@ -0,0 +1,200 @@
+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}` as `xema://${string}`,
+      };
+    }
+    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

@@ -0,0 +1,86 @@
+/**
+ * Closed sets for the `SystemBus` contract (Phase 6b).
+ *
+ * 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

@@ -0,0 +1,96 @@
+import type { CapabilityRef } from '@xemahq/kernel-contracts/capability';
+import type {
+  CapabilityInvokeMeta,
+  CapabilityInvokeResult,
+} from './capability-invoke';
+import type { PaletteEntry, PaletteQuery } from './palette';
+import type {
+  OpenWindowRequest,
+  WindowId,
+  WindowState,
+} from './windows';
+import type { WindowArrangement } from './enums';
+
+/**
+ * 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: import('./deeplink').ParsedDeeplink): Promise<void>;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * SystemBus — the framework-agnostic OS-orchestration contract plane
+ * (Phase 6b). 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

@@ -0,0 +1,106 @@
+import {
+  parseXemaObjectRef,
+  type XemaObjectKind,
+  type XemaObjectRef,
+} from '@xemahq/kernel-contracts/object';
+import { ActionRefKind } from './enums';
+import type {
+  ActionRef,
+  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 as ActionRef).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

@@ -0,0 +1,109 @@
+import type { CapabilityRef } from '@xemahq/kernel-contracts/capability';
+import type { XemaObjectKind, XemaObjectRef } from '@xemahq/kernel-contracts/object';
+import { ActionRefKind } from './enums';
+
+/**
+ * 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
+ * plan-of-record (§12.3).
+ *
+ * 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[];
+}

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

@@ -0,0 +1,77 @@
+import type { CapabilityRef } from '@xemahq/kernel-contracts/capability';
+import { PaletteEntrySource } from './enums';
+
+/**
+ * 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;
+}