@xemahq/ui-kernel 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/ui-kernel",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Host-framework-agnostic UI kernel for the Xema OS. Defines the SystemBus orchestration contract (capability.invoke, cross-biome intents, command palette, xema:// deeplinks, window manager) AND the biome-host contract surface (FrontendBiome/FrontendBiomeFactory, HostBridge, the singleton biomeRegistry, session contributions) that every frontend biome composes against. No Vite, Next.js, or React-Router — React itself IS allowed as the shared component model (the contracts traffic in ReactNode/ComponentType and a React context). Concrete host adapters (router/auth/toast wiring) live in separate packages that consume this kernel. The SystemBus is pure orchestration: it never authorizes, the backend capability-router enforces all policy.",
   "keywords": [
     "xema",
@@ -12,16 +12,15 @@
     "deeplink",
     "intents"
   ],
+  "license": "Apache-2.0",
+  "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
   "homepage": "https://docs.xema.dev/biomes",
-  "bugs": {
-    "url": "https://github.com/xema-dev/xema-monorepo/issues"
-  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/xema-dev/xema-monorepo.git",
+    "url": "git+https://github.com/xema-dev/xema-kernel-sdk.git",
     "directory": "packages/ui/xema-ui-kernel"
   },
-  "license": "Apache-2.0",
+  "bugs": "https://github.com/xema-dev/xema-kernel-sdk/issues",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -54,8 +53,10 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^0.462.0",
+    "react-pdf": "^9.1.1",
     "react-resizable-panels": "^4.9.0",
-    "tailwind-merge": "^2.5.4"
+    "tailwind-merge": "^2.5.4",
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.0.0",
@@ -74,7 +75,7 @@
     "prettier": "3.6.2",
     "react": "^18.3.1",
     "typescript": "5.9.3",
-    "@xemahq/kernel-contracts": "^0.14.0"
+    "@xemahq/kernel-contracts": "^0.39.0"
   },
   "exports": {
     ".": {
@@ -101,6 +102,7 @@
   "scripts": {
     "clean": "rm -rf dist",
     "build": "tsc -p tsconfig.json",
+    "test": "echo '[ui-kernel] *.{test,spec} files run under host-web vitest (this package carries no vitest dep by design — see tsconfig exclude). Write tests with vitest; the frontend-bridge sync fails on a node:test file.'",
     "format": "prettier --write \"src/**/*.{ts,tsx}\"",
     "lint": "tsc -p tsconfig.lint.json --noEmit",
     "typecheck": "tsc -p tsconfig.lint.json --noEmit"

package/src/index.ts

@@ -1,3 +1,8 @@
 export * from './lib/system-bus';
 export * from './lib/biome-host';
 export * from './lib/capabilities';
+
+// Guided-capture UX kit (B5). Also available at the `@xemahq/ui-kernel/ui`
+// subpath alongside the rest of the shared UI surface; re-exported here so the
+// capture primitives are reachable from the package root too.
+export * from './ui/capture';

package/src/lib/biome-host/define-web-biome.test.js

@@ -0,0 +1,93 @@
+// Test suite for defineWebBiome's define-time scope/access validation and the
+// chrome default. Runs on Node's native test runner against the COMPILED dist
+// (CommonJS), so the package needs no jest/vitest/ts-jest toolchain — the
+// `test` script builds first, then runs this file with `node --test`.
+//
+// Covered:
+//   1. A `public` page with access `'member'` (or omitted) throws at define time.
+//   2. A `public` + access `'public'` page is accepted; its route carries no
+//      nav item and mounts with access `'public'`.
+//   3. A non-public page declaring access `'public'` throws at define time.
+//   4. `chrome` defaults to `'host'` when a page omits it; `'none'` passes through.
+
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const { defineWebBiome } = require('../../../dist/lib/biome-host/define-web-biome.js');
+
+const load = () => Promise.resolve({ default: () => null });
+const bridge = /** @type {any} */ ({});
+
+test('rejects a public page whose access is not public (member default)', () => {
+  assert.throws(
+    () =>
+      defineWebBiome({
+        id: 'test-biome',
+        displayName: 'Test',
+        pages: [{ slug: 'ext/:id', label: 'Ext', scope: 'public', load }],
+      }),
+    /a 'public' scope page MUST declare access: 'public'/,
+  );
+});
+
+test('rejects a public page with an explicit non-public access tier', () => {
+  assert.throws(
+    () =>
+      defineWebBiome({
+        id: 'test-biome',
+        displayName: 'Test',
+        pages: [
+          { slug: 'ext/:id', label: 'Ext', scope: 'public', access: 'org-admin', load },
+        ],
+      }),
+    /a 'public' scope page MUST declare access: 'public'/,
+  );
+});
+
+test('rejects a non-public page that declares access public', () => {
+  assert.throws(
+    () =>
+      defineWebBiome({
+        id: 'test-biome',
+        displayName: 'Test',
+        pages: [{ slug: 'system/x', label: 'X', access: 'public', load }],
+      }),
+    /access: 'public' is only valid on a 'public' scope page/,
+  );
+});
+
+test('accepts a public + access:public page and emits no nav item', () => {
+  const factory = defineWebBiome({
+    id: 'test-biome',
+    displayName: 'Test',
+    pages: [
+      { slug: 'ext/:id', label: 'Ext', scope: 'public', access: 'public', load },
+    ],
+  });
+  const biome = factory(bridge);
+  assert.equal(biome.routes.length, 1);
+  const route = biome.routes[0];
+  assert.equal(route.path, 'ext/:id');
+  assert.equal(route.access, 'public');
+  assert.equal(route.projectScoped, false);
+  // Public routes never enter the authenticated app rail.
+  assert.equal(biome.navItems.length, 0);
+});
+
+test('chrome defaults to host and none passes through', () => {
+  const factory = defineWebBiome({
+    id: 'test-biome',
+    displayName: 'Test',
+    pages: [
+      { slug: 'system/a', label: 'A', load },
+      { slug: 'system/b', label: 'B', chrome: 'none', load },
+    ],
+  });
+  const biome = factory(bridge);
+  const a = biome.routes.find((r) => r.path === 'system/a');
+  const b = biome.routes.find((r) => r.path === 'system/b');
+  assert.equal(a.chrome, 'host');
+  assert.equal(b.chrome, 'none');
+});

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

@@ -44,8 +44,10 @@ import type {
   FrontendBiome,
   FrontendBiomeFactory,
   NavItemContribution,
+  PageChrome,
   RouteAccess,
   RouteContribution,
+  RouteScope,
 } from './frontend-biome';
 import type { ComponentType } from 'react';
 
@@ -75,11 +77,24 @@ export interface WebBiomePage {
   readonly category?: string;
   /**
    * Route scope. `'org'` (default) mounts at the org root; `'project'` mounts
-   * under `/projects/:projectId`. Maps to {@link RouteContribution.projectScoped}.
+   * under the canonical project-scoped route prefix; `'public'` mounts OUTSIDE
+   * the host's authenticated group (no Keycloak session, no login redirect, no
+   * org switcher). Maps to {@link RouteContribution.projectScoped} for the
+   * authenticated scopes; a `'public'` page MUST also declare
+   * `access: 'public'` (enforced at define time).
+   */
+  readonly scope?: RouteScope;
+  /**
+   * Access tier required to render the route. Defaults to `'member'`. A
+   * `'public'` page (scope `'public'`) MUST set this to `'public'`; a non-public
+   * page MUST NOT — both contradictions are rejected at define time.
    */
-  readonly scope?: 'org' | 'project';
-  /** Access tier required to render the route. Defaults to `'member'`. */
   readonly access?: RouteAccess;
+  /**
+   * Whether the host wraps the page in its application shell. Defaults to
+   * `'host'`; `'none'` renders with no app rail, topbar, or org switcher.
+   */
+  readonly chrome?: PageChrome;
   /** Dynamic import of the page module (`() => import('./pages/X')`). */
   readonly load: () => Promise<{ default: ComponentType<unknown> }>;
   /**
@@ -108,6 +123,47 @@ export interface DefineWebBiomeOptions {
   readonly outputRenderers?: FrontendBiome['outputRenderers'];
 }
 
+/** Default host-shell mode a page renders in when it omits `chrome`. */
+const DEFAULT_PAGE_CHROME: PageChrome = 'host';
+
+/**
+ * Reject the two `scope`/`access` contradictions at define time (module load,
+ * when the biome calls `defineWebBiome(...)` at its top level) — fail fast, do
+ * NOT silently coerce:
+ *
+ *   1. A `public` page with any `access` other than `'public'`: a public route
+ *      is un-authenticated, so a privilege tier is meaningless. The author must
+ *      set `access: 'public'` explicitly (an omitted `access` defaults to
+ *      `'member'`, which is exactly this contradiction).
+ *   2. A non-`public` page declaring `access: 'public'`: `'public'` is the
+ *      no-auth marker; an org/project route is always authenticated.
+ *
+ * `scope` defaults to `'org'` and `access` defaults to `'member'` for the
+ * purpose of this check, matching the emit defaults below.
+ */
+function assertPageScopeAccessLocked(biomeId: string, page: WebBiomePage): void {
+  const scope: RouteScope = page.scope ?? 'org';
+  const access: RouteAccess = page.access ?? 'member';
+  const where = `web biome '${biomeId}' page '${page.slug}'`;
+
+  if (scope === 'public' && access !== 'public') {
+    throw new Error(
+      `${where}: a 'public' scope page MUST declare access: 'public' ` +
+        `(got access: '${access}'). A public route is un-authenticated, so an ` +
+        `authenticated privilege tier is a contradiction. Set access: 'public' ` +
+        `or change the scope.`,
+    );
+  }
+  if (scope !== 'public' && access === 'public') {
+    throw new Error(
+      `${where}: access: 'public' is only valid on a 'public' scope page ` +
+        `(got scope: '${scope}'). '${access}' is the no-auth marker; an ` +
+        `org/project route is always authenticated. Set scope: 'public' or ` +
+        `change the access tier.`,
+    );
+  }
+}
+
 /**
  * Build the `FrontendBiomeFactory` a web biome default-exports. See the
  * module doc-comment for the rationale and an example.
@@ -115,6 +171,13 @@ export interface DefineWebBiomeOptions {
 export function defineWebBiome(
   options: DefineWebBiomeOptions,
 ): FrontendBiomeFactory {
+  // Validate every page's scope/access pairing NOW, at module load, so a
+  // contradiction surfaces the instant the biome module is imported — not
+  // lazily when the host first calls the factory.
+  for (const page of options.pages) {
+    assertPageScopeAccessLocked(options.id, page);
+  }
+
   return () => {
     const navItems: NavItemContribution[] = [];
     const routes: RouteContribution[] = [];
@@ -124,10 +187,14 @@ export function defineWebBiome(
         path: page.slug,
         projectScoped: page.scope === 'project',
         element: lazyRoute(page.load),
+        chrome: page.chrome ?? DEFAULT_PAGE_CHROME,
         ...(page.access ? { access: page.access } : {}),
       });
 
-      if (!page.navHidden) {
+      // Public routes mount OUTSIDE the authenticated group and never belong in
+      // the authenticated app rail — so they contribute no nav item regardless
+      // of `navHidden`. Authenticated pages emit a nav item unless hidden.
+      if (!page.navHidden && page.scope !== 'public') {
         navItems.push({
           id: page.id ?? page.slug,
           label: page.label,

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

@@ -44,8 +44,42 @@ export interface NavItemContribution {
  * declaratively — nav-hide is NOT a security boundary, a deeplink bypasses it.
  * Precedence (least → most privileged): `member` < `org-admin` <
  * `platform-admin`. Defaults to `member` when a route omits the field.
+ *
+ * `public` is NOT a privilege tier — it is the *no-auth* marker: a `public`
+ * route requires no Keycloak session at all and mounts OUTSIDE the host's
+ * 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.
+ */
+export type RouteAccess = 'member' | 'org-admin' | 'platform-admin' | 'public';
+
+/**
+ * Where a route mounts in the host's URL/auth topology. Closed set — adding a
+ * member is a one-line change here (and the single mapping in `defineWebBiome`
+ * plus one resolver partition in the host).
+ *
+ * - `org` — mounts at the org root, inside the authenticated group.
+ * - `project` — mounts under the project-scoped route prefix, inside the
+ *   authenticated group.
+ * - `public` — mounts OUTSIDE the authenticated group; no Keycloak session,
+ *   no login redirect, no org switcher. Locked to `RouteAccess` `'public'`.
  */
-export type RouteAccess = 'member' | 'org-admin' | 'platform-admin';
+export type RouteScope = 'org' | 'project' | 'public';
+
+/**
+ * Whether a page renders wrapped in the host application shell (app rail,
+ * topbar, org switcher) or standalone. Closed set — a new member is a one-line
+ * change here. Defaults to `'host'` when a page omits it.
+ *
+ * - `host` — the default; the host renders its chrome around the page.
+ * - `none` — the host renders the page with NO app rail, topbar, or org
+ *   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.
+ */
+export type PageChrome = 'host' | 'none';
 
 export interface RouteContribution {
   /** React-router path. May include params. */
@@ -63,9 +97,16 @@ export interface RouteContribution {
   readonly projectScoped: boolean;
   /**
    * Access tier required to render this route. The host resolver enforces it
-   * declaratively. Defaults to `'member'` when omitted.
+   * declaratively. Defaults to `'member'` when omitted. `'public'` marks a
+   * no-auth route the host mounts outside its authenticated group.
    */
   readonly access?: RouteAccess;
+  /**
+   * Whether the host wraps this route in its application shell. Defaults to
+   * `'host'` when omitted; `'none'` renders the page with no app rail,
+   * topbar, or org switcher. See {@link PageChrome}.
+   */
+  readonly chrome?: PageChrome;
 }
 
 /**
@@ -182,7 +223,7 @@ export interface OutputRendererContribution {
  *
  * This factory shape keeps biome code free of any direct dependency
  * on host-shell primitives (router, auth client, toast library), which
- * is what allows the same biome package to load into a Vite SPA host
- * today and a Next.js host tomorrow.
+ * is what allows the same biome package to load into one host runtime
+ * today and a different host runtime tomorrow.
  */
 export type FrontendBiomeFactory = (bridge: HostBridge) => FrontendBiome;

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

@@ -5,6 +5,7 @@ import { createContext, useContext, type ReactNode } from 'react';
 import type { CapabilityPort } from '../capabilities';
 import type { SystemBus } from '../system-bus';
 
+import type { I18nSource } from './i18n-port';
 import type { RealtimeSource } from './realtime-port';
 
 /**
@@ -235,6 +236,18 @@ export interface HostBridge {
    * actionable error if a biome uses them before the host wires `bridge.realtime`.
    */
   readonly realtime?: RealtimeSource;
+  /**
+   * Localization port. The HOST injects a concrete {@link I18nSource} backed by
+   * its locale provider (authoritative locale from org/app/user settings +
+   * catalog loading); biomes reach it through the kernel `useT` / `useLocale`
+   * hooks so biome code never imports an i18n library directly — same decoupling
+   * as `navigation` / `realtime`.
+   *
+   * OPTIONAL: a host without localization omits it; the kernel `useT`/`useLocale`
+   * hooks fail fast with an actionable error if a biome uses them before the host
+   * wires `bridge.i18n`.
+   */
+  readonly i18n?: I18nSource;
   /**
    * Error-decoding surface — the canonical user-facing error decoder. Defaults
    * (in the kernel default bridge wiring) to {@link getUserFacingErrorMessage};

package/src/lib/biome-host/i18n-hooks.ts

@@ -0,0 +1,50 @@
+/**
+ * Kernel-side i18n hooks. Biomes call these INSTEAD of importing an i18n library
+ * or the host's locale provider directly, so biome code stays decoupled from the
+ * i18n implementation — the same decoupling `useHostBridge` provides for
+ * navigation / auth / realtime / capabilities.
+ *
+ * Each hook reads the host-injected {@link I18nSource} off `bridge.i18n` and
+ * delegates straight through. The host owns the authoritative locale + catalog
+ * loading; the kernel owns only the contract + this thin delegation.
+ */
+
+import { useHostBridge } from './host-bridge';
+import type { I18nSource, Translator } from './i18n-port';
+
+/**
+ * Resolve the host-injected i18n source, failing fast with an actionable message
+ * if the host has not wired `bridge.i18n`. `bridge.i18n` is an optional port (a
+ * host without localization omits it), so the kernel hooks must not silently
+ * no-op — a biome that calls them expects translated copy.
+ */
+function requireI18n(i18n: I18nSource | undefined): I18nSource {
+  if (!i18n) {
+    throw new Error(
+      'useT/useLocale require an i18n source, but the host has not wired ' +
+        '`bridge.i18n`. The host must provide an I18nSource (locale + catalogs) ' +
+        'on the HostBridge to use kernel i18n hooks.',
+    );
+  }
+  return i18n;
+}
+
+/**
+ * A {@link Translator} for the active locale, scoped to an optional namespace.
+ * Call at render; the returned `t(key, params?)` interpolates `{name}` tokens.
+ *
+ * @example
+ *   const t = useT('radar');
+ *   return <h1>{t('title')}</h1>;              // radar.title
+ *   return <p>{t('greeting', { name })}</p>;   // "Hello, {name}"
+ */
+export function useT(namespace?: string): Translator {
+  const bridge = useHostBridge();
+  return requireI18n(bridge.i18n).useTranslator(namespace);
+}
+
+/** The active BCP-47 locale tag (e.g. `"pt-PT"`) for date/number formatting. */
+export function useLocale(): string {
+  const bridge = useHostBridge();
+  return requireI18n(bridge.i18n).useLocale();
+}

package/src/lib/biome-host/i18n-port.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+
+import { makeTranslator } from './i18n-port';
+
+const en = {
+  title: 'Dashboard',
+  greeting: 'Hello, {name}',
+  radar: { title: 'Radar', empty: 'No leads yet' },
+} as const;
+
+describe('makeTranslator', () => {
+  it('resolves flat and nested dot-path keys', () => {
+    const t = makeTranslator(en);
+    expect(t('title')).toBe('Dashboard');
+    expect(t('radar.title')).toBe('Radar');
+  });
+
+  it('interpolates {name} placeholders', () => {
+    const t = makeTranslator(en);
+    expect(t('greeting', { name: 'Ada' })).toBe('Hello, Ada');
+  });
+
+  it('leaves an unknown placeholder verbatim (visible authoring bug)', () => {
+    const t = makeTranslator({ msg: 'Hi {who}' });
+    expect(t('msg', {})).toBe('Hi {who}');
+  });
+
+  it('applies a namespace prefix', () => {
+    const t = makeTranslator(en, { namespace: 'radar' });
+    expect(t('title')).toBe('Radar');
+    expect(t('empty')).toBe('No leads yet');
+  });
+
+  it('returns the raw key for a missing message (never blank, never throws)', () => {
+    const t = makeTranslator(en);
+    expect(t('does.not.exist')).toBe('does.not.exist');
+  });
+
+  it('falls back message-by-message to the default-locale catalog', () => {
+    const pt = { title: 'Painel' }; // partial locale — no greeting
+    const t = makeTranslator(pt, { fallback: en });
+    expect(t('title')).toBe('Painel'); // primary wins
+    expect(t('greeting', { name: 'Ada' })).toBe('Hello, Ada'); // fallback fills the gap
+  });
+
+  it('coerces numeric params to strings', () => {
+    const t = makeTranslator({ count: '{n} items' });
+    expect(t('count', { n: 3 })).toBe('3 items');
+  });
+});

package/src/lib/biome-host/i18n-port.ts

@@ -0,0 +1,96 @@
+/**
+ * Kernel i18n contract + a framework-free translator core.
+ *
+ * Xema's locale is DATA-driven (per-org / per-app / per-user settings), not
+ * URL-driven, so the kernel deliberately does NOT depend on next-intl / react-
+ * intl. A biome localises its UI through the host-injected {@link I18nSource}
+ * (reached via the `useT` / `useLocale` kernel hooks) exactly the way it reaches
+ * realtime / navigation — the biome never imports an i18n library, and the host
+ * owns catalog loading + the authoritative locale source.
+ *
+ * The {@link makeTranslator} core here is pure and host-agnostic: a host (or a
+ * biome, or a test) builds a `Translator` from a nested-JSON catalog with no
+ * framework in the loop.
+ */
+
+/** Interpolation values for a message's `{name}` placeholders. */
+export type TranslateParams = Readonly<Record<string, string | number>>;
+
+/**
+ * Resolve one message key to a localized string, interpolating `{name}`
+ * placeholders. Missing keys return the key itself (visible, never a throw or a
+ * blank) — the standard i18n contract, not a silent business-logic fallback.
+ */
+export type Translator = (key: string, params?: TranslateParams) => string;
+
+/** A nested message catalog: dot-path keys map to strings (or sub-catalogs). */
+export interface Catalog {
+  readonly [segment: string]: string | Catalog;
+}
+
+export interface MakeTranslatorOptions {
+  /** Prefix every lookup with this namespace path (e.g. `"radar"`). */
+  readonly namespace?: string;
+  /**
+   * Default-locale catalog consulted per-key when the primary catalog lacks a
+   * message — so a partially-translated locale falls back message-by-message
+   * instead of dropping to the raw key.
+   */
+  readonly fallback?: Catalog;
+}
+
+function lookup(catalog: Catalog, path: readonly string[]): string | undefined {
+  let node: string | Catalog | undefined = catalog;
+  for (const segment of path) {
+    if (node === undefined || typeof node === 'string') {
+      return undefined;
+    }
+    node = node[segment];
+  }
+  return typeof node === 'string' ? node : undefined;
+}
+
+function interpolate(message: string, params?: TranslateParams): string {
+  if (!params) {
+    return message;
+  }
+  // Replace `{name}` tokens; an unknown token is left verbatim (visible), never
+  // blanked — a missing param is an authoring bug that should be obvious.
+  return message.replaceAll(/\{(\w+)\}/g, (whole, name: string) =>
+    Object.prototype.hasOwnProperty.call(params, name) ? String(params[name]) : whole,
+  );
+}
+
+/**
+ * Build a {@link Translator} over a catalog. Pure — no React, no framework, no
+ * global state. Resolution order per key: primary catalog → fallback catalog →
+ * the key itself.
+ */
+export function makeTranslator(
+  catalog: Catalog,
+  options?: MakeTranslatorOptions,
+): Translator {
+  const prefix = options?.namespace ? options.namespace.split('.') : [];
+  const fallback = options?.fallback;
+  return (key, params) => {
+    const path = [...prefix, ...key.split('.')];
+    const message =
+      lookup(catalog, path) ?? (fallback ? lookup(fallback, path) : undefined) ?? key;
+    return interpolate(message, params);
+  };
+}
+
+/**
+ * Host-implemented i18n source. The host wires these against its locale provider
+ * (authoritative locale from org/app/user settings + catalog loading); biomes
+ * reach them through the kernel {@link useT} / {@link useLocale} hooks.
+ *
+ * Every method is a React hook (reads locale/catalog context), so it MUST be
+ * called from a component's render.
+ */
+export interface I18nSource {
+  /** A {@link Translator} for the active locale, optionally namespaced. */
+  useTranslator(namespace?: string): Translator;
+  /** The active BCP-47 locale tag (e.g. `"pt-PT"`). */
+  useLocale(): string;
+}

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

@@ -28,6 +28,8 @@ export * from './biome-mode';
 export * from './agent-validation';
 export * from './realtime-port';
 export * from './realtime-hooks';
+export * from './i18n-port';
+export * from './i18n-hooks';
 export * from './errors';
 export * from './response-envelope';
 export * from './use-mutation-with-error-toast';

package/src/lib/biome-host/realtime-port.ts

@@ -73,11 +73,17 @@ export interface RealtimeConnectionState {
 
 /**
  * A server-side scope a connection can subscribe to so it only receives the
- * events for one project or session, rather than the full org firehose. The
- * host's transport reference-counts identical scopes across mounts.
+ * events for one project, session, or app, rather than the full org firehose.
+ * The host's transport reference-counts identical scopes across mounts.
+ *
+ * `app` is the app-surface scope: an external/app-facing biome subscribes to
+ * its app's event stream (delivery is authz-gated server-side by the subject's
+ * app membership). It is value-identical to the server `ScopeKind.app` and the
+ * host transport's `EventScopeOptions` — the kernel union is the last hop to
+ * carry it, so a decoupled/remote biome can type an app subscription.
  */
 export interface RealtimeScope {
-  readonly kind: 'project' | 'session';
+  readonly kind: 'project' | 'session' | 'app';
   readonly id: string;
 }
 

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

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

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

@@ -1,6 +1,6 @@
 /**
  * SystemBus — the framework-agnostic OS-orchestration contract plane
- * (Phase 6b). Pure types + a small framework-agnostic runtime
+ * Pure types + a small framework-agnostic runtime
  * ({@link IntentRegistry} + {@link parseDeeplink}). No React, no Vite, no
  * Next.js, no React-Router, no transport client.
  */

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

@@ -10,7 +10,7 @@ import { ActionRefKind } from './enums';
  * `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).
+ * platform design.
  *
  * The registry is pure orchestration: it indexes contributions and
  * resolves them. It performs NO authorization — whether the actor may

package/src/session-kit/approvals/ApprovalCard.tsx

@@ -1,5 +1,5 @@
 /**
- * The GENERIC approval frame (HANDOFF §6) — identical platform-wide.
+ * The GENERIC approval frame — identical platform-wide.
  *
  * Header: "Approval required" + RiskPill (reused from the kit) + mono
  * capability ref + serif title + summary. Then the biome-supplied

package/src/session-kit/approvals/ApprovalsCenter.tsx

@@ -1,5 +1,5 @@
 /**
- * Approvals Center body (HANDOFF §6) — the cross-portal batch-review list.
+ * Approvals Center body — the cross-portal batch-review list.
  *
  * This is the GENERIC, prop-driven body (toolbar + rows + empty state). It
  * does NOT own the drawer chrome: the host wraps it in its own `Sheet`
@@ -11,7 +11,7 @@
  * portal + biome + quorum and an "Open session" affordance. "Select
  * low-risk" selects every low/medium item; bulk "Approve N" resolves the
  * selection. The row model (`ApprovalCenterItem`) already carries
- * portalId/name/accent so Pillar 4 can group by portal without a reshape.
+ * portalId/name/accent so host portals can group by portal without a reshape.
  */
 import { CapabilityRiskTier } from '@xemahq/kernel-contracts/capability';
 import { useCallback, useState, type ReactElement } from 'react';

package/src/session-kit/approvals/CapabilityApprovalStickyBar.tsx

@@ -1,5 +1,5 @@
 /**
- * Sticky CAPABILITY-approval bar (HANDOFF §6) — pinned above the composer
+ * Sticky CAPABILITY-approval bar — pinned above the composer
  * so a pending capability approval is always actionable without scrolling
  * back to the inline card.
  *