4. App tier — @get-bb/plugin-sdk/app

The browser entry. It runs only through the import map (app.mjs leaves @get-bb/plugin-sdk/app bare; packages/plugin-build/src/externals.ts). It re-exports React types only; React itself comes from the map (07 §2.1, I8). Everything here is a line in packages/plugin-sdk/api.lock.json (27 values, 82 types). Slot names are §5; this section is the mechanism. Source of truth: packages/plugin-sdk/src/app/{index,define-plugin-app,slots,hooks}.ts over packages/kernel-ui/src/**; where spec 07 and the built kernel differ, the "As built" column wins (04-kernel-as-built D16–D18).

4.1 definePluginApp and setup(app, config)

Rules: every register/inject needs literal name, kind, scope (the collector throws otherwise). A registration into a name no live occupant declares fails the plugin's load (SlotAuthorityError, "use slots.inject"). Commit is atomic per plugin: any failure restores the previous generation in routes, commands, kinds, slots and preferences (kernel-ui README "Failed reload rollback").

4.2 app.slots.register

register<Name, O extends RegisterOptions<Name>>(options: O & { name: Name }, component: SlotComponentInput<SlotComponentProps<Name, O>>): void. kind/scope are narrowed by the merged SlotMap entry for Name; an unmerged name accepts the open unions and the component's props take kind/scope from the literal options (SDK README deviation 9).

// contracts.ts (published):  declare module "@get-bb/plugin-sdk/app" {
//   interface SlotMap { "notes.panel": { kind: "list"; scope: "root"; props: { heading: string } } } }
app.slots.register(
  { name: "root", kind: "single", scope: "root", priority: -1000,
    children: { "notes.panel": { kind: "list", scope: "root", props: z.object({ heading: z.string() }) } } },
  ({ renderSlot, Original }) => <main>{renderSlot("notes.panel", { heading: "Notes" })}</main>,   // renderSlot typed to "notes.panel"
);
app.slots.register({ name: "notes.panel", kind: "list", scope: "root", order: 10 }, (p: SlotComponentProps<"notes.panel">) => <b>{p.heading}</b>);

The root registration at priority: -1000 is a fallback for a composition or test without ui-shell: in the product ui-shell (priority 0) wins root, this occupant never mounts, and the plugin's panel reaches the screen as a pane kind plus a route (§4.5, "How a page appears").

4.3 Slot component props

SlotComponentProps<Name, O> = SlotPropsOf<Name> & ScopeProps<scope> & { renderSlot: RenderSlot<children of O> } & ({ store: StoreFace<T> } when O.store) & ({ Original: SlotComponent } unless kind is list) & ({ selected: unknown } when kind is chain). Never ctx, the container, or a query client (07 §5.7, A5); services arrive through hooks (§4.9).

Mount: every occupant instance renders under PluginContext {pluginId, generation} → the kit's PortalScopeProvider → release registry → CrashBoundary → Suspense (fallback = the owner fallback) → <div data-bb-plugin-root data-bb-plugin="<id>" class="contents">. React key = instance key ${name}|${key ?? ""}|${pluginId}|${generation}|${scopeKey} (+ |<mode>), so a new generation or a mode change remounts (07 §5.8; SlotMount.tsx).

4.4 Arbitration and pins

One rule, owned by kernel-core (02 §3.4 order(candidates, pin)): replaces → user pin → priority desc → sorted plugin id asc. kernel-ui adds only the crash-latch filter in front of it and never ranks on its own (12 U1). It applies to single, each key of keyed, the evaluation order of chain, and every pane/tab kind (LayoutStore.paneKinds_/tabKinds_). list slots skip arbitration: all occupants, order asc then plugin id, when(owner) and only filtered.

4.5 Routes, panes, tabs

URL = the focused pane (Q21). The kernel has no routes of its own; / belongs to ui-shell (D16). A pane is { kind, state }; a route maps a path to a pane kind; a dock holds a flat tab list (no splits inside a dock).

How a page appears. KernelRoot renders NoRoutePage when no route matches the URL and otherwise the root slot, renderSlot("root", {}, { fallback: <LoadingPage/> }) (boot/KernelRoot.tsx); root is the kernel's a priori single slot (create-ui-kernel.ts), and arbitration (§4.4) picks one occupant. In the product that occupant is ui-shell's ShellRoot (priority 0, §5.1): it renders shell.main, whose occupant LayoutHost mounts kernel-ui's LayoutRoot, and LayoutRoot mounts every pane of the layout tree through SlotMount with the pane kind's winning component (PaneHost → usePaneMount → kindChainHead, layout/LayoutRoot.tsx; an unknown kind renders MissingKindPane). So a plugin page in the product is a pane kind plus a route (hello-slot: kind hello, path /hello), and the shell draws it. LayoutRoot is not exported from @get-bb/plugin-sdk/app, so a plugin's own root occupant cannot host panes: it renders only what it returns. A root registration at priority: -1000 mounts only when nothing outranks it — createAppHarness without shell, or a composition without ui-shell — and then the routed pane does not appear; render the same panel from both places, as hello-slot does (HelloPanel is both the root occupant and the hello pane component). ui-shell/pages (§5.14) with the page pane kind (§5.6, route /plugins/:pluginId/:pageId/*) is the shell's registry for a page with shell chrome; the slice has no registrants.

Kernel-registered pane commands (bindable, when: { all: ["splitActive"], none: ["modalOpen"] }): pane.focus.1…8 (Mod+N desktop, Control+N web-mac, Mod+Shift+N web-other), pane.focus.previous, pane.focus.next, pane.close (Mod+Shift+X), pane.maximize.toggle (Mod+Shift+E). thread.open and pane.act are ui-shell's (07 §4.7, R10; layout-commands.ts).

4.6 Client commands and keybindings

Ids are flat and open (thread.new, pane.focus.*); one executor plus a before-interceptor stack per id (02 §6.3 on the browser side). The bus is kernel-ui's synchronous registry; the kernel does not mirror it onto the container bus (D17). Hub {t: "command"} frames reach commands.run directly. An executor that throws yields an error result, never a timeout.

4.7 Preferences

A browser facade over 02's kernel/preferences; there is no kernel-ui/preferences service. Keys are static <pluginId>/<name> (^[a-z0-9][a-z0-9-]*\/[a-zA-Z0-9][a-zA-Z0-9._-]*$, PreferencesFacade KEY_RE); per-instance values are maps under one key. Preference key rule (identical in §1.3 and §3.7): the key is the full <pluginId>/<name> string in every tier, with name in ^[a-zA-Z][a-zA-Z0-9_-]*$ (the app's regex is wider, the server tier's is not); each tier that reads the key defines it itself with the same schema and default (a server define does not make the key readable in the browser, nor the reverse — usePreference of a key this bundle did not define throws read before its define); contributes.settings[name] is optional for code — it adds the Settings form row and the required fast path, and nothing checks that its default equals the code default. hello-slot defines hello-slot/theme in both server.ts and app.tsx from one THEME_KEY and DEFAULT_THEME exported by contracts.ts.

4.8 Data: defineQuery, defineMutation, defineRowStore, defineStore

Module-level definitions that bind to the kernel lazily from a component; every .use()/.useHandle() is a hook (D18). The kernel owns the cache, the realtime subscriptions and invalidation (A5). client in the callbacks is the BbClient (kernel-ui/src/data/client.ts): { serverUrl: string; query<T = JsonValue>(serviceId: string, method: string, input: JsonValue): Promise<T>; mutate<T = JsonValue>(serviceId, method, input: JsonValue): Promise<T> } — query = GET /api/v1/<service>/<method>?input=<json>, mutate = POST, X-BB-Client on every request, an error envelope → KernelError. T is a statement, not a parse: hello-slot parses the body with the contract's output schema. I is unconstrained; a method whose input is z.strictObject({}) takes {} (second example below).

export const notesQuery = defineQuery<{ pinnedOnly: boolean }, Note[]>({
  key: "list", fetch: (input, client) => client.query("notes-fixture/notes", "list", input),
  invalidateOn: [{ name: "notes-fixture/note.changed", key: null }, { entity: "thread", id: () => threadId }],
});
const q = notesQuery.use({ pinnedOnly: false });          // { status, data, error, refetch, … }
const handle = notesQuery.useHandle();                     // a hook too; use `handle.invalidate()` in an event handler

// no input: the cache entry is `<pluginId>/total:{}`
export const totalQuery = defineQuery<Record<string, never>, Total>({
  key: "total", fetch: (input, client) => client.query("word-count/counter", "total", input),
  invalidateOn: [{ name: "word-count/counted", key: null }],
});
const total = totalQuery.use({});

4.9 useService and errors

// hello-slot app.tsx: tolerate service_unavailable after every other hook has run, so the hook order stays stable
function useGreeter(): GreeterHandle | null {
  try { return useService(greeter); } catch (error) {
    if (error instanceof KernelError && error.code === "service_unavailable") return null;
    throw error;                                   // a Suspense promise or a real bug
  }
}

4.10 Every app export (27 values, 20 hooks)

4.11 Components and the import map

bb plugin build marks every import-map specifier external; the browser resolves them through the map core inlines into index.html (hashed, immutable URLs). Bundles load with import("<jsUrl>?h=<hash>").

IconName (@bb/ui, packages/ui/src/primitives/icon/icon.tsx) is a core name or an extended name; PluginIconName is <pluginId>/<name>. The 46 core names (CORE_ICON_MAP, on the boot path): AlertCircle, AlertTriangle, Archive, Bug, Check, ChevronDown, ChevronLeft, ChevronRight, Circle, CircleCheck, CircleQuestion, CircleX, ClosePluginPane, CloseThreadPane, Code, ComputerTerminal01, Copy, Download, Edit, Folder, FolderExport, FolderGit, FolderPlus, Info, ListTodo, Loading, MessageQuestion, MessageCirclePlus, MessageSquarePlus, MessageSquare, MoreHorizontal, PanelLeft, Search, SectionAdd, Settings, SlidersHorizontal, Spinner, Target, Terminal, Toolbox, ToolCase, Trash2, UserRoundPlus, Workflow, X, Zap. The 95 extended names (EXTENDED_ICON_NAMES, icon-registry.ts) load with the first route that needs them; ICON_NAMES lists both. <Icon name> takes IconName | PluginIconName; plugin glyphs enter the namespace through registerIcons(pluginId, map), and no kernel-ui or app code in the slice calls it for contributes.icons.named, so a <pluginId>/<name> value (hello-slot's hello-slot/wave) has no renderer today — use a core or extended name. app.panes.register icon and app.tabs.register icon take the same IconName (layout-store.ts). Props: Button = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "title"> & { variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link"; size?: "default" | "sm" | "lg" | "icon"; asChild?: boolean } (primitives/button.tsx); Input = React.ComponentProps<"input"> (primitives/input.tsx); both forward their ref, and every other primitive passes its HTML or Radix props through the same way (packages/ui/src/primitives/<name>.tsx is the prop reference).

CSS rules (07 §2.5, §5.8, R34; packages/plugin-build/src/scope-plugin-utilities.ts): the build rewrites the compiled utilities layer to :where([data-bb-plugin="<id>"]) .cls, :where([data-bb-plugin="<id>"]).cls (both arms; never @scope). Authored CSS (global.css/app.css) must root every selector at [data-bb-plugin-effect="<own id>"], including selectors nested in @media/@supports; anything else fails the build. Stamp data-bb-plugin-effect="<contributorId>" on DOM you paint for another plugin (ui-editor-tiptap decorations) so the contributor's sheet reaches it. Overlays portaled to body carry data-bb-plugin through usePortalScopeProps. @bb/ui/ui.css and the app's theme.css are the host sheets; a plugin never imports Tailwind itself. Manifest contributes.tokens values must derive from var(--canvas|--ink|<theme color>) or a color-mix of those.

4.12 Bundle and load lifecycle

bb plugin build writes dist/app.mjs, dist/app.css, dist/app.contributions.json (and meta.json with sdkMajor: 1, uiMajor: 1, per-file digests). app.contributions.json has no optional field: declares{} (each child slot: kind, scope, JSON-Schema props, boot, overlay, fallback, owner), registers[] (name, kind, scope, key, priority, order, hasStore), injects[], routes[], panes[] (kind, priority, hasDock), tabs[] (kind, priority, persist incl. "dynamic", singleton, closable), commands[] (id, defaultShortcut, desktopOnly, menu), preferences[] (key, scope, default, schema). It is the app tier's only claim; contributes.slots in the manifest is informational and cross-checked at build (D9).

4.13 Types index