bb.layout

bb.layout supplies the app shell, shared panel frame, modal layer, status area, and theme system.

Purpose

The plugin claims the kernel-owned bb.app.root surface. Its winner declares all bb.layout.* child surfaces.

The plugin owns shell chrome and panel dock rules. Domain plugins own the content that the shell shows.

Surfaces

The active root claim declares the six bb.layout.* child surfaces. A root replacement can keep these IDs.

The first-party manifest makes the graph and service edges static:

{
  "id": "bb.layout",
  "claims": [
    { "surface": "bb.app.root" },
    { "surface": "bb.layout.sidebar" },
    { "surface": "bb.layout.theme", "key": "bb.layout.default" },
    { "service": "bb.layout.themes", "version": "1.0.0" }
  ],
  "surfaces": [
    { "id": "bb.layout.sidebar", "kind": "single", "replaceable": true, "contract": "./contracts#LayoutSidebarProps", "stability": "stable" },
    { "id": "bb.layout.main", "kind": "single", "replaceable": true, "contract": "./contracts#LayoutMainProps", "stability": "stable" },
    { "id": "bb.layout.statusbar", "kind": "list", "contract": "./contracts#LayoutStatusItemRegistration", "stability": "stable" },
    { "id": "bb.layout.panels", "kind": "list", "contract": "./contracts#LayoutPanelRegistration", "stability": "stable" },
    { "id": "bb.layout.modals", "kind": "list", "contract": "./contracts#LayoutModalRegistration", "stability": "stable" },
    { "id": "bb.layout.theme", "kind": "keyed", "replaceable": true, "contract": "./contracts#LayoutThemeDefinition", "stability": "stable" }
  ],
  "services": [
    { "id": "bb.layout.themes", "kind": "single", "replaceable": true, "defaultProvider": "bb.layout", "stability": "stable" }
  ],
  "requires": [{ "service": "bb.storage", "range": "^1" }],
  "optional": [{ "service": "bb.realtime", "range": "^1" }],
  "watched": [{ "service": "bb.plugins", "range": "^1" }]
}

Root, sidebar, and main

The kernel passes only stable window and route facts to the root. The Layout plugin owns all view state.

import type { ComponentType } from "react";

export interface AppRootProps {
  route: LayoutRoute;
  viewport: LayoutViewport;
  safeArea: { top: number; right: number; bottom: number; left: number };
}

export interface LayoutRoute {
  path: string;
  projectId: string | null;
  threadId: string | null;
}

export interface LayoutViewport {
  width: number;
  height: number;
  compact: boolean;
  desktopWindow: boolean;
}

export interface LayoutSidebarProps {
  route: LayoutRoute;
  viewport: LayoutViewport;
  panels: readonly LayoutPanelEntry[];
  statusItems: readonly LayoutStatusItemEntry[];
  closeCompactSidebar(): void;
}

export interface LayoutMainProps {
  route: LayoutRoute;
  viewport: LayoutViewport;
  panels: LayoutPanelController;
  modals: LayoutModalController;
}

A single winner also gets a typed Original component. The kernel remounts the winner after a winner change.

The root error boundary stays outside the plugin tree. A failed root claim returns to the default Layout claim.

The first-party root uses the child surfaces directly:

function LayoutRoot(props: AppRootProps) {
  return (
    <LayoutFrame>
      <Surface id="bb.layout.sidebar" props={sidebarProps(props)} />
      <Surface id="bb.layout.main" props={mainProps(props)} />
      <SurfaceList id="bb.layout.statusbar" props={statusbarProps(props)} />
      <PanelDock surface="bb.layout.panels" />
      <ModalLayer surface="bb.layout.modals" />
    </LayoutFrame>
  );
}

Status bar

The status bar is a list surface. Each entry supplies data or a small component.

export interface LayoutStatusItemRegistration {
  id: string;
  order?: number;
  align?: "start" | "end";
  title: string;
  icon?: string;
  component?: ComponentType<LayoutStatusItemProps>;
  onActivate?(props: LayoutStatusItemProps): void | Promise<void>;
}

export interface LayoutStatusItemProps {
  compact: boolean;
  route: LayoutRoute;
  panels: LayoutPanelController;
  modals: LayoutModalController;
}

export interface LayoutStatusItemEntry {
  pluginId: string;
  registration: LayoutStatusItemRegistration;
}

The shell renders a data-only entry as a standard icon button. The shell supplies its tooltip and focus style.

The default sidebar can show selected status entries in its footer. This placement does not change contract ownership.

Panels

bb.layout.panels stores panel declarations. A declaration does not open its panel.

export type LayoutPanelDock = "sidebar" | "right" | "bottom";
export type LayoutPanelFrame = "padded" | "flush";

export interface LayoutPanelRegistration<TState = JsonValue, TTarget = JsonValue> {
  id: string;
  title: string;
  icon?: string;
  component: ComponentType<LayoutPanelProps<TState, TTarget>>;
  preferredDock: LayoutPanelDock;
  allowedDocks?: readonly LayoutPanelDock[];
  frame?: LayoutPanelFrame;
  instances?: "single" | "multiple";
  persistent?: boolean;
  target?: StandardSchemaV1<TTarget>;
  navigation?: {
    path: string;
    order?: number;
    accessory?: ComponentType;
  };
  headerContent?: ComponentType<LayoutPanelHeaderProps>;
}

export interface LayoutPanelEntry {
  id: string; // `<pluginId>/<registrationId>`
  pluginId: string;
  registration: LayoutPanelRegistration;
}

export interface LayoutPanelProps<TState = JsonValue, TTarget = JsonValue> {
  panelId: string;
  instanceId: string;
  dock: LayoutPanelDock;
  state: TState | null;
  target: { sequence: number; value: TTarget } | null;
  focused: boolean;
  controller: LayoutPanelController;
}

export interface LayoutPanelHeaderProps {
  panelId: string;
  instanceId: string;
  dock: LayoutPanelDock;
  close(): void;
}

export interface LayoutPanelOpenOptions<TState = JsonValue, TTarget = JsonValue> {
  instanceKey?: string;
  title?: string;
  state?: TState;
  target?: TTarget;
  dock?: LayoutPanelDock;
  focus?: boolean;
}

export interface LayoutPanelController {
  open<TState, TTarget>(
    panelId: string,
    options?: LayoutPanelOpenOptions<TState, TTarget>,
  ): string;
  focus(instanceId: string): boolean;
  close(instanceId: string): boolean;
  move(instanceId: string, dock: LayoutPanelDock): boolean;
  updateState<TState extends JsonValue>(instanceId: string, state: TState): void;
  clearTarget(instanceId: string, sequence?: number): void;
}

The shell creates the full panel ID from the claimant ID and local registration ID. This rule prevents silent collisions.

A single panel uses one instance per panel ID. An open call focuses that instance.

A multiple panel uses instanceKey as its stable instance identity. The controller creates a key when none exists.

The shell stores only JSON state for a persistent panel. It never stores a session target.

Each target gets a larger sequence value. The panel clears only the sequence that it used.

The shell checks the target schema before it opens the panel. An invalid target fails the call without a state change.

The shell can move a panel when the viewport becomes compact. The panel cannot set pixel sizes or frame chrome.

Domain surfaces can use this controller. For example, bb.thread-ui.sidePanels supplies thread panel declarations.

Modals

The modal surface follows the same declaration rule. The shell owns all modal behavior outside the component.

export interface LayoutModalRegistration<TState = JsonValue> {
  id: string;
  title: string;
  component: ComponentType<LayoutModalProps<TState>>;
  size?: "small" | "medium" | "large";
  dismiss?: "button" | "button-and-backdrop" | "explicit";
}

export interface LayoutModalProps<TState = JsonValue> {
  modalId: string;
  instanceId: string;
  state: TState | null;
  close(result?: JsonValue): void;
}

export interface LayoutModalController {
  open<TState extends JsonValue>(modalId: string, state?: TState): string;
  close(instanceId: string, result?: JsonValue): boolean;
  closeTop(result?: JsonValue): boolean;
}

The shell gives focus to the top modal. It returns focus to the prior element after the modal closes.

Themes

bb.layout.theme is a keyed app capability. Its key has the form <ownerPluginId>.<localThemeId>.

export type LayoutThemeKey = `${string}.${string}`;
export type LayoutColorMode = "light" | "dark";

export interface LayoutThemeDefinition {
  id: LayoutThemeKey;
  name: string;
  description?: string;
  palette: {
    light: LayoutThemePalette;
    dark: LayoutThemePalette;
  };
  codeTheme?: {
    light: LayoutCodeTheme;
    dark: LayoutCodeTheme;
  };
}

export interface LayoutThemePalette {
  variables: Readonly<Record<`--${string}`, string>>;
  colorScheme: "light" | "dark";
}

export interface LayoutCodeTheme {
  name: string;
  foreground: string;
  background: string;
  colors: Readonly<Record<string, string>>;
  tokenColors: readonly LayoutCodeThemeTokenRule[];
}

export interface LayoutCodeThemeTokenRule {
  scope?: string | readonly string[];
  settings: {
    foreground?: string;
    background?: string;
    fontStyle?: string;
  };
}

export interface LayoutThemeClientState {
  selection: LayoutThemeSelection;
  mode: LayoutColorMode;
  definition: LayoutThemeDefinition;
  codeTheme: LayoutCodeTheme;
}

The keyed winner rule applies only when two claimants use the same key. The default keys use the bb.layout.* prefix.

The browser resolves the light or dark branch. A mode change does not change the selected theme key.

The theme definition supplies data. It does not run a React wrapper around the app.

The catalog also includes old on-disk custom themes. These themes are Layout-owned data, not dynamic contract claims.

Services

bb.layout.themes

The service gives every server plugin one typed theme API. The old bb.sdk.theme facade calls this service.

export interface LayoutThemes {
  get(): Promise<LayoutThemeState>;
  catalog(): Promise<LayoutThemeCatalog>;

  // Set the complete selection.
  set(selection: LayoutThemeSelection): Promise<LayoutThemeState>;

  // Keep the current favicon color and change only the theme.
  set(themeId: LayoutThemeKey): Promise<LayoutThemeState>;
}

export interface LayoutThemeSelection {
  themeId: LayoutThemeKey;
  faviconColor:
    | "default"
    | "red"
    | "orange"
    | "yellow"
    | "green"
    | "teal"
    | "blue"
    | "purple"
    | "pink";
}

export interface LayoutThemeState extends LayoutThemeSelection {
  definition: LayoutThemeDefinition;
}

export interface LayoutThemeCatalog {
  customThemeDirectory: string;
  themes: readonly {
    id: LayoutThemeKey;
    pluginId: string;
    name: string;
    description: string | null;
  }[];
  active: LayoutThemeState;
}

The object overload changes the full selection in one call. The string overload keeps the current favicon color.

The compatibility facade converts old IDs, such as nord, to canonical keys before it calls the service.

The service stores the selection through bb.storage. It watches bb.plugins for theme claim changes.

If the selected claimant goes away, the service selects bb.layout.default. It publishes one theme-change event when bb.realtime is available.

Required consumers restart after a service winner change. Watched consumers stay active and receive the new provider state.

Exports

bb.layout publishes exact first-party code through these module paths.

An import selects this exact first-party code. A surface render follows the current contract winner.

Host roles

bb.layout declares no host role. The app and server artifacts use kernel ports only.

Example

This plugin adds a status action and a theme. The manifest records both claims before the app code runs.

{
  "id": "acme.focus",
  "version": "2.0.0",
  "claims": [
    { "surface": "bb.layout.statusbar" },
    { "surface": "bb.layout.theme", "key": "acme.focus.dim" }
  ],
  "artifacts": { "app": "./dist/app.js" }
}

import { definePlugin } from "@get-bb/plugin/app";
import { Button } from "@bb/ui";

export default definePlugin((api) => {
  api.surfaces.add("bb.layout.statusbar", {
    id: "focus-toggle",
    order: 40,
    title: "Focus mode",
    component: ({ compact }) => (
      <Button size={compact ? "icon" : "sm"} onClick={() => api.commands.run("acme.focus.toggle")}>
        Focus
      </Button>
    ),
  });

  api.surfaces.provideKey("bb.layout.theme", "acme.focus.dim", {
    id: "acme.focus.dim",
    name: "Focus Dim",
    description: "A low contrast theme for long work sessions.",
    palette: {
      light: {
        colorScheme: "light",
        variables: { "--background": "#f5f3ee", "--foreground": "#292722" },
      },
      dark: {
        colorScheme: "dark",
        variables: { "--background": "#171816", "--foreground": "#d7d5ce" },
      },
    },
  });
});

The runtime removes both entries when the plugin unloads. The theme service uses the default theme if this key disappears.

Covers