@xemahq/ui-kernel 0.5.0 → 0.6.1

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

@@ -24,11 +24,12 @@ export * from './biome-registry';
 export * from './session-contributions';
 export * from './session-profiles';
 export * from './host-sources';
-export * from './nav';
 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.
  *

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

@@ -1,5 +1,5 @@
 /**
- * Obligation chip + quorum dots (HANDOFF §6).
+ * Obligation chip + quorum dots.
  *
  * `Obligation` renders one obligation as a chip: host-supplied icon (via
  * `renderIcon` from the stable `ObligationIcon` key) + label + optional

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

@@ -1,5 +1,5 @@
 /**
- * Scoped approval bodies (HANDOFF §6) — the biome-supplied typed detail
+ * Scoped approval bodies — the biome-supplied typed detail
  * that renders UNDER the generic frame.
  *
  * `ScopedBody` is an EXHAUSTIVE switch over `ApprovalScopeKind`. A scope

package/src/session-kit/approvals/approval-model.ts

@@ -1,6 +1,5 @@
 /**
- * Approval primitive — generic frame model + scoped-body payloads
- * (Pillar 3 of the Xema Portals design handoff; HANDOFF §6).
+ * Approval primitive — generic frame model + scoped-body payloads.
  *
  * The approval is the runtime face of a kernel policy decision: a
  * capability call returns `allow | deny | needs_approval`
@@ -9,7 +8,7 @@
  * (risk pill + capability ref + obligations + quorum + actions); each
  * biome supplies a typed `scope` body for rich detail — the same
  * generic-frame + biome-body pattern as the in-chat widget registry
- * (HANDOFF §3.2) and the preview-tab kinds (HANDOFF §5).
+ * and the preview-tab kinds.
  *
  * This module REUSES the kernel contracts rather than redefining them:
  *   • `CapabilityRiskTier` (low/medium/high/critical) — risk pill + accent
@@ -24,7 +23,7 @@ import type { CapabilityRiskTier } from '@xemahq/kernel-contracts/capability';
 import type { PolicyObligationKind } from '@xemahq/kernel-contracts/policy';
 
 /**
- * Closed set of biome-supplied scoped-body kinds (HANDOFF §6). This is the
+ * Closed set of biome-supplied scoped-body kinds. This is the
  * approval analogue of `ChatWidgetKind` — a typed, versioned catalogue of
  * rich bodies that render UNDER the generic frame. The renderer
  * (`ScopedBody`) switches on `kind`; an unknown kind fails SAFE to a
@@ -165,7 +164,7 @@ export interface ApprovalRequest {
  * "allow once" vs "approve & remember" distinction is a UI affordance on
  * top of the same `Approved` decision (the remember flag is carried
  * separately when the backend supports it); both resolve the suspended
- * call. The denied/override-rationale path is DEFERRED (HANDOFF §6).
+ * call. The denied/override-rationale path is not yet implemented.
  */
 export enum ApprovalDecision {
   Approved = 'approved',
@@ -175,14 +174,14 @@ export enum ApprovalDecision {
 /**
  * A pending approval as it appears in the cross-portal Approvals Center —
  * the request plus the portal/session context it was raised in. The
- * portal fields are first-class so Pillar 4 (Portals) can batch and group
+ * portal fields are first-class so the Portals surface can batch and group
  * approvals across portals without reshaping this model.
  */
 export interface ApprovalCenterItem {
   /** Mirrors `request.id`; kept distinct so a Center may track its own row id. */
   readonly id: string;
   readonly request: ApprovalRequest;
-  /** Portal the approval was raised in (Pillar 4 cross-portal context). */
+  /** Portal the approval was raised in (cross-portal context). */
   readonly portalId?: string;
   readonly portalName?: string;
   /** Portal accent token (`var(--p-*)`) for the row glyph; optional. */
@@ -194,7 +193,7 @@ export interface ApprovalCenterItem {
 
 /** True when the tier always demands an explicit Approve (no allow-once). */
 export function isExplicitApprovalTier(tier: CapabilityRiskTier): boolean {
-  // `critical` and `high` are explicit-only (HANDOFF §6: critical always
+  // `critical` and `high` are explicit-only (critical always
   // explicit; high uses the warning accent and skips allow-once-remember).
   return tier === 'critical' || tier === 'high';
 }

package/src/session-kit/approvals/index.ts

@@ -1,6 +1,6 @@
 /**
  * `@xemahq/ui-kernel/session-kit` approvals — the generic approval
- * primitive (Pillar 3 of the Xema Portals design handoff; HANDOFF §6).
+ * primitive.
  *
  * Generic frame + scoped bodies + sticky bar + Approvals Center. Models on
  * the kernel contracts (`CapabilityRiskTier`, `PolicyObligationKind`) and

package/src/session-kit/approvals/obligation-display.ts

@@ -1,5 +1,5 @@
 /**
- * Obligation → display metadata map (HANDOFF §6).
+ * Obligation → display metadata map.
  *
  * Covers ALL NINE obligation kinds in the kernel closed taxonomy —
  * `audit`, `redact-secrets`, `require-runner-kind`,

package/src/session-kit/approvals/risk-accent.ts

@@ -1,6 +1,6 @@
 /**
  * Risk-tier → colour expressions for the approval frame's accent rail and
- * the sticky bar (HANDOFF §6). RiskPill owns the PILL styling; this map is
+ * the sticky bar. RiskPill owns the PILL styling; this map is
  * the matching surface accent (foreground / soft background / border) the
  * frame and bar paint with. Both read the SAME kernel `CapabilityRiskTier`
  * enum so the pill and the rail can never disagree on a tier's colour.

package/src/session-kit/combobox/Combobox.tsx

@@ -1,5 +1,5 @@
 /**
- * Generic searchable picker (HANDOFF §7). Use it wherever a closed set
+ * Generic searchable picker. Use it wherever a closed set
  * is selected (agents, models, skills/tools, …).
  *
  * - Shows a search field when `items.length > searchThreshold` (default

package/src/session-kit/display/MessageTurn.tsx

@@ -2,7 +2,7 @@
  * A single message turn. User turns render a right-aligned soft bubble;
  * agent turns render a thin gutter + role caption + flowing body.
  *
- * The body is rendered by `renderMarkdown` when supplied (Pillar 2 wires
+ * The body is rendered by `renderMarkdown` when supplied (host shells wire
  * the host's full `MarkdownRenderer` here) and falls back to the kit's
  * built-in `MD` otherwise — so the kit is self-contained but never
  * forces its tiny renderer on a host that has a richer one.

package/src/session-kit/display/TokenMeter.tsx

@@ -1,6 +1,6 @@
 /**
  * Token/cost meter — input & output token counts plus a running dollar
- * cost. Used both inside the ContextHeader and (in Pillar 2) absolute
+ * cost. Used both inside the ContextHeader and (in host shells) absolute
  * top-right of the composer.
  */
 import { SessionSkin } from '../lib/enums';

package/src/session-kit/index.ts

@@ -1,7 +1,7 @@
 /**
  * `@xemahq/ui-kernel/session-kit` — the thin, prop-driven generic
  * component substrate for agent-session surfaces and the Portals
- * chrome (Pillar 1 of the Xema Portals design handoff).
+ * chrome.
  *
  * Everything here is presentational and icon-agnostic: components take
  * data + host-supplied icon nodes and emit inline-styled markup against
@@ -9,7 +9,7 @@
  * subscriptions, no framework imports — so the same kit renders inside
  * the host shell and inside a biome's own surfaces.
  *
- * Pillar 2 consumes these via `import { … } from '@xemahq/ui-kernel/session-kit'`.
+ * Host shells consume these via `import { … } from '@xemahq/ui-kernel/session-kit'`.
  */
 
 // Closed-set enums + the authoritative status-dot map.
@@ -39,6 +39,6 @@ export * from './display/TodoChecklist';
 export * from './combobox/Combobox';
 export * from './combobox/use-click-outside';
 
-// Approvals primitive (Pillar 3 — generic frame + scoped bodies + sticky
+// Approvals primitive — generic frame + scoped bodies + sticky
 // bar + cross-portal Approvals Center).
 export * from './approvals';

package/src/session-kit/lib/enums.ts

@@ -17,7 +17,7 @@ export enum ToolStatus {
 }
 
 /**
- * The four authoritative transcript status-dot states (HANDOFF §3.1).
+ * The four authoritative transcript status-dot states.
  * `Narration` is the hollow dot used by a `say` event — it is not a
  * tool, so it sits outside `ToolStatus`.
  */

package/src/session-kit/lib/status-dot.ts

@@ -1,5 +1,5 @@
 /**
- * Authoritative transcript status-dot colour map (HANDOFF §3.1).
+ * Authoritative transcript status-dot colour map.
  *
  *   pending / running → amber, PULSING   (--warning)
  *   done / success    → green            (--success)

package/src/session-kit/primitives/RiskPill.tsx

@@ -4,7 +4,7 @@
  * string union. Critical renders an optional caller-supplied alert icon
  * (the kit carries no icon dependency, matching the rest of ui-kernel).
  *
- * Risk → colour (HANDOFF §6):
+ * Risk → colour:
  *   low      → ink / muted
  *   medium   → --info
  *   high     → --warning

package/src/ui/branding/app-branding-provider.tsx

@@ -0,0 +1,146 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// AppBrandingProvider — the runtime branding applier
+//
+// Takes a kernel `BrandingConfig` (plus an optional per-sub-tenant override)
+// and APPLIES it at runtime:
+//
+//   • writes `primaryColor` → `--app-primary-color` and every `cssTokens`
+//     entry → `--<key>` as CSS custom properties on its OWN wrapper element,
+//     so they cascade ONLY to the app subtree — never onto
+//     `document.documentElement`, so an app's branding cannot leak into the
+//     host chrome;
+//   • exposes `displayName` / `logoUrl` / `primaryColor` to children through
+//     context (`useAppBranding`) for a branded header to render.
+//
+// Every value crosses `sanitize.ts` first: an unsafe CSS value or a
+// non-`http(s)` logo URL is dropped, never written raw.
+//
+// This is the reusable half of Wave 8.4 — a biome imports it from
+// `@xemahq/ui-kernel/ui`, like `useIsMobile` / `Sheet`.
+// ═══════════════════════════════════════════════════════════════════════════
+import * as React from 'react';
+
+import type { BrandingConfig } from '@xemahq/kernel-contracts/app-runtime';
+
+import { cn } from '../cn';
+
+import {
+  sanitizeCssCustomPropertyName,
+  sanitizeCssValue,
+  sanitizeLogoUrl,
+} from './sanitize';
+
+/** CSS custom property carrying the app's resolved primary brand color. */
+export const APP_PRIMARY_COLOR_VAR = '--app-primary-color';
+
+/** Values a branded header needs — sanitized, safe to render. */
+export interface AppBrandingContextValue {
+  readonly displayName: string;
+  readonly logoUrl?: string;
+  readonly primaryColor?: string;
+}
+
+const AppBrandingContext = React.createContext<AppBrandingContextValue | null>(
+  null,
+);
+
+/**
+ * Resolved branding for the nearest enclosing {@link AppBrandingProvider}.
+ * Throws when used outside one — a header that assumes branding must not
+ * silently render an unbranded surface.
+ */
+export function useAppBranding(): AppBrandingContextValue {
+  const ctx = React.useContext(AppBrandingContext);
+  if (ctx === null) {
+    throw new Error(
+      'useAppBranding must be used within an <AppBrandingProvider>.',
+    );
+  }
+  return ctx;
+}
+
+export interface AppBrandingProviderProps {
+  /** The app's base branding (from the App definition / release). */
+  readonly branding: BrandingConfig;
+  /**
+   * Per-sub-tenant override, resolved from `AppRoleBinding.tenantId`. Each
+   * present field shadows the base; absent fields fall through to `branding`.
+   * Optional — apps with no sub-tenant branding pass nothing.
+   */
+  readonly tenantBranding?: Partial<BrandingConfig>;
+  /** Extra classes for the wrapper element. */
+  readonly className?: string;
+  readonly children: React.ReactNode;
+}
+
+/**
+ * Merge base branding with an optional per-sub-tenant override (override wins
+ * per field), then sanitize every applied value.
+ */
+function resolveBranding(
+  branding: BrandingConfig,
+  tenantBranding: Partial<BrandingConfig> | undefined,
+): {
+  readonly context: AppBrandingContextValue;
+  readonly cssVars: Record<string, string>;
+} {
+  const displayName = tenantBranding?.displayName ?? branding.displayName;
+  const rawPrimary = tenantBranding?.primaryColor ?? branding.primaryColor;
+  const rawLogo = tenantBranding?.logoUrl ?? branding.logoUrl;
+  const cssTokens = { ...branding.cssTokens, ...tenantBranding?.cssTokens };
+
+  const primaryColor =
+    rawPrimary !== undefined
+      ? (sanitizeCssValue(rawPrimary) ?? undefined)
+      : undefined;
+  const logoUrl = sanitizeLogoUrl(rawLogo);
+
+  const cssVars: Record<string, string> = {};
+  if (primaryColor !== undefined) {
+    cssVars[APP_PRIMARY_COLOR_VAR] = primaryColor;
+  }
+  for (const [rawKey, rawValue] of Object.entries(cssTokens)) {
+    const name = sanitizeCssCustomPropertyName(rawKey);
+    const value = sanitizeCssValue(rawValue);
+    if (name !== null && value !== null) {
+      cssVars[name] = value;
+    }
+  }
+
+  return {
+    context: { displayName, logoUrl, primaryColor },
+    cssVars,
+  };
+}
+
+/**
+ * Scopes an app's branding to its subtree. Renders a wrapper element carrying
+ * the CSS custom properties inline, so they cascade to the app content and
+ * nowhere else. On unmount the element (and its properties) simply disappear —
+ * no cleanup, no global mutation.
+ */
+export function AppBrandingProvider({
+  branding,
+  tenantBranding,
+  className,
+  children,
+}: AppBrandingProviderProps): React.ReactElement {
+  const { context, cssVars } = React.useMemo(
+    () => resolveBranding(branding, tenantBranding),
+    [branding, tenantBranding],
+  );
+
+  return (
+    <AppBrandingContext.Provider value={context}>
+      <div
+        data-app-branding=""
+        className={cn(className)}
+        // Custom properties are not part of `React.CSSProperties`; the cast is
+        // the standard way to set `--*` vars inline.
+        style={cssVars as React.CSSProperties}
+      >
+        {children}
+      </div>
+    </AppBrandingContext.Provider>
+  );
+}