@jxsuite/studio 6.1.2 → 8.0.0

package/src/content/page-summaries.ts

@@ -0,0 +1,129 @@
+/**
+ * What the Content workspace's Pages list says about each page beyond its file: the template it is
+ * drawn in, the collection a dynamic page expands over, and whether it is marked a draft
+ * (`specs/studio.md` §22.5, the Content-Pages board: Title, URL, Template, Status, Edited).
+ *
+ * The scan behind the Content home knows each page's FILE; its `$layout`, `$paths` and `draft` are
+ * inside it. So this reads each page once, through the same parse the editor uses, and keeps the
+ * answer until a file event drops it ({@link invalidatePageSummaries}, wired beside the
+ * template-page index in `studio.ts`). The read never rejects: a page that cannot be read states
+ * nothing, and is listed by its route alone.
+ *
+ * @docs studio/projects/browse
+ */
+
+import { isNonNullObject } from "@jxsuite/schema/guards";
+import { getPlatform, hasPlatform } from "../platform";
+import { pageFactsOf } from "./collection-pages";
+import { DRAFT_FIELD } from "./draft-state";
+import type { FormatFrontmatter } from "../format/format-host";
+import type { JxMutableNode } from "@jxsuite/schema/types";
+
+/** One page, as the Pages list states it. */
+export interface PageSummary {
+  path: string;
+  /** Its `$layout`: a path, `false` (no layout), or `undefined` (the project's default). */
+  layout: string | false | undefined;
+  /** The collection its `$paths` expands over, or `null` for a page of its own. */
+  contentType: string | null;
+  /** Whether the page carries `draft: true`, the one draft marker a page can have. */
+  draft: boolean;
+}
+
+/** What a page that could not be read states: nothing. */
+function unread(path: string): PageSummary {
+  return { contentType: null, draft: false, layout: undefined, path };
+}
+
+/** The summary a parsed page states. Exported so the rule is assertable without a platform. */
+export function pageSummaryOf(
+  path: string,
+  document: JxMutableNode | null,
+  frontmatter: FormatFrontmatter | null,
+): PageSummary {
+  const { contentType, layout } = pageFactsOf(document, frontmatter);
+  const draft = frontmatter?.[DRAFT_FIELD] === true || document?.[DRAFT_FIELD] === true;
+  return { contentType, draft, layout, path };
+}
+
+/** Read one page. */
+async function readSummary(path: string): Promise<PageSummary> {
+  try {
+    const source = await getPlatform().readFile(path);
+    if (path.endsWith(".json")) {
+      const parsed: unknown = JSON.parse(source);
+      /* SAFETY: a `.json` file under `pages/` is a page document by the project layout; one that is
+         not an object states nothing, which is the branch below. */
+      return isNonNullObject(parsed) && !Array.isArray(parsed)
+        ? pageSummaryOf(path, parsed as JxMutableNode, null)
+        : unread(path);
+    }
+    const { parseSourceForPath } = await import("../files/file-ops");
+    const parsed = await parseSourceForPath(path, source);
+    /* SAFETY: a format class's parser returns its file as a Jx element tree (the format contract);
+       only `$layout`, `$paths` and `draft` are read off it. */
+    return pageSummaryOf(path, parsed.document as JxMutableNode, parsed.frontmatter);
+  } catch {
+    return unread(path);
+  }
+}
+
+// ─── The cache ───────────────────────────────────────────────────────────────
+
+/** At most this many pages are read for one list; the rest are listed by route alone. */
+export const PAGE_READ_LIMIT = 300;
+
+let _cache: { key: string; pages: Map<string, PageSummary> } | null = null;
+let _loading: { key: string; read: Promise<void> } | null = null;
+let _epoch = 0;
+const _listeners = new Set<() => void>();
+
+/**
+ * The pages' summaries as they stand, keyed by path: the map, or `null` while they are being read
+ * (which starts the read; listeners are told when it lands).
+ *
+ * @param paths The page files, in the order the list draws them.
+ */
+export function peekPageSummaries(
+  paths: readonly string[],
+): ReadonlyMap<string, PageSummary> | null {
+  const key = paths.join("\n");
+  if (_cache?.key === key) {
+    return _cache.pages;
+  }
+  if (!hasPlatform()) {
+    return new Map(paths.map((path) => [path, unread(path)]));
+  }
+  if (_loading?.key !== key) {
+    const epoch = _epoch;
+    const read = Promise.all(paths.slice(0, PAGE_READ_LIMIT).map((path) => readSummary(path))).then(
+      (summaries) => {
+        if (epoch !== _epoch || _loading?.read !== read) {
+          return;
+        }
+        _loading = null;
+        _cache = { key, pages: new Map(summaries.map((summary) => [summary.path, summary])) };
+        for (const listener of _listeners) {
+          listener();
+        }
+      },
+    );
+    _loading = { key, read };
+  }
+  return null;
+}
+
+/** Forget every summary. The next list re-reads its pages. */
+export function invalidatePageSummaries(): void {
+  _epoch += 1;
+  _cache = null;
+  _loading = null;
+}
+
+/** Be told when a read lands. Returns the function that stops it. */
+export function onPageSummariesRead(listener: () => void): () => void {
+  _listeners.add(listener);
+  return () => {
+    _listeners.delete(listener);
+  };
+}

package/src/content/record-entry.ts

@@ -0,0 +1,201 @@
+/**
+ * One record of a file-backed collection, edited as an entry: a form over one CSV row.
+ *
+ * A collection whose `source` names one file (`./content/projects.csv`) has one entry per record
+ * (`content/file-records.ts`). The file's own grid edits all of them at once; this is the form-only
+ * entry editor (`content/entry-editor.ts`, `specs/studio.md` §22.5) over ONE of them, so opening a
+ * project from the Content workspace opens that project's fields, typed by the collection's schema,
+ * rather than a table the reader has to find the row in.
+ *
+ * **It is an editor of the file's grid tab, not a second document.** The record's fields are read
+ * from, and written into, the grid controller's edit buffer (`grid/edit-buffer.ts`), the same
+ * buffer the grid's cells write. So ⌘S saves the file through the grid's one commit path (with its
+ * staleness check and its untouched-cell rule), ⌘Z undoes a field edit exactly as it undoes a cell,
+ * the tab's dirty dot is the buffer's, and switching the tab's editor to Grid shows the edit as a
+ * pending cell.
+ *
+ * Which record the form shows is per tab, here, keyed by the tab's id. An opener names the record
+ * by its place among the file's data rows, because that is all a scan knows and the rows may not
+ * have loaded yet; the place resolves to the row's key the moment they have, reactively, so the
+ * form draws the record as soon as it exists. Previous / Next then name rows by key, which a save
+ * that re-reads the file does not move.
+ *
+ * @docs studio/projects/content-types
+ */
+
+import { onScopeDispose, reactive } from "../reactivity";
+import { activateTab, workspace } from "../workspace/workspace";
+import { getGridController } from "../grid/grid-controller";
+import { isBoolean, isNonNullObject, isNumber, isString } from "@jxsuite/schema/guards";
+import { entryDay } from "./entry-summaries";
+import type { GridCellValue } from "../grid/grid-source";
+import type { EntryFields } from "./entry-fields";
+import type { JsonValue } from "../types";
+import type { Tab } from "../tabs/tab";
+
+/** A value that already starts with a calendar day, which a date input reads as it is. */
+const ISO_DAY = /^\d{4}-\d{2}-\d{2}/;
+
+/**
+ * The `canvasMode` the entry form draws under. Defined here, with the record it may be over, and
+ * re-exported by `entry-editor.ts`, which imports this module.
+ */
+export const ENTRY_MODE = "entry";
+
+/** A tab's record: by its row key, or (until the rows load) by its place among the data rows. */
+type ShownRecord = { key: string } | { row: number };
+
+/** Tab id → the record its entry form shows. */
+const shown = reactive(new Map<string, ShownRecord>());
+
+/** The key of the record a tab's entry form shows, or null when it shows none (yet). Tracks. */
+export function recordOf(tab: Tab): string | null {
+  const record = shown.get(tab.id);
+  if (record === undefined) {
+    return null;
+  }
+  if ("key" in record) {
+    return record.key;
+  }
+  return getGridController(tab)?.state.rows[record.row]?.key ?? null;
+}
+
+/** Whether the tab's entry form is over a record of its file, chosen or still loading. Tracks. */
+export function hasRecord(tab: Tab): boolean {
+  return shown.has(tab.id);
+}
+
+/** Show the record keyed `rowKey` in this tab's entry form. */
+export function showRecord(tab: Tab, rowKey: string): void {
+  shown.set(tab.id, { key: rowKey });
+}
+
+/** Forget the tab's record (its tab closed, or the record is gone). */
+export function forgetRecord(tab: Tab): void {
+  shown.delete(tab.id);
+}
+
+/** Whether this tab's entry form is over a record of its grid rather than over its own document. */
+export function isRecordTab(tab: Tab): boolean {
+  return hasRecord(tab) && getGridController(tab) !== null;
+}
+
+/**
+ * The record's fields as the form reads them: every column's current value, pending edits included,
+ * typed as the grid types it (a number column's cell is a number, a list column's a list of
+ * strings). A cell with nothing in it is absent, as an empty frontmatter key would be.
+ */
+export function recordFields(tab: Tab): EntryFields {
+  const controller = getGridController(tab);
+  const rowKey = recordOf(tab);
+  if (!controller || rowKey === null) {
+    return {};
+  }
+  const fields: EntryFields = {};
+  for (const column of controller.state.columns) {
+    const value = controller.buffer.effectiveValue(rowKey, column.field);
+    if (value === null || value === "") {
+      continue;
+    }
+    if (column.kind === "date" && isString(value) && !ISO_DAY.test(value)) {
+      /* A CSV spells a date the way its spreadsheet did (`6/3/2026`), which a date input cannot
+         show. The form is shown the day it means; the cell keeps its spelling until it is edited. */
+      fields[column.field] = entryDay(value) || value;
+      continue;
+    }
+    fields[column.field] = isNonNullObject(value) && !Array.isArray(value) ? value.$ref : value;
+  }
+  return fields;
+}
+
+/** A form value as the cell it is written into. */
+function cellValue(value: JsonValue | undefined): GridCellValue {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => (isString(item) ? item : JSON.stringify(item)));
+  }
+  if (isString(value) || isNumber(value) || isBoolean(value)) {
+    return value;
+  }
+  // A cell holds text: an object a field produced is written as its JSON.
+  return JSON.stringify(value);
+}
+
+/**
+ * Write a form patch into the record's row as one undo step. A field with no column is ignored: the
+ * file has nowhere to keep it, and adding a column is the grid's decision, not a form's.
+ */
+export function commitRecordFields(tab: Tab, patch: Record<string, JsonValue | undefined>): void {
+  const controller = getGridController(tab);
+  const rowKey = recordOf(tab);
+  if (!controller || rowKey === null) {
+    return;
+  }
+  const columns = new Set(controller.state.columns.map((column) => column.field));
+  controller.buffer.group(() => {
+    for (const [field, value] of Object.entries(patch)) {
+      if (columns.has(field)) {
+        controller.buffer.setCell(rowKey, field, cellValue(value));
+      }
+    }
+  });
+}
+
+/** Where the shown record sits among the file's rows, for the form's Previous / Next. */
+export interface RecordPlace {
+  /** Its place among the rows, from 0; -1 when the record is not (or no longer) among them. */
+  index: number;
+  total: number;
+  previous: string | null;
+  next: string | null;
+}
+
+/** The shown record's place among the grid's rows, in file order. Tracks the rows. */
+export function recordPlace(tab: Tab): RecordPlace {
+  const controller = getGridController(tab);
+  const rowKey = recordOf(tab);
+  const rows = controller?.state.rows ?? [];
+  const index = rowKey === null ? -1 : rows.findIndex((row) => row.key === rowKey);
+  return {
+    index,
+    next: index === -1 ? null : (rows[index + 1]?.key ?? null),
+    previous: index <= 0 ? null : (rows[index - 1]?.key ?? null),
+    total: rows.length,
+  };
+}
+
+/**
+ * Open one record of a file-backed collection in its entry form.
+ *
+ * Opens (or reveals) the file's grid tab, names the record at `row` (its place among the file's
+ * data rows, as `content/file-records.ts` numbers it) and puts the tab in the entry editor. The
+ * form draws the record once the grid's rows have loaded ({@link recordOf}).
+ *
+ * @returns The tab, or null when the file could not be opened at all.
+ */
+export async function openRecordEntry(path: string, row: number): Promise<Tab | null> {
+  /* Dynamic for the reason `entry-open.ts` gives: `files/files.ts` reaches the platform, the format
+     registry and the packages layer. */
+  const { openFileInTab } = await import("../files/files");
+  await openFileInTab(path);
+  const tab = workspace.tabs.get(path) ?? null;
+  if (!tab || !getGridController(tab)) {
+    return tab;
+  }
+  if (!shown.has(tab.id)) {
+    // The choice lives as long as the tab: a file reopened later starts on no record.
+    tab.scope.run(() => {
+      onScopeDispose(() => forgetRecord(tab));
+    });
+  }
+  shown.set(tab.id, { row });
+  if (!tab.capabilities.modes.includes(ENTRY_MODE)) {
+    tab.capabilities.modes.unshift(ENTRY_MODE);
+  }
+  tab.session.ui.canvasMode = ENTRY_MODE;
+  tab.session.ui.preview = false;
+  activateTab(tab.id);
+  return tab;
+}

package/src/content/writing-banner.ts

@@ -0,0 +1,177 @@
+/// <reference lib="dom" />
+/**
+ * The writing-mode banner: what the canvas says while a collection entry is written inside its
+ * template's layout (`specs/studio.md` §22.5).
+ *
+ * "Writing mode: text and media are editable, the layout is locked", with **Edit the <item>
+ * template in Design**. The template it opens is the collection's template PAGE when the project
+ * has one (the page whose `$paths.contentType` names the collection,
+ * `content/collection-pages.ts`), because that is the page that decides what an entry looks like on
+ * the site; with no such page it is the layout the entry is drawn in. Opening either activates it,
+ * and activating a page or a layout enters Design (§22.1).
+ *
+ * One banner per pane, mounted into the host the canvas stage draws above Edit's column
+ * (`surfaces/canvas-stage.json`'s `writing-banner`); `canvas/canvas-render.ts` hands the host over
+ * and repaints it. It is the one band Edit draws over a document: an ordinary page opens at the top
+ * with nothing above it (studio.md §4.2).
+ *
+ * @docs studio/projects/content-types
+ */
+
+import { isString } from "@jxsuite/schema/guards";
+import { paneRegion } from "../ui/regions";
+import { workspace } from "../workspace/workspace";
+import { collectionForFile } from "./collection-match";
+import { contentCollection, templateDisplayName } from "./content-collections";
+import {
+  entryLayoutPath,
+  entryLocale,
+  onCollectionPagesRead,
+  peekCollectionPage,
+} from "./collection-pages";
+import { mountWritingBannerSurface } from "../surfaces/writing-banner";
+import type { Tab } from "../tabs/tab";
+import type { WritingBannerHandle, WritingBannerView } from "../surfaces/writing-banner";
+
+/** The sentence the banner always says. */
+export const WRITING_MODE_TEXT = "Writing mode: text and media are editable, the layout is locked";
+
+/** Where the banner's button goes, and what it is called. `null` when there is nothing to open. */
+export interface BannerTarget {
+  path: string;
+  /** The button's text, as `WritingBannerView.actionLabel` draws it. */
+  actionLabel: string;
+}
+
+/**
+ * What an entry's banner opens: its collection's page, else the layout it is drawn in.
+ *
+ * Each label names the file it opens. The collection's page is called what the Content home's
+ * header line calls it ("Design the post page"), so the two surfaces that reach it agree; a layout
+ * is a template everywhere in Studio, and is called one by its own name.
+ */
+export function bannerTarget(tab: Tab): BannerTarget | null {
+  const match = collectionForFile(tab.documentPath);
+  if (!match) {
+    return null;
+  }
+  const item = contentCollection(match.name)?.item ?? "entry";
+  const page = peekCollectionPage(match.name, entryLocale(tab.documentPath));
+  if (page) {
+    return { actionLabel: `Design the ${item} page`, path: page.path };
+  }
+  const own = tab.doc.document.$layout ?? tab.doc.content.frontmatter.$layout;
+  const layout = entryLayoutPath(isString(own) || own === false ? own : undefined, page ?? null);
+  if (!layout) {
+    return null;
+  }
+  return {
+    actionLabel: `Edit the ${templateDisplayName(layout)} template in Design`,
+    path: layout.replace(/^\.\//, ""),
+  };
+}
+
+/** What the banner over `tab` in `paneId` draws. */
+export function writingBannerView(paneId: string, tab: Tab): WritingBannerView {
+  const target = bannerTarget(tab);
+  return {
+    actionLabel: target?.actionLabel ?? "",
+    actionState: target ? "shown" : "hidden",
+    region: paneRegion(paneId, "writing-banner"),
+    text: WRITING_MODE_TEXT,
+  };
+}
+
+// ─── Mounting ────────────────────────────────────────────────────────────────
+
+interface StandingBanner {
+  host: HTMLElement;
+  handle: WritingBannerHandle;
+  /** The tab the banner was last drawn for: what its button opens the template of. */
+  tabId: string | null;
+}
+
+const _banners = new Map<string, StandingBanner>();
+let _unlisten: (() => void) | null = null;
+
+/** Open the template of the entry a pane's banner is over. */
+async function openTemplate(paneId: string): Promise<void> {
+  const tabId = _banners.get(paneId)?.tabId;
+  const tab = tabId ? workspace.tabs.get(tabId) : undefined;
+  const target = tab ? bannerTarget(tab) : null;
+  if (!target) {
+    return;
+  }
+  const { openFileInTab } = await import("../files/files");
+  await openFileInTab(target.path);
+}
+
+/** Repaint every banner: the collection pages it names its button from have just been read. */
+function repaintAll(): void {
+  for (const [paneId, banner] of _banners) {
+    const tab = banner.tabId ? workspace.tabs.get(banner.tabId) : undefined;
+    if (tab) {
+      banner.handle.update(writingBannerView(paneId, tab));
+    }
+  }
+}
+
+/**
+ * Take a pane's banner host, or let it go (`null`).
+ *
+ * The stage announces the host when it draws the `writing` or `banner` lead; the same host comes
+ * back on every repaint that keeps that lead, so a second announcement of it changes nothing.
+ */
+export function attachWritingBanner(paneId: string, host: HTMLElement | null): void {
+  const held = _banners.get(paneId);
+  if (held?.host === host) {
+    return;
+  }
+  if (held) {
+    held.handle.dispose();
+    _banners.delete(paneId);
+  }
+  if (!host) {
+    return;
+  }
+  _unlisten ??= onCollectionPagesRead(repaintAll);
+  const handle = mountWritingBannerSurface(
+    host,
+    {
+      actionLabel: "",
+      actionState: "hidden",
+      region: paneRegion(paneId, "writing-banner"),
+      text: WRITING_MODE_TEXT,
+    },
+    {
+      openTemplate: () => {
+        void openTemplate(paneId);
+      },
+    },
+  );
+  _banners.set(paneId, { handle, host, tabId: null });
+}
+
+/** Draw a pane's banner for the entry it is over. A pane with no banner host is left alone. */
+export function renderWritingBanner(paneId: string, tab: Tab): void {
+  const banner = _banners.get(paneId);
+  if (!banner) {
+    return;
+  }
+  banner.tabId = tab.id;
+  banner.handle.update(writingBannerView(paneId, tab));
+}
+
+/** Take a pane's banner down (its lead went away, or the pane did). Idempotent. */
+export function detachWritingBanner(paneId: string): void {
+  attachWritingBanner(paneId, null);
+}
+
+/** Take every banner down — tests. */
+export function resetWritingBanners(): void {
+  for (const paneId of _banners.keys()) {
+    detachWritingBanner(paneId);
+  }
+  _unlisten?.();
+  _unlisten = null;
+}

package/src/create/add-new-commands.ts

@@ -0,0 +1,185 @@
+/**
+ * `file.new`: Add new, as a command record (`specs/studio.md` §9.1.1).
+ *
+ * One record, four doors: the palette, the Command Bar's overflow, the chords, and the assistant.
+ * The Site panel's **+** and the Content home's **New** run it too, so there is one way in and
+ * every surface is a rendering of it.
+ *
+ * **Two behaviours, chosen by the arguments.** With a `name`, it creates — kind, name and options
+ * through `deriveCreation`, refused by throwing the sentence the dialog would print, written by the
+ * flow's one write path — and opens nothing modal. Without one, it OPENS the dialog on the kind
+ * asked for and returns at once, never awaiting it: a `run` that waits on a person is the second
+ * deletion rule of `studio-ui-guidelines.md` §12.4, and returning is what keeps this record a tool.
+ * The model is told as much in the description, and the report says which of the two happened.
+ *
+ * **The chords.** `⌘N` where the host owns it — the desktop app — and `⌘⌥N` everywhere, because a
+ * browser keeps `⌘N` for a new window and never delivers it to the page.
+ *
+ * DOM-free at import: the flow is loaded on the first run, so `commands/app-commands.ts` can list
+ * this record in a bare Bun process.
+ *
+ * @docs studio/projects/pages-layouts-components
+ */
+
+import {
+  argsSchema,
+  derivedEnumProperty,
+  enumArg,
+  enumProperty,
+  optionalStringArg,
+  stringProperty,
+} from "../commands/command-args";
+import { entryCollections } from "../content/entry-model";
+import { CREATION_KINDS } from "./add-new";
+import type { CreationKind } from "./add-new";
+import type { AddNewRequest, AddNewResult } from "./add-new-flow";
+import type { CommandArgValues } from "../commands/command-args";
+import type { AiToolReport, AnyCommand, CommandRegistry } from "../commands/registry";
+
+/** The id, which the Site panel and the Content home run. */
+export const FILE_NEW = "file.new";
+
+/** What one run did: a creation, or the dialog it opened instead. */
+interface LastRun {
+  created: AddNewResult | null;
+  opened: CreationKind | null;
+}
+
+/** The last run, for `report`, which reads module state rather than an injected dep. */
+let _lastRun: LastRun = { created: null, opened: null };
+
+/** The arguments as a request, each one read with the reader its schema names. */
+function requestOf(args: CommandArgValues): AddNewRequest {
+  const request: AddNewRequest = {};
+  if (args.kind !== undefined) {
+    request.kind = enumArg(FILE_NEW, args, "kind", CREATION_KINDS);
+  }
+  const name = optionalStringArg(FILE_NEW, args, "name");
+  if (name !== undefined) {
+    request.name = name;
+  }
+  const collection = optionalStringArg(FILE_NEW, args, "collection");
+  if (collection !== undefined) {
+    request.collection = collection;
+  }
+  const locale = optionalStringArg(FILE_NEW, args, "locale");
+  if (locale !== undefined) {
+    request.locale = locale;
+  }
+  const template = optionalStringArg(FILE_NEW, args, "template");
+  if (template !== undefined) {
+    request.template = template;
+  }
+  return request;
+}
+
+/** The sentence the model reads after a run. */
+function reportFor(): AiToolReport {
+  const { created, opened } = _lastRun;
+  if (created) {
+    return { summary: describe(created), wrote: created.wrote };
+  }
+  return {
+    summary:
+      `Opened Add new on ${opened ?? "page"} for the person; nothing is created until they ` +
+      "confirm. Pass a name to create without the dialog.",
+    wrote: [],
+  };
+}
+
+/** One sentence naming what a creation made. */
+export function describe(result: AddNewResult): string {
+  switch (result.kind) {
+    case "page": {
+      return `Created the page ${result.path}${result.route ? `, which opens at ${result.route}` : ""}, and opened it in Design.`;
+    }
+    case "component": {
+      return `Created <${result.tag ?? ""}> in ${result.path}; it is listed under Components in the Site panel and open in Design.`;
+    }
+    case "template": {
+      return `Created the template ${result.path} and opened it in Design.`;
+    }
+    case "entry": {
+      return `Created the entry ${result.path} and opened it.`;
+    }
+    case "collection": {
+      return `Created the ${result.path.replace(/^content\//, "")} collection, writing ${result.wrote.join(", ")}.`;
+    }
+    default: {
+      return `Uploaded ${result.wrote.length === 1 ? "1 file" : `${result.wrote.length} files`} to public/media/.`;
+    }
+  }
+}
+
+/** The `file.new` record. */
+export function addNewCommands(): AnyCommand[] {
+  return [
+    {
+      aiTool: {
+        description:
+          "Create a page, collection, template, component or collection entry, the way Add new does: " +
+          "pass kind and name and it is written and opened, with the path derived from the name " +
+          "(pages/<slug>.json, layouts/<slug>.json, components/<tag>.json, a content/<name>/ " +
+          "collection). Without a name it only opens the Add new dialog for the person.",
+        name: "add_new",
+        report: () => reportFor(),
+      },
+      args: argsSchema(
+        {
+          collection: derivedEnumProperty(
+            () => entryCollections().map((collection) => collection.name),
+            "For an entry: the content collection it is created in.",
+          ),
+          kind: enumProperty(
+            CREATION_KINDS,
+            "What to create: page, collection, template, component, media (an upload) or entry.",
+          ),
+          locale: stringProperty(
+            "For a page or an entry of a localized collection: the language it is written in, one " +
+              "of the project's i18n locales such as fr-CA. A page in another language is saved in " +
+              "that language's folder and opens under its URL prefix.",
+          ),
+          name: stringProperty(
+            "The name. A page's URL, a template's file and a component's tag are derived from it. " +
+              "Omit it to open the Add new dialog instead of creating.",
+          ),
+          template: stringProperty(
+            "The template to start from: a layout such as base or layouts/base.json, article for a " +
+              "Markdown page, or blank for none. A collection uses it for its own page; a template " +
+              "is wrapped in it.",
+          ),
+        },
+        [],
+      ),
+      category: "File",
+      group: "1_file",
+      icon: "plus",
+      id: FILE_NEW,
+      keybinding: ["mod+n", "mod+alt+n"],
+      level: "project",
+      menus: ["commandbar/overflow", "palette"],
+      requires: "an open project",
+      run: async (_ctx, args) => {
+        const request = requestOf(args);
+        const flow = await import("./add-new-flow");
+        if (request.name !== undefined) {
+          _lastRun = { created: null, opened: null };
+          const created = await flow.createDirect({ ...request, name: request.name });
+          _lastRun = { created, opened: null };
+          return;
+        }
+        _lastRun = { created: null, opened: request.kind ?? "page" };
+        // Opened, never awaited: the dialog belongs to the person (studio-ui-guidelines.md §12.4).
+        void flow.openAddNew(request);
+      },
+      title: "Add New…",
+      undo: "none",
+      when: (ctx) => ctx.project.open,
+    },
+  ];
+}
+
+/** Register `file.new`. */
+export function registerAddNewCommands(registry: CommandRegistry): void {
+  registry.registerAll(addNewCommands());
+}