@jxsuite/studio 2.0.0 → 2.1.0

package/src/collab/collab-state.ts

@@ -8,7 +8,22 @@ import { reactive, toRaw } from "../reactivity";
 import type { Tab } from "../tabs/tab";
 import type { CollabAwarenessState } from "@jxsuite/collab/awareness-types";
 
-export type CollabTabStatus = "detached" | "connecting" | "synced" | "offline";
+/**
+ * What co-editing is doing for this tab.
+ *
+ * `"detached"` used to mean three different things at once and say none of them: this build has no
+ * collaboration at all, this project has collaboration but this tab is solo, and the attach was
+ * tried and it FAILED. §7.4: a freeze is currently indistinguishable from a bug, and so was a
+ * broken connection. `"unavailable"` and `"failed"` split the third and first cases out, so the
+ * chip can say which one it is.
+ */
+export type CollabTabStatus =
+  | "unavailable"
+  | "detached"
+  | "connecting"
+  | "synced"
+  | "offline"
+  | "failed";
 
 export interface PeerPresence {
   clientId: number;
@@ -25,8 +40,18 @@ export interface TabCollabState {
   /**
    * True while source holds the canonical lock (someone is co-editing the code view): structural
    * surfaces soft-freeze and the canvas previews the source reconciler's parses.
+   *
+   * The freeze is real and it is brief, and until now its only rendering was a grey line for three
+   * seconds — which is exactly what a bug looks like. It gets an indicator (§7.4).
    */
   sourceCanonical: boolean;
+  /**
+   * Why the last attach failed, when it did. Empty while `status` is anything but `"failed"`.
+   *
+   * The attach used to swallow its own exception into `status = "detached"`, so a dead relay, an
+   * expired token and a project that simply is not shared all produced the same silence.
+   */
+  attachError: string;
 }
 
 const states = new WeakMap<Tab, TabCollabState>();
@@ -40,10 +65,11 @@ export function collabState(tab: Tab): TabCollabState {
   if (!state) {
     state = reactive({
       active: false,
+      attachError: "",
       peers: [],
       readOnly: false,
       sourceCanonical: false,
-      status: "detached",
+      status: "unavailable",
     }) as TabCollabState;
     states.set(key, state);
   }

package/src/collab/presence-chips.ts

@@ -1,13 +1,32 @@
 /**
- * Presence chips — who else is in this co-editing session, plus the sync-status pill that replaces
- * the dirty dot for collab tabs. Pure lit templates over collabState(tab); the toolbar includes
- * them and its render effect tracks the underlying reactive state.
+ * Presence chips — who else is in this co-editing session, the sync-status pill that replaces the
+ * dirty dot for collab tabs, and the two states co-editing had no way to announce (§7.4).
+ *
+ * Pure lit templates over `collabState(tab)`; the toolbar includes them and its render effect
+ * tracks the underlying reactive state.
+ *
+ * **What was invisible.** Three things:
+ *
+ * - **The source-canonical freeze.** While a peer holds the code view, structural edits are refused.
+ *   The whole rendering of that was a three-second grey status line the moment you tried — which is
+ *   precisely what a bug looks like. It gets a persistent indicator, so the refusal has a visible
+ *   cause standing beside it for as long as it is true.
+ * - **Read-only guests.** Their edits applied locally and were dropped at the publish gate. They now
+ *   get a banner that says so before they type, not a silence after.
+ * - **A failed attach.** It set `status = "detached"` — the same value a solo document carries — so a
+ *   dead relay was indistinguishable from nobody having shared the file. `"failed"` and
+ *   `"unavailable"` are now separate states with separate sentences.
+ *
+ * **Undo says what it does.** The Y.UndoManager is constructed with `trackedOrigins:
+ * {LOCAL_ORIGIN}`, so ⌘Z reaches your own actions and never a peer's. That is the correct behaviour
+ * and it is also surprising, so the status pill's title states it — §13 lists this as adopted
+ * precisely because silently undoing someone else's work is worse than not undoing.
  */
 
 import { html, nothing } from "lit-html";
 import type { TemplateResult } from "lit-html";
 import { collabState } from "./collab-state";
-import type { PeerPresence } from "./collab-state";
+import type { CollabTabStatus, PeerPresence } from "./collab-state";
 import type { Tab } from "../tabs/tab";
 
 function initialOf(peer: PeerPresence): string {
@@ -22,25 +41,71 @@ function titleOf(peer: PeerPresence, docPath: string | null): string {
   return here ? who : `${who} — ${peer.state.focusedPath ?? "browsing"}`;
 }
 
-const STATUS_LABEL: Record<string, string> = {
+/** One line per status. Every state says what it is; none of them say nothing. */
+const STATUS_LABEL: Readonly<Record<CollabTabStatus, string>> = {
   connecting: "Connecting…",
+  detached: "Solo",
+  failed: "Not connected",
   offline: "Offline — changes sync on reconnect",
   synced: "Live",
+  unavailable: "",
 };
 
-/** Chips + status pill for the toolbar; `nothing` while the tab isn't co-editing. */
+/**
+ * The sentence behind the pill — including the one undo fact nobody would guess.
+ *
+ * @param {CollabTabStatus} status
+ * @param {string} attachError
+ * @returns {string}
+ */
+export function statusTitle(status: CollabTabStatus, attachError: string): string {
+  if (status === "failed") {
+    return (
+      `Live collaboration could not start${attachError ? ` — ${attachError}` : ""}. ` +
+      "Your edits are saved to this machine as usual."
+    );
+  }
+  if (status === "synced" || status === "offline") {
+    return `${STATUS_LABEL[status]}. Undo only takes back your own edits, never a collaborator's.`;
+  }
+  return STATUS_LABEL[status];
+}
+
+/** Chips + status pill for the toolbar; `nothing` while the tab has no collaboration to report. */
 export function presenceChipsTemplate(tab: Tab | null): TemplateResult | typeof nothing {
   if (!tab) {
     return nothing;
   }
   const state = collabState(tab);
-  if (state.status === "detached") {
+  /* "unavailable" is the only silent state: this build has no collaboration, so there is nothing to
+     be honest ABOUT. Every other state — including solo and failed — says which one it is. */
+  if (state.status === "unavailable") {
     return nothing;
   }
-  const label = STATUS_LABEL[state.status] ?? state.status;
+  const label = STATUS_LABEL[state.status] || state.status;
   return html`
-    <div class="jx-presence" title=${label}>
+    <div class="jx-presence" title=${statusTitle(state.status, state.attachError)}>
       <span class="jx-presence-status" data-status=${state.status}>${label}</span>
+      ${
+        state.readOnly
+          ? html`<span
+              class="jx-presence-flag"
+              data-flag="read-only"
+              title="You have read access to this session. Your edits show here but are not published to the others."
+              >Read-only</span
+            >`
+          : nothing
+      }
+      ${
+        state.sourceCanonical
+          ? html`<span
+              class="jx-presence-flag"
+              data-flag="frozen"
+              title="Someone is editing the code view. Structural edits are paused until they stop — this is not an error."
+              >Code view held</span
+            >`
+          : nothing
+      }
       ${state.peers.map(
         (peer) => html`
           <span
@@ -58,3 +123,29 @@ export function presenceChipsTemplate(tab: Tab | null): TemplateResult | typeof
     </div>
   `;
 }
+
+/**
+ * The read-only banner — a standing statement, not an after-the-fact refusal.
+ *
+ * A guest without write access used to watch their edits apply locally and be dropped silently at
+ * the publish gate, which reads as the app losing work. The sentence has to be there before the
+ * first keystroke, so it is rendered by the PANE CHROME (`panels/pane-context.ts`) rather than by
+ * the toolbar the chips ride in: the chrome is per-pane and per-document, it sits directly above
+ * the editing surface, and the stage is offset by the band it lives in — so the banner pushes the
+ * document down instead of covering it.
+ */
+export function readOnlyBannerTemplate(tab: Tab | null): TemplateResult | typeof nothing {
+  if (!tab) {
+    return nothing;
+  }
+  const state = collabState(tab);
+  if (!state.active || !state.readOnly) {
+    return nothing;
+  }
+  return html`
+    <div class="jx-collab-banner" role="status" data-kind="read-only">
+      You have read access to this session. You can explore and edit locally, but your changes are
+      not published to the other people in it.
+    </div>
+  `;
+}

package/src/commands/active-registry.ts

@@ -0,0 +1,42 @@
+/**
+ * Active-registry.ts — the one registry this window's chrome renders from.
+ *
+ * `registry.ts` deliberately has no module-level singleton: the context a registry closes over is
+ * one window's, the CI checks build their own, and every test wants a registry it can state
+ * exactly. That is right, and it leaves one gap — the Command Bar and the Palette are mounted by
+ * `studio.ts` BEFORE the bootstrap composes the registry (`toolbar.mount` runs at the top of the
+ * file, `createCommandRegistry` near the bottom), so neither surface can be handed one at mount.
+ *
+ * This is the seam, in the same idiom as `platform.ts`'s `registerPlatform` / `getPlatform` and
+ * `canvas/preview-navigate.ts`'s handler slot: the bootstrap sets it once, and the surfaces ask.
+ *
+ * The holder is a `shallowRef`, which is the load-bearing part. A surface that reads
+ * {@link activeRegistry} inside its render effect TRACKS the holder, so the effect re-runs the
+ * moment the bootstrap sets it — which is what lets the Command Bar paint an honest empty band at
+ * mount and fill in without anyone remembering to call `render()` afterwards.
+ */
+
+import { shallowRef } from "../reactivity";
+import type { CommandRegistry } from "./registry";
+
+const _registry = shallowRef<CommandRegistry | null>(null);
+
+/**
+ * Publish this window's registry. Called once by the bootstrap, and by tests with their own.
+ *
+ * Passing `null` clears it, which is what an unmounting test does so the next one starts cold.
+ */
+export function setActiveRegistry(registry: CommandRegistry | null): void {
+  _registry.value = registry;
+}
+
+/**
+ * This window's registry, or `null` before the bootstrap has composed it.
+ *
+ * Returning `null` rather than throwing is deliberate: the surfaces render a skeleton in that
+ * window, and a chrome that crashes because it painted one frame early would be a worse bug than
+ * the one this seam exists to solve.
+ */
+export function activeRegistry(): CommandRegistry | null {
+  return _registry.value;
+}

package/src/commands/app-commands.ts

@@ -0,0 +1,176 @@
+/**
+ * App-commands.ts — the whole app's command set, in one bare-Bun-importable place.
+ *
+ * `src/studio.ts` composes the registry a RUNNING window uses, by calling each module's
+ * `registerXCommands(registry, deps)` beside the state it writes. That is the right shape for the
+ * app and the wrong shape for CI: `scripts/check-command-levels.ts`,
+ * `scripts/check-chrome-budget.ts` and `scripts/check-shot-contract.ts` all run in a bare Bun
+ * process with no DOM and no bootstrap, and each looks for one export — `defaultCommandSet()`.
+ *
+ * Without this module those three checks see only `commands/defaults.ts`'s sixteen records, which
+ * is why plan §13.5's headline promise was not yet true: a manifest step naming `view.setActivity`
+ * with a panel id the registry does not declare sailed through Lane 1, because Lane 1 could not
+ * load the record that declares the enum. Every module gathered below imports cleanly with no
+ * `document` and no `localStorage` write, which is the ONLY property this file requires of them —
+ * and the test beside it asserts exactly that, so a future DOM read at module scope fails here
+ * rather than in CI.
+ *
+ * **Deps are the no-op set.** Nothing here runs a command; the checks read `id`, `level`, `menus`
+ * and `args`. Passing real implementations would mean importing the app.
+ *
+ * **The canvas keyboard is here now.** This note used to say `editor/shortcuts.ts`'s records were
+ * deliberately absent because `edit.copy` / `edit.cut` were declared in two places, and that they
+ * would join "when that reconciliation lands — one line each, and no script changes". The
+ * reconciliation had already landed (`shortcuts.ts`'s handoff table records it as PAID: the
+ * clipboard pair is defined once, in `editor/context-menu.ts`, and spread from there), so the
+ * deferral outlived its reason by two phases while ten records the app runs stayed invisible to
+ * every check and to the generated keyboard sheet. It was one line. `tests/
+ * app-commands-composition.test.ts` now asserts the projection from BOTH directions, because a
+ * record the app registers and the projection omits is exactly as invisible as the reverse, and
+ * only one of the two had a guard.
+ */
+
+import { defaultCommands, noopCommandDeps } from "./defaults";
+import { panelFocusRoster } from "../panels/navigator-panels";
+import { createCommandRegistry } from "./registry";
+import { emptyContext } from "./context";
+import { DEFAULT_INSPECTOR_TAB, shellViewCommands } from "../shell";
+import { canvasViewCommands } from "../canvas/canvas-utils";
+import { selectionCommands } from "../canvas/canvas-render";
+import { inspectorCommands } from "../panels/properties-panel";
+import { dataExplorerCommands } from "../panels/data-explorer";
+import { seoCommands } from "../panels/seo-modal";
+import { a11yCommands } from "../services/a11y-report";
+import { liveElementCommands } from "../editor/context-menu";
+import { signalsCommands } from "../panels/signals-panel";
+import { formulaEditorCommands } from "../panels/formula-workspace";
+import { styleCommands } from "../panels/style-panel";
+import { gridCommands } from "../grid/grid-open";
+import { settingsCommands } from "../settings/settings-document";
+import { collabCommands } from "../collab/collab-commands";
+import { assistantCommands } from "../panels/ai-panel";
+import { preferencesCommands } from "../settings/preferences-dialog";
+import { aboutCommands } from "../about/about-modal";
+import { libraryCommands } from "../browse/library-commands";
+import { sourceControlCommands } from "../panels/git-panel";
+import { publishCommands } from "../publish/publish-commands";
+import { gridViewCommands } from "../grid/grid-panel";
+import { redirectsCommands } from "../grid/redirects-grid";
+import { contentCommands } from "../content/entry-commands";
+import { i18nCommands } from "../i18n/i18n-commands";
+import { newProjectCommands } from "../new-project/new-project-modal";
+import { canvasCommands } from "../editor/shortcuts";
+import { formatCommands, registerSelectionCommands } from "../panels/block-action-bar";
+import { registerTabCommands } from "../workspace/workspace";
+import { derivationCommands, noopDerivationDeps } from "../workspace/pane-derive";
+import type { AnyCommand } from "./registry";
+
+/** A verb set that does nothing — the checks read declarations, never behaviour. */
+const NO_OP = () => {};
+
+/**
+ * A stage the zoom verbs can be DECLARED against. Reading it is a no-op; running one is not the
+ * point here — the checks read `id`, `level`, `menus` and `args`.
+ *
+ * Exported so its own test can call it. The zoom records only reach a stage when they RUN with a
+ * document open, which no check does, so the accessor would otherwise be a function nothing in the
+ * suite ever enters — and "nothing calls it" is the shape this repository treats as a defect
+ * everywhere else.
+ */
+export const noopStage = () => ({
+  applyTransform: NO_OP,
+  canvasMode: "design",
+  panX: 0,
+  panY: 0,
+  setPan: NO_OP,
+});
+
+/**
+ * Records that are only reachable through a `registerX(registry, deps)` entry point.
+ *
+ * Collected by registering them into a throwaway registry and reading it back, rather than by
+ * asking those modules to grow a second export. That also means these records go through
+ * `register()`'s own duplicate-id, chord-conflict and placement checks on the way in, so this
+ * function throws for the same reasons the app's bootstrap would.
+ */
+function viaRegistration(): AnyCommand[] {
+  const registry = createCommandRegistry({ getContext: emptyContext });
+  registerTabCommands(registry, { openFile: NO_OP, openFileInPane: NO_OP });
+  registerSelectionCommands(registry, { convertToComponent: NO_OP, navigateToComponent: NO_OP });
+  return [...registry.list()];
+}
+
+/**
+ * Every command the app's registry holds, in bootstrap order.
+ *
+ * Order matches `studio.ts` so a reader comparing the two files can do it line by line.
+ */
+export function appCommandSet(): AnyCommand[] {
+  return [
+    // The panel roster is the one dependency the checks must supply for real: the ⌘1–8 records are
+    // Generated from it, so an empty one would hide eight commands (and their chords) from the
+    // Level check, the chrome budget and the generated keyboard sheet alike.
+    ...defaultCommands({ ...noopCommandDeps(), panelRoster: panelFocusRoster() }),
+    ...viaRegistration(),
+    ...derivationCommands(noopDerivationDeps()),
+    ...shellViewCommands({ inspectorTab: () => DEFAULT_INSPECTOR_TAB, setInspectorTab: NO_OP }),
+    ...canvasViewCommands({
+      getCanvasMode: () => "design",
+      renderPane: NO_OP,
+      setCanvasMode: NO_OP,
+      setResolvingOpen: NO_OP,
+    }),
+    ...selectionCommands(),
+    ...inspectorCommands(),
+    ...seoCommands(),
+    ...a11yCommands(),
+    // The element menu's eight verbs. Every one declares `menus: ["context/element", "palette"]`
+    // And none reached the palette, because they were registered ONLY into the private registry
+    // `editor/context-menu.ts` builds for its popover — a registry whose own docstring said it
+    // Existed "until a bootstrap composes every contribution point into a single app-wide
+    // Registry". This is that bootstrap; it has existed since P2.
+    ...liveElementCommands(),
+    ...dataExplorerCommands({ renderLeftPanel: NO_OP }),
+    ...signalsCommands(),
+    ...formulaEditorCommands(),
+    ...gridCommands(),
+    ...settingsCommands(),
+    ...collabCommands(),
+    ...assistantCommands(),
+    ...preferencesCommands(),
+    ...aboutCommands(),
+    ...libraryCommands(),
+    ...contentCommands(),
+    // The four translation verbs. `i18n.switchLocale` is deliberately not among them: it is a
+    // Rendering context, defined in `canvas/canvas-utils.ts` beside the per-tab UI state it writes.
+    ...i18nCommands(),
+    ...sourceControlCommands(),
+    ...publishCommands(),
+    ...gridViewCommands(),
+    ...redirectsCommands(),
+    ...newProjectCommands(),
+    ...styleCommands(),
+    // Inline formatting — the eight `format.*` records. Registered in the bootstrap beside the bar
+    // That renders them, and projected here so the palette, the level check and the generated
+    // Keyboard sheet all see the first `caret`-scoped chords the app has ever had.
+    ...formatCommands(),
+    /* The canvas keyboard's own nine, plus the clipboard pair they spread.
+       These were the last records the app registered and this projection did not contain, so ⌘C,
+       ⌘X, ⌘V, Enter, the three structural arrows and all three zoom chords were absent from
+       `check-command-levels`, from the chrome budget and from the GENERATED keyboard sheet — a
+       reader of `docs/studio/interface/shortcuts.md` could not find Copy. The docstring above used
+       to defer this on the grounds that `edit.copy` was declared twice; it is not, and has not been
+       since the four literal duplicates were paid off (`shortcuts.ts`'s handoff table). It is one
+       line, exactly as that note promised. */
+    ...canvasCommands(noopStage),
+  ];
+}
+
+/**
+ * The name the three CI checks import by.
+ *
+ * Kept as an alias rather than renaming the scripts' contract: `commands/defaults.ts` exports the
+ * same symbol, so pointing a check at either module is a `--source` flag, and a check written
+ * before this file existed keeps working unchanged.
+ */
+export const defaultCommandSet = appCommandSet;

package/src/commands/budget.ts

@@ -0,0 +1,158 @@
+/**
+ * Budget.ts — chrome is earned by frequency and capped by a build check.
+ *
+ * Plan §2, principle 9: at most five commands may declare `menus: ["commandbar/primary"]`, and at
+ * most four tabs per dock. `scripts/check-chrome-budget.ts` fails CI otherwise, which is what turns
+ * "we should keep the toolbar small" from a code-review opinion into a build error.
+ *
+ * The cap is not arbitrary. The toolbar's own CSS already admits it is over budget — a container
+ * query at 1140px strips every `.tb-label` rather than conceding there are too many controls — and
+ * an unlabelled icon is a control the user has to hover to identify. A hard number is what makes
+ * "retire this control, keep its name and its chord" the cheap option.
+ *
+ * The dock/tab sets used to be a flat declaration — written out from §3.2 because `registerPanel()`
+ * did not exist. It does now, so the two `rail/*` rows are a QUERY over `railDeclarations()`
+ * ({@link dockTabs}) and adding a ninth rail panel fails this check without anyone remembering to
+ * update a list. The two rows that remain declared are the two docks whose tab sets this module
+ * cannot see from a bare Bun process: the Inspector's four come from `commands/defaults.ts`'s
+ * `INSPECTOR_TABS` (a query in all but name), and the Bottom dock's four are records in
+ * `panels/bottom-dock.ts`, which renders lit templates and therefore cannot be imported here.
+ * `tests/bottom-dock.test.ts` asserts the declared row and the registered set are the same four
+ * titles, so the copy cannot drift — the same bargain `tests/right-panel.test.ts` strikes for the
+ * Inspector. Both become real queries the day `scripts/check-chrome-budget.ts` joins them the way
+ * it already joins the rail.
+ */
+
+import { INSPECTOR_TABS } from "./defaults";
+
+/** The caps. Raising either one is a design decision, so it happens here, in one place. */
+export const CHROME_BUDGET = {
+  /** Commands allowed in the Command Bar's primary verb cluster. */
+  commandbarPrimary: 5,
+  /** Tabs allowed in any one dock (or rail group). */
+  dockTabs: 4,
+  /**
+   * Verbs allowed in the block action bar's inline-format cluster.
+   *
+   * Eight, which is the whole vocabulary `data/elements-meta.json` declares — bold, italic,
+   * underline, strikethrough, superscript, subscript, code, link. It is a cap and not a count: an
+   * element offers the SUBSET its `$inlineActions` names, so the bar never draws eight, and a ninth
+   * verb is a design decision that has to be made here rather than by appending to a data file.
+   */
+  blockbarFormat: 8,
+} as const;
+
+/** One tabbed region and what it currently hosts. */
+export interface DockDeclaration {
+  /** Region key as §3.2 names it. Rail groups count separately — they are separate placements. */
+  dock: string;
+  tabs: readonly string[];
+}
+
+/**
+ * The tabbed regions that are still WRITTEN DOWN rather than observed.
+ *
+ * The Inspector's row is a query in all but name — `INSPECTOR_TABS` is the list `right-panel.ts`
+ * renders and `⌘⇧1–4` address, so a fifth inspector tab fails this check in the commit that adds
+ * it. The Bottom dock's row is the same shape: the four ids live in `shell.ts`'s `BOTTOM_TAB_IDS`
+ * (so `view.setBottomTab`'s enum can be read in a bare Bun process) and the four RECORDS live in
+ * `panels/bottom-dock.ts`. It inherited this cap before it existed, which is why Deploy folded into
+ * Activity rather than becoming a fifth tab.
+ *
+ * The rail's two groups are NOT here. They come from `panels/panel-registry.ts`'s
+ * `railDeclarations()` and are joined on by {@link dockTabs} — the registry is the single source of
+ * what a panel is called and which group it sits in, and a duplicate list here was the last place
+ * those could disagree.
+ */
+export const DECLARED_DOCK_TABS: readonly DockDeclaration[] = [
+  { dock: "inspector", tabs: INSPECTOR_TABS.map((tab) => tab.title) },
+  { dock: "bottom", tabs: ["Problems", "Logic", "Activity"] },
+];
+
+/**
+ * Every tabbed region: the declared ones plus the rail groups the panel registry observes.
+ *
+ * The rails arrive as an ARGUMENT rather than by import so this module keeps the property that lets
+ * three CI checks load it in a bare Bun process — `panel-registry.ts` reaches the DOM, the shell
+ * record and the workspace. `scripts/check-chrome-budget.ts` is the one place that joins them.
+ *
+ * @param rails `railDeclarations()`, or `[]` where no registry has been populated.
+ */
+export function dockTabs(rails: readonly DockDeclaration[] = []): DockDeclaration[] {
+  return [...DECLARED_DOCK_TABS, ...rails];
+}
+
+/** The subset of a command record the budget check reads. */
+export interface BudgetableRecord {
+  id: string;
+  menus?: readonly string[] | undefined;
+}
+
+/** One exceeded cap. */
+export interface BudgetViolation {
+  /** What was counted: a placement key, or a dock key. */
+  subject: string;
+  count: number;
+  limit: number;
+  message: string;
+}
+
+/** Commands declaring the primary Command Bar cluster. */
+export function primaryCommandIds(commands: readonly BudgetableRecord[]): string[] {
+  return commands
+    .filter((command) => (command.menus ?? []).includes("commandbar/primary"))
+    .map((command) => command.id);
+}
+
+/**
+ * Check both caps.
+ *
+ * @param input.commands Every registered command record.
+ * @param input.docks The shell's tabbed regions. Defaults to {@link dockTabs} with no rails.
+ */
+export function checkChromeBudget(input: {
+  commands: readonly BudgetableRecord[];
+  docks?: readonly DockDeclaration[];
+}): BudgetViolation[] {
+  const violations: BudgetViolation[] = [];
+  const primary = primaryCommandIds(input.commands);
+  if (primary.length > CHROME_BUDGET.commandbarPrimary) {
+    violations.push({
+      subject: "commandbar/primary",
+      count: primary.length,
+      limit: CHROME_BUDGET.commandbarPrimary,
+      message:
+        `${primary.length} commands declare menus:["commandbar/primary"], the cap is ` +
+        `${CHROME_BUDGET.commandbarPrimary} — ${primary.join(", ")}. Retire one to ` +
+        `"commandbar/overflow": it keeps its name, its chord and its palette row.`,
+    });
+  }
+  const formatting = input.commands
+    .filter((command) => (command.menus ?? []).includes("blockbar/format"))
+    .map((command) => command.id);
+  if (formatting.length > CHROME_BUDGET.blockbarFormat) {
+    violations.push({
+      subject: "blockbar/format",
+      count: formatting.length,
+      limit: CHROME_BUDGET.blockbarFormat,
+      message:
+        `${formatting.length} commands declare menus:["blockbar/format"], the cap is ` +
+        `${CHROME_BUDGET.blockbarFormat} — ${formatting.join(", ")}. The cluster sits over a text ` +
+        `range in a floating bar; a ninth verb belongs in the palette.`,
+    });
+  }
+  for (const dock of input.docks ?? dockTabs()) {
+    if (dock.tabs.length > CHROME_BUDGET.dockTabs) {
+      violations.push({
+        subject: dock.dock,
+        count: dock.tabs.length,
+        limit: CHROME_BUDGET.dockTabs,
+        message:
+          `dock "${dock.dock}" declares ${dock.tabs.length} tabs, the cap is ` +
+          `${CHROME_BUDGET.dockTabs} — ${dock.tabs.join(", ")}. Fold two together or move one ` +
+          `to another dock.`,
+      });
+    }
+  }
+  return violations;
+}