@jxsuite/studio 2.0.0 → 2.1.0

package/src/commands/reference.ts

@@ -0,0 +1,227 @@
+/**
+ * Reference.ts — the registry, projected into the two generated documentation pages.
+ *
+ * Plan §12 P3 lists `docs/studio/interface/shortcuts.md` and a new
+ * `docs/studio/interface/commands.md` as **generated from the registry and CI-diffed**, which is
+ * the last of §5.5's seven derivations: with the chrome, the keymap, the palette, the menus and the
+ * automation surface all rendering the same records, a hand-maintained shortcut sheet is the only
+ * place left for the app's keyboard and its documentation to disagree.
+ *
+ * This module is the projection, not the generator. It takes a command set — `appCommandSet()`, the
+ * one bare-Bun-importable export the three CI checks already load — and returns ROWS plus the
+ * markdown table each page's body is made of. `scripts/docs/generate-reference.ts` supplies the
+ * frontmatter, the prose and the file write; keeping the two apart is what lets the projection be
+ * tested in this package, next to the records it reads, without a docs harness.
+ *
+ * Everything here is pure and sorted deterministically: a generated page that reorders itself
+ * between runs is a CI diff nobody can review.
+ */
+
+import { formatChord, normalizeChord } from "./keymap";
+import { CATEGORIES } from "./levels";
+import type { KeybindingOverrides } from "./keymap";
+import type { Category, KeyScope, Level, Placement } from "./levels";
+import type { AnyCommand } from "./registry";
+
+/** One command, as `docs/studio/interface/commands.md` prints it. */
+export interface CommandRow {
+  id: string;
+  title: string;
+  category: Category;
+  level: Level;
+  /** Canonical chords, in declaration order. Empty when the command is palette-only. */
+  chords: readonly string[];
+  /** Chords as a mac reader sees them. */
+  mac: readonly string[];
+  /** Chords as a Windows/Linux reader sees them. */
+  pc: readonly string[];
+  /** The `requires` sentence — the same string the disabled tooltip and the agent's refusal print. */
+  requires: string;
+  /** Declared placements, sorted. `["palette"]` when the record declares none. */
+  menus: readonly Placement[];
+  /** The assistant tool name this record projects to, or `""` when it does not. */
+  aiTool: string;
+  destructive: boolean;
+}
+
+/** One binding, as `docs/studio/interface/shortcuts.md` prints it. */
+export interface ShortcutRow {
+  /** Canonical chord — `"mod+shift+p"`. The sort key, so the sheet is stable across platforms. */
+  chord: string;
+  mac: string;
+  pc: string;
+  commandId: string;
+  title: string;
+  category: Category;
+  /** Where the chord is live. The column that explains why ⌘D does nothing while you are typing. */
+  scope: KeyScope;
+  /** Whether this chord came from the user's layer rather than the record. Always false in docs. */
+  overridden: boolean;
+}
+
+/** Human wording for each {@link KeyScope}, so the sheet does not print an enum at a reader. */
+export const SCOPE_LABELS: Readonly<Record<KeyScope, string>> = {
+  global: "Anywhere",
+  canvas: "Canvas selection",
+  caret: "Text caret",
+  grid: "Data grid",
+  code: "Code editor",
+  dock: "Focused dock",
+  palette: "Palette",
+};
+
+/** Category order — declaration order in `levels.ts`, which is task order, not alphabetical. */
+const CATEGORY_RANK = new Map(CATEGORIES.map((category, index) => [category, index]));
+
+function categoryRank(category: Category): number {
+  return CATEGORY_RANK.get(category) ?? CATEGORIES.length;
+}
+
+/** A record's chords in canonical form, in declaration order. */
+function chordsOf(command: AnyCommand): string[] {
+  const raw = command.keybinding;
+  if (!raw) {
+    return [];
+  }
+  return (typeof raw === "string" ? [raw] : [...raw]).map((chord) => normalizeChord(chord));
+}
+
+/**
+ * Every command, as documentation rows.
+ *
+ * Sorted by category then title — the palette's own grouping, so a reader who learned the app
+ * through the palette finds the page laid out the way they already think.
+ */
+export function commandReference(commands: readonly AnyCommand[]): CommandRow[] {
+  return commands
+    .map((command) => {
+      const chords = chordsOf(command);
+      const row: CommandRow = {
+        id: command.id,
+        title: command.title,
+        category: command.category,
+        level: command.level,
+        chords,
+        mac: chords.map((chord) => formatChord(chord, true)),
+        pc: chords.map((chord) => formatChord(chord, false)),
+        requires: command.requires ?? "",
+        menus: [...(command.menus ?? ["palette"])].toSorted(),
+        aiTool: command.aiTool?.name ?? "",
+        destructive: command.destructive === true,
+      };
+      return row;
+    })
+    .toSorted(
+      (a, b) =>
+        categoryRank(a.category) - categoryRank(b.category) || a.title.localeCompare(b.title),
+    );
+}
+
+/**
+ * Every BINDING, as documentation rows — one row per chord, not per command.
+ *
+ * `edit.redo` declares two chords and appears twice, because a reader looking up ⌘Y needs to find
+ * it. Sorted by scope then chord so the sheet reads as "here is what this key does, and here is
+ * where it is live".
+ *
+ * `overrides` is the user's layer (`specs/studio.md` §15) and is how ONE projection serves both
+ * readers: the generated page passes none and prints what the app ships with, while the in-app
+ * Keyboard sheet passes the live layer and prints what this author's keyboard actually does. A
+ * command the user unbound has an entry with no chords and contributes no row — the same rule as a
+ * command that never declared one, because in both cases there is nothing to press.
+ */
+export function shortcutReference(
+  commands: readonly AnyCommand[],
+  overrides?: KeybindingOverrides,
+): ShortcutRow[] {
+  const rows: ShortcutRow[] = [];
+  for (const command of commands) {
+    const scope: KeyScope = command.keyScope ?? "global";
+    const override = overrides?.get(command.id);
+    const chords =
+      override === undefined ? chordsOf(command) : override.map((chord) => normalizeChord(chord));
+    for (const chord of chords) {
+      rows.push({
+        chord,
+        mac: formatChord(chord, true),
+        pc: formatChord(chord, false),
+        commandId: command.id,
+        title: command.title,
+        category: command.category,
+        scope,
+        overridden: override !== undefined,
+      });
+    }
+  }
+  return rows.toSorted((a, b) => a.scope.localeCompare(b.scope) || a.chord.localeCompare(b.chord));
+}
+
+/** Escape the one character that would break out of a markdown table cell. */
+function cell(value: string): string {
+  return value.replaceAll("|", String.raw`\|`);
+}
+
+function table(header: readonly string[], rows: readonly (readonly string[])[]): string {
+  const lines = [
+    `| ${header.join(" | ")} |`,
+    `| ${header.map(() => "---").join(" | ")} |`,
+    ...rows.map((row) => `| ${row.map((value) => cell(value)).join(" | ")} |`),
+  ];
+  return lines.join("\n");
+}
+
+/** A chord list as one cell: `` `⌘⇧Z` or `⌘Y` ``, or an em dash when the command has none. */
+function chordCell(chords: readonly string[]): string {
+  return chords.length === 0 ? "—" : chords.map((chord) => `\`${chord}\``).join(" or ");
+}
+
+/**
+ * The body of `docs/studio/interface/shortcuts.md` — one `##` section per scope.
+ *
+ * Both platforms print, side by side, because the alternative is the page telling half its readers
+ * a chord they do not have — which is the documentation version of the bug `formatChord` fixed in
+ * the toolbar.
+ */
+export function shortcutsMarkdown(rows: readonly ShortcutRow[]): string {
+  const sections: string[] = [];
+  const scopes = [...new Set(rows.map((row) => row.scope))];
+  for (const scope of scopes) {
+    const inScope = rows.filter((row) => row.scope === scope);
+    sections.push(
+      `## ${SCOPE_LABELS[scope]}\n`,
+      table(
+        ["macOS", "Windows / Linux", "Command", "Id"],
+        inScope.map((row) => [
+          `\`${row.mac}\``,
+          `\`${row.pc}\``,
+          row.title,
+          `\`${row.commandId}\``,
+        ]),
+      ),
+    );
+  }
+  return sections.join("\n\n");
+}
+
+/** The body of `docs/studio/interface/commands.md` — one `##` section per category. */
+export function commandsMarkdown(rows: readonly CommandRow[]): string {
+  const sections: string[] = [];
+  const categories = [...new Set(rows.map((row) => row.category))];
+  for (const category of categories) {
+    const inCategory = rows.filter((row) => row.category === category);
+    sections.push(
+      `## ${category}\n`,
+      table(
+        ["Command", "Id", "Shortcut", "Level", "Requires"],
+        inCategory.map((row) => [
+          row.destructive ? `${row.title} (destructive)` : row.title,
+          `\`${row.id}\``,
+          chordCell(row.mac),
+          row.level,
+          row.requires || "—",
+        ]),
+      ),
+    );
+  }
+  return sections.join("\n\n");
+}

package/src/commands/registry.ts

@@ -0,0 +1,293 @@
+/**
+ * Registry.ts — one definition site per action.
+ *
+ * A {@link Command} is the whole record of a capability: its name, its containment level, the
+ * predicate that decides whether it is available, the one sentence that says why it is not, its
+ * default chord, and the surfaces it belongs in. Every surface — Command Bar, palette, rail,
+ * context menus, the block action bar, the keymap, `__jxAutomation` and the assistant's tools —
+ * becomes a RENDERING of these records. A surface may choose whether to show a command; it may
+ * never decide what it is called, when it is available, or what it does (plan §2, principle 1).
+ *
+ * Three things fail loudly at registration rather than degrading into a surface disagreement:
+ *
+ * - A duplicate id — the second definition site the whole design exists to prevent;
+ * - A chord already claimed in the same `keyScope` (see `keymap.ts`) — this is exactly how ⌘W came to
+ *   disagree with the tab strip's × button;
+ * - A `menus` placement the level × placement matrix does not admit (see `levels.ts`), so a
+ *   selection-level verb cannot appear in the Command Bar even in a hand-written test app.
+ *
+ * `when` / `enablement` are `(ctx) => boolean` closures, modelled on the shipped
+ * `services/gated-registry.ts` `ToolAvailability`, and `requires` is ONE string with three
+ * consumers: the disabled control's tooltip, the palette row's grey subtitle and the agent's
+ * refusal message. Plan §13 rejects a serialisable string DSL; do not add one.
+ *
+ * The registry takes its context by injection (`getContext`), so nothing here imports a state
+ * module. That is what lets the CI checks import the command set in a bare Bun process and lets
+ * every test build the exact state it wants to assert against.
+ */
+
+import { createKeymap } from "./keymap";
+import type { KeyChordEvent, Keymap, KeymapMatch } from "./keymap";
+import { checkRecordPlacements } from "./levels";
+import type { Category, KeyScope, Level, Placement } from "./levels";
+import type { CommandContext } from "./context";
+
+/** Arguments as they arrive from a palette prompt, an automation manifest step or an AI tool call. */
+export type CommandArgs = Record<string, unknown>;
+
+/** How an action's effect is undone — surfaced to the user before an agent runs it. */
+export type UndoScope = "document" | "project" | "none";
+
+/**
+ * One capability, defined once.
+ *
+ * @template A The argument record `run` receives. Defaults to `void` for the (common) case of a
+ *   command that takes none.
+ */
+export interface Command<A = void> {
+  /** `"<category>.<verb>"` — the same namespace `scripts/screenshots/manifest.json` addresses. */
+  id: string;
+  /** Imperative human name. The ONLY place this action is named. */
+  title: string;
+  category: Category;
+  /** REQUIRED containment level, checked against every declared placement. */
+  level: Level;
+  /** Keyboard dispatch scope. Deliberately separate from {@link Command.level}. */
+  keyScope?: KeyScope;
+  /** Icon key, resolved through the activity bar's existing icon map. */
+  icon?: string;
+  /** Hide entirely. Default: always visible. */
+  when?: (ctx: CommandContext) => boolean;
+  /** Show but disable. Defaults to {@link Command.when}. */
+  enablement?: (ctx: CommandContext) => boolean;
+  /** The human reason, e.g. "an element selection". Tooltip, palette subtitle, agent refusal. */
+  requires?: string;
+  /** Default chord(s), e.g. `"mod+shift+p"`. User overrides layer on top. */
+  keybinding?: string | readonly string[];
+  /** JSON Schema for {@link Command.run}'s args — the palette's prompt AND the AI tool's params. */
+  args?: object;
+  /** Surfaces this command renders in. Defaults to `["palette"]`. */
+  menus?: readonly Placement[];
+  /** Menu ordering key: "1_clipboard", "3_structure", "9_danger". */
+  group?: string;
+  undo?: UndoScope;
+  destructive?: boolean;
+  /** Opt-in projection to the assistant. The human's gate and the agent's gate stay one predicate. */
+  aiTool?: { name: string; description: string };
+  run: (ctx: CommandContext, args: A) => void | Promise<void>;
+}
+
+/**
+ * A command of unknown argument type, as stored.
+ *
+ * `never` (not `unknown`) is what makes an arbitrary `Command<A>` assignable: `run` is
+ * contravariant in its argument, so a handler taking `{ path }` satisfies one taking `never`.
+ */
+export type AnyCommand = Command<never>;
+
+/** `<namespace>.<verb>`, lowercase namespace, at least two dot-separated segments. */
+const ID_PATTERN = /^[a-z][a-z\d]*(\.[a-zA-Z\d]+)+$/;
+
+/** Thrown when a command is invoked while its own predicate refuses it. */
+export class CommandUnavailableError extends Error {
+  readonly commandId: string;
+  /** The `requires` sentence, or a generic fallback when the record did not supply one. */
+  readonly requires: string;
+
+  constructor(commandId: string, requires: string) {
+    super(refusalSentence(commandId, requires));
+    this.name = "CommandUnavailableError";
+    this.commandId = commandId;
+    this.requires = requires;
+  }
+}
+
+/** Wording shared by the disabled tooltip, the palette subtitle and the agent's refusal. */
+const GENERIC_REQUIREMENT = "a different studio state";
+
+/** The one refusal sentence. `CommandUnavailableError` and `refusalMessage` must not diverge. */
+function refusalSentence(commandId: string, requires: string): string {
+  return `Command "${commandId}" is not available right now — it requires ${requires}.`;
+}
+
+export interface CommandRegistry {
+  /** Define a command. Throws on a duplicate id, a chord conflict or a misplacement. */
+  register: <A>(command: Command<A>) => void;
+  /** Define many, in order. Not transactional: the throwing record is the one that failed. */
+  registerAll: (commands: readonly AnyCommand[]) => void;
+  get: (id: string) => AnyCommand | undefined;
+  /** Every command, in registration order. */
+  list: () => readonly AnyCommand[];
+  /** Commands whose `when` holds right now — what a surface iterates. */
+  visible: () => readonly AnyCommand[];
+  /** Commands declaring `placement`, visible right now, sorted by `group` then title. */
+  forPlacement: (placement: Placement) => readonly AnyCommand[];
+  isVisible: (id: string) => boolean;
+  isEnabled: (id: string) => boolean;
+  /** The `requires` sentence when a visible command is disabled; `undefined` when it is usable. */
+  disabledReason: (id: string) => string | undefined;
+  /** The full refusal sentence, for an agent or a tooltip. `undefined` when the command is usable. */
+  refusalMessage: (id: string) => string | undefined;
+  /** Run a command. Throws on an unknown id, or {@link CommandUnavailableError} when refused. */
+  run: (id: string, args?: CommandArgs) => void | Promise<void>;
+  /** The chord index, conflict-checked at registration. */
+  keymap: Keymap;
+  /** Resolve a keyboard event through a scope stack and run what it hits. */
+  handleKeyEvent: (event: KeyChordEvent, scopeStack: readonly KeyScope[]) => string | undefined;
+  /** The context the predicates are currently reading — exposed for surfaces that need a snapshot. */
+  context: () => CommandContext;
+}
+
+export interface CommandRegistryOptions {
+  /** The live context. Called per predicate evaluation; a reactive record makes this free. */
+  getContext: () => CommandContext;
+  /** Format chords with mac glyphs. Defaults to platform detection inside the keymap. */
+  mac?: boolean;
+}
+
+/**
+ * Build an empty registry.
+ *
+ * There is deliberately no module-level singleton here: the app creates one in its bootstrap and
+ * passes it down, so tests, the CI checks and a future second window each get their own.
+ */
+export function createCommandRegistry(options: CommandRegistryOptions): CommandRegistry {
+  const commands = new Map<string, AnyCommand>();
+  const keymap = createKeymap(options.mac === undefined ? {} : { mac: options.mac });
+
+  function mustGet(id: string): AnyCommand {
+    const command = commands.get(id);
+    if (!command) {
+      throw new Error(`unknown command "${id}"`);
+    }
+    return command;
+  }
+
+  function visibleWith(command: AnyCommand, ctx: CommandContext): boolean {
+    return command.when?.(ctx) ?? true;
+  }
+
+  function enabledWith(command: AnyCommand, ctx: CommandContext): boolean {
+    if (!visibleWith(command, ctx)) {
+      return false;
+    }
+    // `enablement` defaults to `when`: a command that only declared `when` is enabled exactly when
+    // It is shown, which is the behaviour every existing hand-wired control already has.
+    return command.enablement?.(ctx) ?? true;
+  }
+
+  const registry: CommandRegistry = {
+    register(command) {
+      if (!ID_PATTERN.test(command.id)) {
+        throw new Error(
+          `invalid command id "${command.id}" — ids are "<category>.<verb>", ` +
+            `e.g. "selection.duplicate" or "view.toggleDock.right"`,
+        );
+      }
+      if (commands.has(command.id)) {
+        throw new Error(
+          `duplicate command id "${command.id}" — a capability has exactly one definition site`,
+        );
+      }
+      if (!command.title) {
+        throw new Error(
+          `command "${command.id}" has no title — the record is where actions are named`,
+        );
+      }
+      const violations = checkRecordPlacements(command);
+      if (violations.length > 0) {
+        throw new Error(`command "${command.id}" ${violations[0]!.message}`);
+      }
+      // Chord conflicts throw from the keymap; do this LAST so a rejected record leaves the
+      // Registry untouched in every failure mode.
+      keymap.add(command);
+      commands.set(command.id, command as AnyCommand);
+    },
+    registerAll(list) {
+      for (const command of list) {
+        registry.register(command);
+      }
+    },
+    get(id) {
+      return commands.get(id);
+    },
+    list() {
+      return [...commands.values()];
+    },
+    visible() {
+      const ctx = options.getContext();
+      return [...commands.values()].filter((command) => visibleWith(command, ctx));
+    },
+    forPlacement(placement) {
+      const ctx = options.getContext();
+      return [...commands.values()]
+        .filter(
+          (command) =>
+            (command.menus ?? ["palette"]).includes(placement) && visibleWith(command, ctx),
+        )
+        .toSorted(
+          (a, b) => (a.group ?? "").localeCompare(b.group ?? "") || a.title.localeCompare(b.title),
+        );
+    },
+    isVisible(id) {
+      return visibleWith(mustGet(id), options.getContext());
+    },
+    isEnabled(id) {
+      return enabledWith(mustGet(id), options.getContext());
+    },
+    disabledReason(id) {
+      const command = mustGet(id);
+      const ctx = options.getContext();
+      return enabledWith(command, ctx) ? undefined : (command.requires ?? GENERIC_REQUIREMENT);
+    },
+    refusalMessage(id) {
+      const reason = registry.disabledReason(id);
+      return reason === undefined ? undefined : refusalSentence(id, reason);
+    },
+    run(id, args = {}) {
+      const command = mustGet(id);
+      const ctx = options.getContext();
+      if (!enabledWith(command, ctx)) {
+        throw new CommandUnavailableError(id, command.requires ?? GENERIC_REQUIREMENT);
+      }
+      return command.run(ctx, args as never);
+    },
+    keymap,
+    handleKeyEvent(event, scopeStack) {
+      /* NARROWEST AVAILABLE wins, not narrowest.
+         A chord bound to a command whose `when` is false is not a hit — the key falls through to
+         the browser rather than being swallowed by an action that is not there. It used to fall
+         through to the browser and NOWHERE ELSE: `resolveEvent` answers with the first scope that
+         binds the chord, so a hidden narrow binding also hid every wider one behind it. That is a
+         defect the caret scope was about to make real. `format.link` binds ⌘K at `caret`, and the
+         caret stack is live in every parent-realm text field too (`caret.active` folds both, by
+         design — see `commands/context.ts`); its `when` is false there, so ⌘K would have resolved
+         to a hidden record and stopped reaching `palette.open`, and the omnibox would have gone
+         quiet in every panel field with nothing to show for it.
+         Walking the stack one scope at a time and taking the first VISIBLE claimant is what
+         "shadowing" has to mean: a command shadows a wider one while it is THERE. */
+      let hit: KeymapMatch | undefined;
+      for (const scope of scopeStack) {
+        const match = keymap.resolveEvent(event, [scope]);
+        if (match && registry.isVisible(match.commandId)) {
+          hit = match;
+          break;
+        }
+      }
+      if (!hit) {
+        return;
+      }
+      // Visible but disabled — ⌘Z with no history, Delete on the root. The chord IS claimed (the
+      // Action exists here, it just cannot act right now, and letting the browser have it would be
+      // Worse), but running it would throw CommandUnavailableError straight out of the keydown
+      // Listener. Claim it silently instead of making every caller wrap dispatch in a try/catch.
+      if (!registry.isEnabled(hit.commandId)) {
+        return hit.commandId;
+      }
+      void registry.run(hit.commandId);
+      return hit.commandId;
+    },
+    context: options.getContext,
+  };
+  return registry;
+}

package/src/component-props.ts

@@ -12,6 +12,7 @@
 
 import type { JsonValue } from "./types";
 import type { JxMutableNode } from "@jxsuite/schema/types";
+import { isPrivateStateKey } from "@jxsuite/schema/guards";
 
 /** One editable prop row: the state key and its current default value (undefined = none). */
 export interface ComponentPropEntry {
@@ -60,8 +61,8 @@ export function componentPropEntries(doc: JxMutableNode | null | undefined): Com
   const state = (doc?.state ?? {}) as Record<string, unknown>;
   const out: ComponentPropEntry[] = [];
   for (const [name, def] of Object.entries(state)) {
-    if (name.startsWith("#")) {
-      continue; // Private entries are not props (the CEM-export rule).
+    if (isPrivateStateKey(name)) {
+      continue; // Private entries are not props (spec.md §5.6).
     }
     const shape = propShape(def);
     if (!shape) {

package/src/content/draft-state.ts

@@ -0,0 +1,106 @@
+/**
+ * The draft axis (§7.6) — what a draft IS, and whether drafts are listed. One place, every list.
+ *
+ * It is deliberately its own module rather than a field on a pane's state and rather than a section
+ * of `entry-model.ts`. Two reasons, and the second is why the definitions live here beside the
+ * flag:
+ *
+ * 1. **The perspective is a fact about the AUTHOR, not the surface.** A draft filter that belonged to
+ *    the Library would answer for the Library only, and the same author would then be shown their
+ *    draft in the collection grid, in the pages grid and in Quick Open a second later.
+ * 2. **Every list that must obey it has to be able to import it.** `entry-model.ts` asks
+ *    `grid/sources/content-source.ts` where a collection's entries live, so the grid source cannot
+ *    ask `entry-model.ts` back what a draft is — `import/no-cycle` is an error in this repo, and
+ *    the cycle would be real. This module has ONE runtime dependency (`reactivity`), so the flag
+ *    and the predicate are importable from a data module, a panel and a command alike. That is the
+ *    property that lets the surfaces actually share them, instead of each carrying its own `draft
+ *    === true`.
+ */
+
+import { reactive } from "../reactivity";
+import type { ContentTypeSchema } from "@jxsuite/schema/types";
+
+/** The conventional boolean frontmatter field that marks an entry a draft (§7.6). */
+export const DRAFT_FIELD = "draft";
+
+/**
+ * What a draft IS, in one sentence, for every surface that shows the pill.
+ *
+ * Deliberately does not say "excluded from production builds" — the spec's §7.6 bullet describes an
+ * intent the build does not implement yet (`packages/compiler`'s `site/site-build.ts` says so
+ * beside `$sitemap`), and a badge that promises a file will not ship when it will is the exact
+ * class of confident-wrong statement §16 exists to end. When the compiler learns to drop drafts,
+ * this constant changes and every surface changes with it.
+ */
+export const DRAFT_MEANING =
+  "Marked a draft. Studio filters drafts out of its own lists; the build does not exclude them yet.";
+
+// ─── What a draft is ─────────────────────────────────────────────────────────
+
+/**
+ * Whether this record is marked a draft. Only the literal `true` counts — never a truthy string.
+ *
+ * Takes the entry's FIELDS, whichever record they live in — `content/entry-fields.ts` answers that,
+ * because a JSON collection's entry has no frontmatter and its `draft` key is on the document.
+ */
+export function isDraftEntry(fields: Record<string, unknown> | null | undefined): boolean {
+  return fields?.[DRAFT_FIELD] === true;
+}
+
+/** Whether this collection's schema declares the draft field as a boolean. */
+export function schemaDeclaresDraft(schema: ContentTypeSchema | null | undefined): boolean {
+  return schema?.properties?.[DRAFT_FIELD]?.type === "boolean";
+}
+
+/**
+ * Whether a surface should show a draft affordance for this entry at all.
+ *
+ * A collection that does not declare `draft` has no draft workflow, and painting a "Published" pill
+ * on its entries — or a Draft column over its grid — would be inventing a state the project never
+ * defined. An entry that carries `draft: true` anyway — because someone typed it — DOES show,
+ * because the fact is on disk.
+ */
+export function hasDraftAxis(
+  schema: ContentTypeSchema | null | undefined,
+  fields?: Record<string, unknown> | null,
+): boolean {
+  return schemaDeclaresDraft(schema) || isDraftEntry(fields);
+}
+
+// ─── The perspective ─────────────────────────────────────────────────────────
+
+/** The perspective. `includeDrafts` false — the default — hides entries marked `draft: true`. */
+export const draftView = reactive({ includeDrafts: false });
+
+/** Whether draft entries are currently listed. */
+export function includingDrafts(): boolean {
+  return draftView.includeDrafts;
+}
+
+/**
+ * Set the perspective.
+ *
+ * A setter, never a toggle: `content.setIncludeDrafts` names the STATE it reaches, so a manifest
+ * step, an assistant call and a checkbox all land on the same value however many times they run
+ * (plan §13.1, and the rule `tests/app-commands.test.ts` enforces).
+ *
+ * Setting the flag is all this does. Repainting the lists that read it belongs to the command — see
+ * `content/entry-commands.ts` — because a data module may not reach into the workspace.
+ */
+export function setIncludeDrafts(include: boolean): void {
+  draftView.includeDrafts = include;
+}
+
+/**
+ * Apply the "including drafts" perspective to a list.
+ *
+ * `includeDrafts` true returns the input array unchanged — identity, not a copy — so a caller can
+ * cheaply tell that nothing was filtered.
+ */
+export function applyDraftFilter<T>(
+  items: readonly T[],
+  fieldsOf: (item: T) => Record<string, unknown> | null | undefined,
+  includeDrafts: boolean,
+): readonly T[] {
+  return includeDrafts ? items : items.filter((item) => !isDraftEntry(fieldsOf(item)));
+}