@belonguniverseai/react-sdk 0.1.0

package/dist/embed/dock-state.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Persisted dock UI state (view + size) so a host-page reload — e.g. the one
+ * the terminal agent triggers — reopens the dock on the same view and size.
+ * Side lives in theme prefs (embed/theme.ts) and the active chat session lives
+ * in the stream-state store; this module owns only view + size. Best-effort:
+ * disabled/quota'd storage just means no cross-reload restore.
+ */
+export type DockView = "chat" | "files";
+export type DockSize = "collapsed" | "expanded" | "modal";
+export type DockState = {
+    readonly view: DockView;
+    readonly size: DockSize;
+    readonly widthPx?: number;
+};
+export declare const readDockState: () => DockState | null;
+export declare const writeDockState: (partial: Partial<DockState>) => void;
+/** Single source for the view↔router-path mapping (shared with BelongDock). */
+export declare const viewToPath: (view: DockView) => string;
+export declare const pathToView: (pathname: string) => DockView;
+/**
+ * Decide what a rail view-icon click does. The Chat icon is a toggle: clicking
+ * it while the chat panel is open (expanded/modal) minimizes the dock to the
+ * rail; clicking it while collapsed re-opens chat. Every other click navigates,
+ * expanding a collapsed dock. Pure so it's unit-tested without a dock render.
+ */
+export type ViewClickResult = {
+    readonly action: "minimize";
+} | {
+    readonly action: "navigate";
+    readonly size: DockSize;
+};
+export declare const resolveViewClick: (clickedView: DockView, currentView: DockView, currentSize: DockSize) => ViewClickResult;

package/dist/embed/download-url.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared "fetch an auth'd byte URL and trigger a browser save" flow — one
+ * object-URL anchor lifecycle in one place. Used by the workspace-file download
+ * hook, the Files-panel upload download, and the FilePreview download fallback.
+ *
+ * Returns the HTTP status (0 on a network error) so callers can tailor their
+ * error message (e.g. the workspace 409/404 cases).
+ */
+export declare const downloadUrlToFile: (url: string, filename: string) => Promise<number>;

package/dist/embed/file-type-icon.d.ts

@@ -0,0 +1,29 @@
+/**
+ * File-type → inline SVG icon for the composer's `@`-reference chips (BEL-89).
+ * Returns a lucide-style SVG STRING (not a React node) because the chip is built
+ * imperatively inside the contentEditable editor (see {@link MentionInput}); a
+ * string drops straight into the chip's innerHTML. `stroke="currentColor"` so the
+ * icon inherits the chip's (accent) text color.
+ *
+ * The mapping is deliberately small — a handful of buckets that cover what lands
+ * in a reconciliation workspace (data, code, docs, images, structured config) —
+ * with a generic file as the fallback. Pure.
+ */
+/** lucide icon inner markup (24×24 viewBox), keyed by bucket. */
+declare const ICON_PATHS: {
+    readonly doc: "<path d=\"M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z\"/><path d=\"M14 2v4a2 2 0 0 0 2 2h4\"/><path d=\"M10 9H8\"/><path d=\"M16 13H8\"/><path d=\"M16 17H8\"/>";
+    readonly code: "<path d=\"M10 12.5 8 15l2 2.5\"/><path d=\"m14 12.5 2 2.5-2 2.5\"/><path d=\"M14 2v4a2 2 0 0 0 2 2h4\"/><path d=\"M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z\"/>";
+    readonly table: "<path d=\"M12 3v18\"/><rect width=\"18\" height=\"18\" x=\"3\" y=\"3\" rx=\"2\"/><path d=\"M3 9h18\"/><path d=\"M3 15h18\"/>";
+    readonly data: "<path d=\"M8 3H7a2 2 0 0 0-2 2v5a2 2 0 0 1-2 2 2 2 0 0 1 2 2v5a2 2 0 0 0 2 2h1\"/><path d=\"M16 21h1a2 2 0 0 0 2-2v-5a2 2 0 0 1 2-2 2 2 0 0 1-2-2V5a2 2 0 0 0-2-2h-1\"/>";
+    readonly image: "<rect width=\"18\" height=\"18\" x=\"3\" y=\"3\" rx=\"2\" ry=\"2\"/><circle cx=\"9\" cy=\"9\" r=\"2\"/><path d=\"m21 15-3.086-3.086a2 2 0 0 0-2.828 0L6 21\"/>";
+    readonly file: "<path d=\"M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z\"/><path d=\"M14 2v4a2 2 0 0 0 2 2h4\"/>";
+};
+type IconBucket = keyof typeof ICON_PATHS;
+/** The bucket name for a path's extension — useful for tests + labels. Pure. */
+export declare const fileTypeBucket: (path: string) => IconBucket;
+/**
+ * Inline SVG markup for a path's file-type icon. `width/height: 1em` so it scales
+ * with the chip font; `currentColor` so it takes the chip's text color. Pure.
+ */
+export declare const fileTypeIconSvg: (path: string) => string;
+export {};

package/dist/embed/format-bytes.d.ts

@@ -0,0 +1,2 @@
+/** Human-readable byte size for file rows: "612 B" / "80 KB" / "1.2 MB". */
+export declare const formatBytes: (bytes: number) => string;

package/dist/embed/global.d.ts

@@ -0,0 +1,79 @@
+import { BelongGlobal, BelongInitInput, RouteHandler, UiActionHandler } from '../types/public.ts';
+type AgentGrantConfig = {
+    readonly provider: string;
+    readonly scopeExternalId: string | null;
+    /** URL search param to read the scope from LIVE (SPA workspace switches). */
+    readonly scopeUrlParam: string | null;
+};
+type GlobalState = {
+    apiBaseUrl: string | null;
+    mode: "dock" | "inline";
+    container: HTMLElement | null;
+    routeHandlers: Map<string, RouteHandler>;
+    uiActionHandlers: Map<string, UiActionHandler>;
+    visible: boolean;
+    agentGrant: AgentGrantConfig | null;
+    /** Whether the active workspace has a Belong panel (BEL-77). */
+    panelEnabled: boolean;
+};
+/**
+ * Whether the active workspace has a Belong panel. The host signals this per
+ * workspace via `init({ panelEnabled })`; omitting it defaults to `true` so
+ * existing embeds keep their panel. When `false`, the dock renders nothing —
+ * workspaces without a configured panel don't show the assistant (BEL-77).
+ */
+export declare const peekPanelEnabled: () => boolean;
+/**
+ * The host's agent-grant context (provider + scope), or null when the embed
+ * didn't configure one — the consent surface stays hidden then.
+ */
+export declare const peekAgentGrantConfig: () => AgentGrantConfig | null;
+/**
+ * The CURRENT scope: the live URL param when tracking is configured (the
+ * host SPA rewrites it on workspace switch without a reload), else the
+ * static value from init. Null = no scope → grant surface hidden.
+ */
+export declare const resolveAgentGrantScope: () => {
+    provider: string;
+    scopeExternalId: string;
+} | null;
+export type MountFn = (input: {
+    readonly container: HTMLElement;
+    readonly apiBaseUrl: string;
+}) => void;
+export type UnmountFn = () => void;
+export declare const registerMounters: (input: {
+    readonly mount: MountFn;
+    readonly unmount: UnmountFn;
+}) => void;
+export declare const peekGlobalState: () => Readonly<GlobalState>;
+/**
+ * Read-only accessors for the dispatch layer (see
+ * `stream/ai-sdk-part-renderers.tsx`). Renderers call these instead of
+ * casting `window.belong` so the type boundary stays honest — the host
+ * never sees these names, but the SDK's internal renderers do.
+ */
+export declare const peekRouteHandler: (routeName: string) => RouteHandler | null;
+export declare const peekUiActionHandler: (actionName: string) => UiActionHandler | null;
+/**
+ * Internal accessor for the renderers: the dispatch layer reads the
+ * registered route + UI-action handlers off `window.belong.__*` so it
+ * can call them when a `data-navigation` or `data-ui-action` stream
+ * part arrives. Public API stays the registration verbs only.
+ */
+export type BelongGlobalWithInternals = BelongGlobal & {
+    readonly __routeHandlers: ReadonlyMap<string, RouteHandler>;
+    readonly __uiActionHandlers: ReadonlyMap<string, UiActionHandler>;
+};
+/**
+ * Populate the SDK's module-singleton config from a host's init input — the
+ * shared CONFIG step of both embed paths. The `window.belong` global's `init`
+ * (script-tag embed) calls this then sets the initial token, mounts, and starts
+ * browser control; the React component (`component/BelongWidget.tsx`) calls it
+ * then owns its own mount via `createShadowMount` + `createPortal`. It
+ * deliberately does NOT mount, set a token, or start the browser-control
+ * channel — those side effects belong to the caller.
+ */
+export declare const applyInitConfig: (input: BelongInitInput) => Promise<void>;
+export declare const createBelongGlobal: () => BelongGlobalWithInternals;
+export {};

package/dist/embed/locale.d.ts

@@ -0,0 +1,18 @@
+import { BelongLocale } from '../types/public.ts';
+export type Locale = BelongLocale;
+export declare const DEFAULT_LOCALE: Locale;
+/** Set the host/tenant default locale (from `init`); user choice still wins. */
+export declare const configureLocale: (locale: Locale | undefined) => void;
+export declare const subscribeLocale: (listener: () => void) => (() => void);
+/** The effective locale: user choice, else host default, else English. */
+export declare const peekLocale: () => Locale;
+/** The user's explicit choice, or null when none (host default applies). */
+export declare const peekUserLocale: () => Locale | null;
+/** Persist the user's language choice and notify subscribers. */
+export declare const setUserLocale: (locale: Locale) => void;
+/** Drop the user override (back to the host default / English). */
+export declare const clearUserLocale: () => void;
+/** `useSyncExternalStore` hook — the effective locale, re-rendering on change. */
+export declare const useLocale: () => Locale;
+/** Test-only: clear listeners + host default and re-seed the user choice. */
+export declare const __resetLocaleForTest: () => void;

package/dist/embed/logo.d.ts

@@ -0,0 +1 @@
+export declare const isSafeLogoDataUrl: (value: string) => boolean;

package/dist/embed/mic-press.d.ts

@@ -0,0 +1,27 @@
+import { VoiceStatus } from './voice-bus.ts';
+/** Release within this window of the press counts as a tap (latch), not a hold. */
+export declare const TAP_TOGGLE_MS = 300;
+export type MicPressState = {
+    readonly phase: "idle";
+} | {
+    readonly phase: "held";
+    readonly downAtMs: number;
+} | {
+    readonly phase: "latched";
+};
+export declare const MIC_PRESS_IDLE: MicPressState;
+/** What the caller must do on the voice bus (start/stop/cancel Capture). */
+export type MicPressAction = "start" | "stop" | "cancel" | "none";
+export type MicPressDecision = {
+    readonly next: MicPressState;
+    readonly action: MicPressAction;
+};
+/**
+ * Decide the next state + voice-bus action for a mic button press event.
+ *
+ * @param event  "down" (pointerdown) or "up" (pointerup / pointercancel).
+ * @param nowMs  Caller-injected clock reading (Date.now()).
+ * @param state  The machine state carried between events (a ref in React).
+ * @param status The CURRENT voice-bus status, read at event time.
+ */
+export declare const micPress: (event: "down" | "up", nowMs: number, state: MicPressState, status: VoiceStatus) => MicPressDecision;

package/dist/embed/onboarding-prefs.d.ts

@@ -0,0 +1,52 @@
+/**
+ * First-run onboarding persistence — "has this user already been onboarded, and
+ * at which version".
+ *
+ * We store a single integer: the onboarding VERSION the user last completed
+ * (0 = never). The dock offers onboarding while that number is below
+ * {@link CURRENT_ONBOARDING_VERSION}. Bumping the constant re-onboards everyone
+ * — and a future version can branch to a single new-feature spotlight instead
+ * of replaying the whole flow.
+ *
+ * Persistence sits behind a swappable {@link OnboardingGateway} PORT so the
+ * default per-browser localStorage adapter can later be replaced — with zero UI
+ * change — by a per-user backend flag (read once from `/v1/config`, written via
+ * a `POST`). Until then localStorage matches every other SDK pref (theme,
+ * voice, dock-state, stream cursor).
+ *
+ * localStorage is a perimeter: the value is zod-validated on read and any junk
+ * (corrupted JSON, wrong shape, storage disabled) degrades to "never onboarded".
+ */
+/**
+ * The onboarding flow version. Increment when the flow changes enough that
+ * already-onboarded users should see it again.
+ */
+export declare const CURRENT_ONBOARDING_VERSION = 1;
+/**
+ * The persistence port. The default adapter is per-browser localStorage; a
+ * server-backed adapter can be swapped in at bootstrap via
+ * {@link configureOnboardingGateway} without touching any component.
+ */
+export type OnboardingGateway = {
+    /** The highest onboarding version the user has completed (0 = never). */
+    getCompletedVersion: () => number;
+    /** Persist the completed onboarding version. */
+    setCompletedVersion: (version: number) => void;
+};
+/**
+ * Replace the persistence adapter (e.g. a server-backed per-user flag at
+ * bootstrap). The default is per-browser localStorage.
+ */
+export declare const configureOnboardingGateway: (next: OnboardingGateway) => void;
+/** The highest onboarding version the user has completed (0 = never). */
+export declare const readOnboardingCompletedVersion: () => number;
+/** Persist that the user finished onboarding at the given version. */
+export declare const markOnboardingCompleted: (version?: number) => void;
+/**
+ * True when this user should be offered the first-run flow — i.e. they have not
+ * completed the current onboarding version. Returning users read `false` and go
+ * straight to the working surface.
+ */
+export declare const shouldOfferOnboarding: () => boolean;
+/** Test-only: restore the default localStorage gateway. */
+export declare const __resetOnboardingGatewayForTest: () => void;

package/dist/embed/onboarding-steps.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Locale-INDEPENDENT tour structure: each step's stable id, the DOM anchor it
+ * spotlights, and the preferred tooltip side. The localized title/body live in
+ * `copy.ts` (keyed by step id) and are merged in by `buildTourSteps`.
+ *
+ * Each anchor is an EXISTING stable hook in the dock (a `data-role` /
+ * `data-testid` already on the control), so the tour needs no new product
+ * chrome. A step whose anchor is absent at runtime (feature gated, rail
+ * collapsed) is skipped gracefully by the engine.
+ */
+export type TourStepPlacement = "top" | "bottom" | "left" | "right";
+export type TourStepId = "autonomy" | "commands" | "voice" | "sessions";
+/** The locale-independent part of a tour step. */
+export type TourStepDef = {
+    readonly id: TourStepId;
+    /** CSS selector resolved INSIDE the dock root to find the highlighted control. */
+    readonly anchor: string;
+    /** Preferred tooltip side relative to the anchor; the engine clamps to fit. */
+    readonly placement: TourStepPlacement;
+};
+/** A fully-resolved (localized) tour step the coach-mark engine renders. */
+export type TourStep = TourStepDef & {
+    readonly title: string;
+    readonly body: string;
+};
+export declare const TOUR_STEP_DEFS: readonly TourStepDef[];
+export declare const TOUR_STEP_COUNT: number;

package/dist/embed/onboarding-store.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Onboarding flow state — a tiny external store (the same `useSyncExternalStore`
+ * shape as `stream-state-store.ts`).
+ *
+ * The flow is a small state machine:
+ *
+ *   idle ──startOnboarding──▶ welcome ──beginTour──▶ tour ──┐
+ *     ▲                          │                    │ next │
+ *     └──(reset, tests only)     │ skip               │ prev │
+ *                                ▼                    ▼      │
+ *                              done ◀──complete/skip──◀──────┘
+ *
+ * `complete`/`skip` stamp the persisted completed version (so a returning user
+ * never sees it again). The component layer GATES the auto-start on
+ * {@link shouldOfferOnboarding}; this store only models the in-session phase, so
+ * a manual "replay" can re-enter `welcome` even for an already-onboarded user.
+ */
+export type OnboardingPhase = "idle" | "welcome" | "tour" | "done";
+export type OnboardingState = {
+    readonly phase: OnboardingPhase;
+    /** Active tour step index (meaningful only while `phase === "tour"`). */
+    readonly stepIndex: number;
+};
+export declare const subscribeOnboarding: (listener: () => void) => (() => void);
+export declare const peekOnboarding: () => OnboardingState;
+/** Enter the welcome card (also the "replay tour" entry point). */
+export declare const startOnboarding: () => void;
+/** Welcome → first spotlight step. */
+export declare const beginTour: () => void;
+/** Advance to the next step, or finish the tour past the last step. */
+export declare const nextStep: () => void;
+/** Step back one (no-op at the first step). */
+export declare const prevStep: () => void;
+/** Dismiss the flow early; marks the user as onboarded so it won't re-offer. */
+export declare const skipOnboarding: () => void;
+/** Finish the flow; marks the user as onboarded. */
+export declare const completeOnboarding: () => void;
+/** Test-only: drop listeners and return to `idle`. */
+export declare const __resetOnboardingStoreForTest: () => void;

package/dist/embed/plan-auto-open.d.ts

@@ -0,0 +1,8 @@
+/** Pure decision for "auto-open the Plan view now?". Opens once per NEW plan
+ *  key; respects a user who navigated away during the current run, but a
+ *  brand-new plan (different key) re-opens regardless. */
+export declare const shouldAutoOpenPlan: (input: {
+    readonly planKey: string | null;
+    readonly lastOpenedKey: string | null;
+    readonly userNavigatedAway: boolean;
+}) => boolean;

package/dist/embed/plan-decision.d.ts

@@ -0,0 +1,10 @@
+import { PlanData } from '../stream/belong-data-parts.ts';
+export type PlanDecision = "approve" | "reject" | "feedback";
+/** Classify a final voice transcript while a plan is awaiting a decision. */
+export declare const interpretPlanDecision: (transcript: string) => PlanDecision;
+/**
+ * Spoken announcement for a freshly proposed plan: title, summary, step
+ * count, then the decision invitation. An empty summary is skipped (no
+ * dangling pause); the step count is pluralized for natural speech.
+ */
+export declare const formatPlanAnnouncement: (plan: PlanData) => string;

package/dist/embed/plan-intent.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Pure detector for "the user wants to enter plan mode" from a composer draft.
+ * Conservative by design: a false positive would silently swallow a normal
+ * message. Only an explicit `/plan` command or a tight set of switch phrases
+ * count; richer requests ("make a plan to migrate X") fall through to a normal
+ * send and rely on the agent proposing a plan (which flips mode separately).
+ *
+ * Regexes are kept deliberately simple (no nested alternations) to stay within
+ * sonarjs/regex-complexity limits and avoid backtracking risks.
+ */
+export type PlanIntent = {
+    readonly kind: "switch";
+} | {
+    readonly kind: "switch_and_send";
+    readonly text: string;
+};
+export declare const detectPlanIntent: (raw: string) => PlanIntent | null;

package/dist/embed/portal-container.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Portal container context.
+ *
+ * Radix overlays (DropdownMenu, Tooltip, Popover, …) portal to
+ * `document.body` by default. When the dock is mounted inside a Shadow DOM for
+ * style isolation (the production embed — see `embed/bootstrap.ts`), that
+ * default would drop the overlay into the host's light DOM, OUTSIDE the shadow
+ * root, where none of our injected CSS reaches — so it would render unstyled.
+ *
+ * This context carries the element those portals should mount into instead: a
+ * node that lives INSIDE the shadow root, so overlays inherit the dock's
+ * isolated styles. The default is `null`, which means "no override" — Radix
+ * falls back to `document.body`. That's exactly right for the dev SPA and
+ * Storybook, where there is no shadow root and the styles live in the document
+ * head.
+ */
+export declare const PortalContainerContext: import('react').Context<HTMLElement | null>;
+/**
+ * The element Radix portals should mount into, or `null` to use Radix's
+ * default (`document.body`). Pass straight through to a Radix `*.Portal`'s
+ * `container` prop — Radix treats `null`/`undefined` as "use the default".
+ */
+export declare const usePortalContainer: () => HTMLElement | null;

package/dist/embed/presets.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { BelongThemeBrand, BelongThemePalette, PartialBelongTheme, PresetName } from '../types/public.ts';
+/** Zod validator for a preset name at perimeters (localStorage, host API).
+ *  MUST list the same members as `PresetName` in `@sdk/types/public.ts`. */
+export declare const PRESET_NAME_SCHEMA: z.ZodEnum<["belong", "simetrik", "custom"]>;
+export declare const BELONG_LIGHT_PALETTE: BelongThemePalette;
+export declare const BELONG_DARK_PALETTE: BelongThemePalette;
+export declare const BELONG_FONT_FAMILY = "\"Inter\", -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Oxygen, Ubuntu, Cantarell, sans-serif";
+export declare const BELONG_RADIUS = "12px";
+export declare const BELONG_BRAND: BelongThemeBrand;
+export declare const SIMETRIK_BRAND: BelongThemeBrand;
+export declare const SIMETRIK_LIGHT_PALETTE: BelongThemePalette;
+export declare const SIMETRIK_DARK_PALETTE: BelongThemePalette;
+export declare const PRESETS: Record<PresetName, PartialBelongTheme>;
+export declare const DEFAULT_PRESET: PresetName;
+/** True when `hostname` is a Simetrik domain (prod / stage / beta). */
+export declare const isSimetrikHost: (hostname: string) => boolean;
+/** The default preset for a host: `simetrik` on a Simetrik domain, else belong. */
+export declare const defaultPresetForHost: (hostname: string) => PresetName;
+export declare const getPreset: (name: PresetName) => PartialBelongTheme;
+export declare const listPresets: () => readonly {
+    name: PresetName;
+    label: string;
+}[];
+/** A brand is co-branded "by Belong" when it is not Belong itself. Drives the
+ *  header/login tagline and the Powered-by-Belong footer. Comparison is exact
+ *  (case-sensitive); built-in preset brand names use title-case ("Belong",
+ *  "Simetrik"). */
+export declare const isCoBrandedByBelong: (brand: BelongThemeBrand) => boolean;

package/dist/embed/session-record.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+export type SessionRecordStore<T extends string> = {
+    /**
+     * The persisted value for `sessionId`, or the fallback when nothing is
+     * stored, the stored record belongs to a different session, or the value is
+     * corrupted / from an older build.
+     */
+    read: (sessionId: string) => T;
+    /** Persist `value` as the choice for `sessionId` (replaces any prior record). */
+    write: (sessionId: string, value: T) => void;
+};
+/**
+ * Build a per-session localStorage store under `storageKey`, persisting the
+ * value under `valueField` and validating reads against `valueSchema`.
+ */
+export declare const createSessionRecordStore: <T extends string>(storageKey: string, valueField: string, valueSchema: z.ZodType<T>, fallback: T) => SessionRecordStore<T>;

package/dist/embed/shadow-mount.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shadow-DOM mount + style isolation for the dock — shared by BOTH embed paths:
+ * the script-tag bootstrap (`embed/bootstrap.ts`, which `createRoot`s into the
+ * returned app node) and the React component (`component/BelongWidget.tsx`,
+ * which `createPortal`s into it).
+ *
+ * In the production embed the dock mounts inside a Shadow DOM and the compiled
+ * CSS is injected INTO that shadow root, so the host's global stylesheet can't
+ * cascade into the dock (the bug where Simetrik's `button {…}` rules turned our
+ * suggestion pills into circles) and our preflight can't leak out onto the host
+ * page. The CSS string is stashed on a global at module-eval by the build's
+ * `css-injected-by-js` hook (see `vite.config.ts` / `vite.component.config.ts`).
+ * When that string is absent — the dev SPA, Storybook, and source-resolved
+ * hosts, where Vite injects styles into the document head and there is no shadow
+ * root — we fall back to a plain light-DOM mount.
+ */
+export declare const splitPropertyRules: (css: string) => {
+    properties: string;
+    rest: string;
+};
+export type ShadowMount = {
+    /** The node a React root / portal renders the dock into. */
+    readonly appRoot: HTMLElement;
+    /** The promoted node Radix overlays portal into (pass as `portalContainer`). */
+    readonly portalRoot: HTMLElement;
+};
+/**
+ * Build the dock's mount targets inside `host`. Production (compiled CSS present
+ * on the global) → attach a shadow root, inject the style-isolated CSS
+ * (`@property` rules to `document.head`, the rest scoped to `:host`), and place
+ * the app + portal nodes inside it. Dev / Storybook / source-resolved hosts (CSS
+ * null) → a light-DOM mount whose styles come from the host page's own `<head>`.
+ *
+ * The CALLER owns `host` (creates + removes it); this only fills it and returns
+ * the React app root + the Radix portal container.
+ */
+export declare const createShadowMount: (host: HTMLElement) => ShadowMount;

package/dist/embed/slash-commands.d.ts

@@ -0,0 +1,49 @@
+import { CommandSummary, SkillSummary } from '../api/skills.ts';
+/** The group label workspace-tree commands render under in the slash menu. */
+export declare const COMMAND_GROUP = "Commands";
+/**
+ * Map a workspace-tree command onto the `SkillSummary` shape the picker
+ * renders — display only. At submit time a command token is deliberately NOT
+ * matched by {@link parseSlashSubmission} (commands aren't in the skills
+ * list), so the draft falls through and posts as RAW text: the worker-side
+ * Agent SDK parses the leading-slash message against its command registry.
+ */
+export declare const commandOptions: (commands: readonly CommandSummary[]) => readonly SkillSummary[];
+/**
+ * Client-side commands offered in the slash menu next to the skills. They
+ * reuse the `SkillSummary` shape so the picker (filter/rank/render) treats
+ * both uniformly; `group: "Built-in"` distinguishes them from skill groups.
+ * A builtin shadows a same-named skill at submit time (builtins are checked
+ * first), so keep these names out of the skill namespace.
+ */
+export declare const BUILTIN_COMMANDS: readonly SkillSummary[];
+export type BuiltinCommandName = "compact";
+/**
+ * Recognize a submitted draft as a built-in command. Strict by design: the
+ * draft (already trimmed by the caller) must be EXACTLY `/<name>` — trailing
+ * text means "not a builtin", so `/compact please` falls through to the
+ * skill/message handling rather than silently dropping the user's words.
+ */
+export declare const parseBuiltinCommand: (draft: string) => BuiltinCommandName | null;
+/**
+ * The slash menu's option list: built-ins merged ahead of the skills, ranked
+ * by {@link filterSkills} (prefix matches first; input order — built-ins
+ * before skills — breaks ties within each bucket).
+ */
+export declare const filterSlashOptions: (skills: readonly SkillSummary[], query: string) => readonly SkillSummary[];
+/** The token after a leading `/`, or null when not in slash-command mode. */
+export declare const slashQuery: (draft: string) => string | null;
+/**
+ * Parse a submitted draft that begins with a picked skill token (`/<name> …`).
+ * Returns the matched skill and the remaining message text when `<name>` is one
+ * of the known skills, else null (so a normal message — or a slash token that
+ * is not a real skill — is sent unchanged). The skill is carried structurally
+ * to the backend; the leading `/<name>` is never sent as text (it collides with
+ * the Claude Agent SDK runtime's own slash-command parser).
+ */
+export declare const parseSlashSubmission: (draft: string, skills: readonly SkillSummary[]) => {
+    readonly skill: string;
+    readonly text: string;
+} | null;
+/** Name-prefix matches first, then other name/description substring matches. */
+export declare const filterSkills: (skills: readonly SkillSummary[], query: string) => readonly SkillSummary[];

package/dist/embed/theme.d.ts

@@ -0,0 +1,40 @@
+import { CSSProperties } from 'react';
+import { BelongTheme, BelongThemePalette, PartialBelongTheme, PresetName } from '../types/public.ts';
+export declare const DEFAULT_THEME: BelongTheme;
+export declare const peekTheme: () => BelongTheme;
+export declare const subscribeTheme: (listener: () => void) => (() => void);
+export declare const setTheme: (partial: PartialBelongTheme) => void;
+/** Switch the active theme style. Built-in presets render their pure palette;
+ *  the Custom style overlays the user's accent/cssVars stash. */
+export declare const applyPreset: (name: PresetName) => void;
+export declare const peekPreset: () => PresetName;
+/**
+ * Set (or clear, with `null`) the Custom-style accent. Updates the stash and
+ * switches to the Custom style so the change is immediately visible.
+ */
+export declare const setAccentColor: (color: string | null) => void;
+export declare const peekAccent: () => string | null;
+/** Replace the Custom-style CSS-vars stash (pass `{}` to clear) + select Custom. */
+export declare const setCustomCssVars: (vars: Record<string, string>) => void;
+export declare const peekCustomCssVars: () => Record<string, string>;
+/** Picks the active palette out of the theme based on `mode`, applying any accent override. */
+export declare const activePalette: (theme: BelongTheme) => BelongThemePalette;
+/** Pick a readable foreground (near-black or white) for text on `color`. */
+export declare const contrastForeground: (color: string) => string;
+/** Recolor only the brand/primary family with `accent`; leave bg/text/border. */
+export declare const applyAccent: (palette: BelongThemePalette, accent: string) => BelongThemePalette;
+export declare const toggleThemeMode: () => void;
+export declare const toggleThemeSide: () => void;
+/**
+ * Project the **active** palette into a `style`-compatible record of
+ * CSS custom properties. Setting them on the dock root cascades into
+ * every descendant.
+ */
+export declare const themeToCssVars: (theme: BelongTheme) => Record<string, string>;
+/**
+ * Inline style for Radix surfaces that portal OUTSIDE the dock root
+ * (DropdownMenu / Popover content), which therefore can't inherit the dock
+ * root's projected CSS vars. Carries the vars plus explicit fallbacks so the
+ * surface paints themed even when portaled into the shadow container.
+ */
+export declare const themeToPortalStyle: (theme: BelongTheme) => CSSProperties;

package/dist/embed/universe-origin.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The host page's canonical origin — the BEL-111 `universeOrigin` component
+ * prop. The dock's cross-origin navigation rebasing (`browser/spa-navigate.ts`)
+ * and the cross-origin block in `browser/dom-bridge.ts` treat this as "the host
+ * app's origin": a URL on a DIFFERENT origin is foreign (blocked / left for a
+ * full load), and same-app env variants (prod↔stage) are rebased onto it.
+ *
+ * A single source so every branch agrees — reading `globalThis.location`
+ * directly in some branches and a configured value in others would rebase
+ * inconsistently. When unset it defaults to the live page origin, so the
+ * script-tag embed and any host that never passes `universeOrigin` behave
+ * exactly as before.
+ */
+/** Register the host's canonical origin. Null / empty clears it (→ live origin). */
+export declare const setUniverseOrigin: (origin: string | null | undefined) => void;
+/** The configured universe origin string, or the live page origin when unset. */
+export declare const getUniverseOrigin: () => string;
+/**
+ * The universe origin as a `URL` (for `.origin` + `.hostname`), or null when it
+ * isn't a parseable absolute origin (e.g. a sandboxed `"null"` origin). Callers
+ * treat null as "can't tell" and fall back to leaving the URL untouched /
+ * refusing a client-side nav — matching the pre-existing safe defaults.
+ */
+export declare const getUniverseUrl: () => URL | null;

package/dist/embed/use-workspace-file-download.d.ts

@@ -0,0 +1,16 @@
+/**
+ * useWorkspaceFileDownload — shared download behavior for the workspace-file
+ * surfaces (the dock's Files panel and the embed WorkspaceTree). Both render a
+ * download button per file; this hook owns the `downloading` indicator state
+ * and the binary-download flow so the two components don't duplicate it.
+ *
+ * The binary download uses a plain fetch + object-URL anchor (a typed Hono
+ * `$get` can't stream a Blob with the bearer header cleanly), mirroring
+ * documents.tsx's upload. Error strings are surfaced via the caller's
+ * `onError` so each component keeps its own `error` state (also used by its
+ * `load()` flow).
+ */
+export declare function useWorkspaceFileDownload(apiBaseUrl: string, onError: (message: string | null) => void): {
+    download: (path: string) => Promise<void>;
+    downloading: string | null;
+};

package/dist/embed/voice/audio-forwarder.worklet.d.ts

@@ -0,0 +1,22 @@
+/**
+ * AudioWorklet forwarder — runs on the audio render thread and posts each
+ * input render quantum's first channel back to the main thread as a copied
+ * Float32Array. The main thread converts those samples to PCM16 (see
+ * `mic-capture.ts`).
+ *
+ * Bundling note: the SDK ships as a Shadow-DOM bundle, and a `?worker&url`
+ * / `new URL(...)` worklet import does not reliably survive `vp build`. So
+ * instead of a separate worklet entry, the processor source lives here as a
+ * template string and a Blob URL is created lazily at runtime
+ * (`audioForwarderWorkletUrl()`). The URL is cached so repeated mic starts
+ * reuse one Blob, and it is never created at import time — a non-browser /
+ * test context can import this module without touching `URL`/`Blob`.
+ */
+/**
+ * Lazily create (and cache) a Blob URL for the `audio-forwarder` worklet
+ * module. Safe to call repeatedly — the first call builds the Blob, later
+ * calls return the cached URL.
+ *
+ * @returns A `blob:` URL suitable for `audioWorklet.addModule(...)`.
+ */
+export declare function audioForwarderWorkletUrl(): string;