@jxsuite/studio 10.4.0 → 10.6.0

package/src/editor/slash-menu.ts

@@ -28,6 +28,7 @@
 
 import { openSlashMenuSurface } from "../surfaces/slash-menu";
 import { componentSlashCommands } from "./insert-component";
+import { elementName } from "../locale/element-names";
 import { rectOf } from "../utils/geometry";
 import type {
   SlashMenuGroup,
@@ -39,24 +40,41 @@ import type { SlashCommand } from "./inline-edit";
 
 // ─── Commands ─────────────────────────────────────────────────────────────────
 
-const SLASH_COMMANDS = [
-  { description: "Large heading", label: "Heading 1", tag: "h1" },
-  { description: "Medium heading", label: "Heading 2", tag: "h2" },
-  { description: "Small heading", label: "Heading 3", tag: "h3" },
-  { description: "Plain text", label: "Paragraph", tag: "p" },
-  { description: "Unordered list", label: "Bulleted List", tag: "ul" },
-  { description: "Numbered list", label: "Numbered List", tag: "ol" },
-  { description: "Quote block", label: "Blockquote", tag: "blockquote" },
-  { description: "Insert image", label: "Image", tag: "img" },
-  { description: "Divider line", label: "Horizontal Rule", tag: "hr" },
-  { description: "Button element", label: "Button", tag: "button" },
-  { description: "Anchor link", label: "Link", tag: "a" },
-  { description: "Preformatted code", label: "Code Block", tag: "pre" },
-  { description: "Insert table", label: "Table", tag: "table" },
-  { description: "Container", label: "Div", tag: "div" },
-  { description: "Section container", label: "Section", tag: "section" },
+/**
+ * The HTML elements the slash menu offers, in this order. Each row's label is the element's name in
+ * the locale catalog (`locale/element-names.ts`), so the menu, the Insert palette and the convert
+ * menu call an element the same thing in every language. A row carries no description: the
+ * catalog's are sentences, written for the palette's tooltips, and a menu row draws its description
+ * on the label's own line and cuts it off there, while a name like "Bulleted list" already says
+ * what the row inserts.
+ */
+const SLASH_TAGS = [
+  "h1",
+  "h2",
+  "h3",
+  "p",
+  "ul",
+  "ol",
+  "blockquote",
+  "img",
+  "hr",
+  "button",
+  "a",
+  "pre",
+  "table",
+  "div",
+  "section",
 ];
 
+/** The element rows, named in the reader's language at the moment the menu opens. */
+function elementCommands(): SlashCommand[] {
+  return SLASH_TAGS.map((tag) => ({
+    description: "",
+    label: elementName(tag),
+    tag,
+  }));
+}
+
 // ─── State ────────────────────────────────────────────────────────────────────
 
 /** Callbacks a caller passes to {@link showSlashMenu}/{@link showSlashMenuAtRect}. */
@@ -127,7 +145,7 @@ export function showSlashMenuAtRect(
  * on offer.
  */
 function standardCommands(): SlashCommand[] {
-  return [...SLASH_COMMANDS, ...componentSlashCommands()];
+  return [...elementCommands(), ...componentSlashCommands()];
 }
 
 /** Everything on offer right now: what the caller named, or the standard set. */

package/src/files/files.ts

@@ -286,6 +286,24 @@ export async function loadProject() {
   }
 }
 
+/**
+ * Show the documents the operating system asks of this window, now and from here on.
+ *
+ * Called once the window has finished loading whatever it holds, so a document opens on top of the
+ * restored session rather than being replaced by it. Called whether or not there is a project yet,
+ * because a welcome window can be given one later and then be asked for a document in it.
+ */
+export function followOpenDocuments(): void {
+  getPlatform().subscribeOpenDocument?.((path) => {
+    // A window whose project did not load has been told why, and has nowhere to put a tab.
+    if (!projectState) {
+      return;
+    }
+    // It reports its own failure ("Could not open …"), as it does for every other caller.
+    void openFileInTab(path);
+  });
+}
+
 // ─── Open Project (PAL-based) ─────────────────────────────────────────────
 
 /**

package/src/format/format-choices.ts

@@ -69,11 +69,11 @@ function declaresDocumentKind(kinds: readonly string[]): boolean {
 /**
  * Whether this path is (or is used as) a layout.
  *
- * Layouts are JSON at BOTH readers — `packages/compiler/src/site/layout-resolver.ts` `JSON.parse`s
- * and throws, `packages/studio/src/site-context.ts` `JSON.parse`s and silently returns null — and
- * there is no `"layout"` document kind for a format to declare, so this clause is hand-written and
- * cannot be derived. `layouts/` is excluded by {@link DOCUMENT_ROOTS} already; what remains is a
- * project whose `layout` points somewhere inside a document root.
+ * A layout is native at both readers — `packages/compiler/src/site/layout-resolver.ts` reads
+ * `.json` and `.jxn` and throws, `packages/studio/src/site-context.ts` `JSON.parse`s and silently
+ * returns null — and there is no `"layout"` document kind for a format to declare, so this clause
+ * is hand-written and cannot be derived. `layouts/` is excluded by {@link DOCUMENT_ROOTS} already;
+ * what remains is a project whose `layout` points somewhere inside a document root.
  */
 function isLayoutPath(path: string): boolean {
   const declared = projectState?.projectConfig?.layout;

package/src/format/format-host.ts

@@ -4,7 +4,9 @@
  * Format classes are auto-discovered server-side from the project imports map
  * (specs/extensions.md); the studio introspects them via the PAL (`listFormats`) and invokes
  * parse/serialize capabilities via `formatAction` (POST /__studio/format in the dev server, RPC on
- * desktop). The studio itself holds zero format knowledge — `.json` is the single native built-in.
+ * desktop). The studio holds no other format knowledge: `.json` is native, and `.jxn` is read and
+ * written here in the same process with the same code as everywhere else (`spec.md` §22), so a host
+ * with no extension runtime has it too.
  */
 
 import { setProjectSchemasForMonaco } from "../services/monaco-lazy";
@@ -17,7 +19,8 @@ import type {
   StudioPlatform,
 } from "../types";
 import { isString } from "@jxsuite/schema/guards";
-import type { JxDocumentValue, JxMutableNode } from "@jxsuite/schema/types";
+import { parseJxn, serializeJxn } from "@jxsuite/schema/jxn";
+import type { JxDocument, JxDocumentValue, JxMutableNode } from "@jxsuite/schema/types";
 
 export interface StudioFormatHints {
   icon?: string;
@@ -59,6 +62,24 @@ export interface StudioFormat {
   capabilities: Record<string, { identifier: string; timing: string[] }>;
 }
 
+/**
+ * What opening a `.jxn` file is told about its format. It is not in {@link getFormats}, which is
+ * what a project chose and what a picker offers: a new document is still `.json`.
+ */
+const JXN_FORMAT: StudioFormat = {
+  capabilities: {
+    parse: { identifier: "parse", timing: ["compiler", "server"] },
+    serialize: { identifier: "serialize", timing: ["compiler", "server"] },
+  },
+  documentKinds: ["page", "component"],
+  exportTarget: false,
+  extensions: [".jxn"],
+  mediaType: null,
+  name: "jxn",
+  remote: false,
+  studio: { documentMode: { default: "component" } },
+};
+
 let _formats: StudioFormat[] = [];
 let _loaded: Promise<StudioFormat[]> | null = null;
 
@@ -235,6 +256,9 @@ export function getFormats(): StudioFormat[] {
 /** Look up the format claiming a file extension (".md" or "md"), optionally by capability. */
 export function formatByExtension(ext: string, capability?: string): StudioFormat | undefined {
   const norm = ext.startsWith(".") ? ext.toLowerCase() : `.${ext.toLowerCase()}`;
+  if (norm === ".jxn") {
+    return JXN_FORMAT;
+  }
   return _formats.find(
     (f) => f.extensions.includes(norm) && (!capability || f.capabilities[capability]),
   );
@@ -245,7 +269,7 @@ export function formatByName(name: string | null | undefined): StudioFormat | un
   if (!name) {
     return undefined;
   }
-  return _formats.find((f) => f.name === name);
+  return name === JXN_FORMAT.name ? JXN_FORMAT : _formats.find((f) => f.name === name);
 }
 
 /** Error for opening a non-JSON file when no imported format class claims its extension. */
@@ -330,6 +354,9 @@ export async function formatParse(
   source: string,
   options?: FormatActionOptions,
 ): Promise<JxMutableNode> {
+  if (name === JXN_FORMAT.name) {
+    return parseJxn(source);
+  }
   /* SAFETY: a format class's `parse` capability returns the Jx document it built from the source —
      The contract every format class implements (specs/extensions.md) — and nothing here inspects
      It before `splitFormatDocument` reads its keys. */
@@ -352,6 +379,11 @@ export async function formatSerialize(
   doc: JxMutableNode,
   options?: FormatActionOptions,
 ): Promise<string> {
+  if (name === JXN_FORMAT.name) {
+    // `source` is what keeps the comments: everything that did not change keeps its exact text.
+    // SAFETY: a document in its editing form, and every member of a JxDocument is optional.
+    return serializeJxn(doc as JxDocument, options?.source);
+  }
   /* SAFETY: a format class's `serialize` capability returns the source text it wrote — the contract
      Every format class implements (specs/extensions.md) — so the answer is a string. */
   return (await formatAction({

package/src/grid/redirects-grid.ts

@@ -29,7 +29,7 @@ import { projectState } from "../store";
 import { clearProblems, notify, problemFindings } from "../services/notify";
 import { showPromptDialog } from "../ui/layers";
 import { activateTab, openTab, workspace } from "../workspace/workspace";
-import { PROJECT_CONFIG_PATH, commitProjectConfig } from "../tabs/project-config";
+import { projectConfigPath, commitProjectConfig } from "../tabs/project-config";
 import { pageRoute } from "../panels/tab-strip";
 import { createGridController, getGridController } from "./grid-controller";
 import {
@@ -230,7 +230,7 @@ export function reportRedirectProblems(
       action: "redirects.open",
       detail: problem.detail,
       key: `redirects.${problem.rule}:${problem.source}`,
-      path: PROJECT_CONFIG_PATH,
+      path: projectConfigPath(),
       source: REDIRECTS_PROBLEM_SOURCE,
       tier: "problem",
     });
@@ -263,7 +263,7 @@ export function createRedirectsSource(): GridSource {
   const load = () => rulesFromConfig(currentConfig());
 
   return {
-    backingPaths: () => new Map([[PROJECT_CONFIG_PATH, "*"]]),
+    backingPaths: () => new Map([[projectConfigPath(), "*"]]),
     capabilities: { delete: true, insert: true, remotePaging: false, remoteSort: false },
     columns: () => Promise.resolve(redirectColumns()),
 
@@ -476,7 +476,7 @@ export function stageRedirectImport(
         action: "redirects.import",
         detail: notes.join("\n"),
         key: "redirects.import",
-        path: PROJECT_CONFIG_PATH,
+        path: projectConfigPath(),
         source: REDIRECTS_PROBLEM_SOURCE,
         tier: "problem",
       },

package/src/grid/sources/content-source.ts

@@ -12,22 +12,18 @@
  * Collections type their columns from the content-type schema (plus inferred extras found in the
  * data); the pages grid is fully inference-driven.
  *
- * **A collection listing obeys the draft perspective (site-architecture.md §7.6).**
- * `content/draft-state.ts` owns both the one flag and the one definition of what a draft is, and
- * this source calls it rather than testing `draft === true` itself — which is what makes "including
- * drafts" mean the same thing here as it does on the tab chip. It can, because that module imports
- * nothing but `reactivity`: the richer `content/entry-model.ts` asks THIS file where a collection's
- * entries live, so an edge back to it would be the cycle `import/no-cycle` rejects.
+ * **A collection listing obeys the hold perspective (site-architecture.md §7.6).**
+ * `content/hold-state.ts` owns both the one flag and the reading of a project's rules, and this
+ * source calls it rather than reading fields itself, which is what makes "including held entries"
+ * mean the same thing here as it does on the tab chip. It can, because that module does not import
+ * the richer `content/entry-model.ts`, which asks THIS file where a collection's entries live, so
+ * an edge back to it would be the cycle `import/no-cycle` rejects.
  */
 import { getPlatform } from "../../platform";
 import { projectState } from "../../store";
 import { workspace } from "../../workspace/workspace";
-import {
-  DRAFT_FIELD,
-  applyDraftFilter,
-  hasDraftAxis,
-  includingDrafts,
-} from "../../content/draft-state";
+import { applyHoldFilter, holdSwitch, includingHeld } from "../../content/hold-state";
+import type { HoldBearer } from "../../content/hold-state";
 import { getGridController } from "../grid-controller";
 import { isRecentLocal, markLocalMutation } from "../../files/fs-events";
 import {
@@ -275,39 +271,38 @@ interface EntryFileSourceOptions {
   /** Inferred columns to front-load, in order (e.g. title/description for pages). */
   priorityFields?: string[];
   /**
-   * Whether this listing is subject to the draft perspective (site-architecture.md §7.6) —
-   * collections are, the pages tree is not. A draft is a property of a content ENTRY: a page
-   * carrying `draft: true` would vanish from the only tree that lists it, with no collection schema
-   * to explain why.
+   * The collection's definition, when this listing is subject to the hold perspective
+   * (site-architecture.md §7.6). Collections are and the pages tree is not: `hold` rules are
+   * written on a content type, and a page belongs to none.
    */
-  drafts?: boolean;
+  holdDef?: () => HoldBearer | null | undefined;
 }
 
 /**
- * The live sources that obey the draft perspective.
+ * The live sources that obey the hold perspective.
  *
  * A `WeakSet` of the source objects rather than a list of tab-id prefixes: whether a listing is
- * draft filtered is decided by one `drafts: true` in this file, and re-deriving it from
- * `"grid://collection/"` in {@link reloadDraftAwareGrids} would be a second answer free to drift.
- * Membership is added by the engine off that same option, so the two cannot disagree. Weak, so a
- * closed tab's source is collectable.
+ * filtered is decided by one `holdDef` in this file, and re-deriving it from `"grid://collection/"`
+ * in {@link reloadHoldAwareGrids} would be a second answer free to drift. Membership is added by the
+ * engine off that same option, so the two cannot disagree. Weak, so a closed tab's source is
+ * collectable.
  */
-const draftAwareSources = new WeakSet<GridSource>();
+const holdAwareSources = new WeakSet<GridSource>();
 
 /**
- * Reload every open grid whose rows depend on the draft perspective.
+ * Reload every open grid whose rows depend on the hold perspective.
  *
  * The perspective is a flag, and a grid holds its rows in controller state that was loaded once —
- * so `content.setIncludeDrafts` changing the flag has to say so. `load()` (not `refresh()`) is the
+ * so `content.setIncludeHeld` changing the flag has to say so. `load()` (not `refresh()`) is the
  * right verb: it re-pulls columns and rows and leaves the edit buffer alone, whereas `refresh()`
  * would stop to ask an author with pending edits whether to discard them, which is not a question a
  * change of perspective should provoke.
  */
-export async function reloadDraftAwareGrids(): Promise<void> {
+export async function reloadHoldAwareGrids(): Promise<void> {
   const reloads: Promise<void>[] = [];
   for (const tab of workspace.tabs.values()) {
     const controller = getGridController(tab);
-    if (controller && draftAwareSources.has(controller.source)) {
+    if (controller && holdAwareSources.has(controller.source)) {
       reloads.push(controller.load());
     }
   }
@@ -317,8 +312,8 @@ export async function reloadDraftAwareGrids(): Promise<void> {
 /** Shared engine for frontmatter-file sources (collections, pages). */
 function createEntryFileSource(opts: EntryFileSourceOptions): GridSource {
   const source = buildEntryFileSource(opts);
-  if (opts.drafts) {
-    draftAwareSources.add(source);
+  if (opts.holdDef) {
+    holdAwareSources.add(source);
   }
   return source;
 }
@@ -420,43 +415,26 @@ function buildEntryFileSource(opts: EntryFileSourceOptions): GridSource {
       extraColumns.sort((a, b) => rank(a) - rank(b));
     }
 
-    columnsCache = withDraftColumn([pathColumn, ...schemaColumns, ...extraColumns]);
+    columnsCache = withHoldColumn([pathColumn, ...schemaColumns, ...extraColumns]);
     return columnsCache;
   };
 
-  /** Whether this listing has a draft axis at all — the schema declares one, or an entry claims one. */
-  const draftAxis = (): boolean => {
-    if (!opts.drafts) {
-      return false;
-    }
-    const schema = opts.schema();
-    return (
-      hasDraftAxis(schema) ||
-      [...entries.values()].some((entry) => hasDraftAxis(schema, entry.frontmatter))
-    );
-  };
-
   /**
-   * Put the Draft column immediately after Path, when this collection has a draft axis.
-   *
-   * A MOVE, and deliberately not a synthesis: wherever there is an axis there is already a column.
-   * A schema that declares `draft` gave `columnsFromSchema` one, and an entry that carries the
-   * field without the schema declaring it gave `inferColumnsFromRows` one — the two conditions of
-   * {@link hasDraftAxis} are exactly the two conditions that produce a column. Building a third here
-   * would be an unreachable branch pretending to be a safety net.
+   * Put the hold switch's column immediately after Path, when the collection's rules offer one.
    *
+   * A MOVE, and deliberately not a synthesis: a field the rules name but neither the schema nor any
+   * entry states has no column to move, and inventing one would show a state nobody wrote down.
    * What the move buys is that the one field deciding whether an entry appears in its own list is
    * not sitting out at column nine, where declaration order or first-sight order happened to put
-   * it. A collection whose entries only ever say `draft: false` has NO axis and is left alone: the
-   * column is ordinary data there, and promoting it would invent a workflow the project never
-   * declared.
+   * it.
    */
-  const withDraftColumn = (columns: GridColumn[]): GridColumn[] => {
-    const index = columns.findIndex((column) => column.field === DRAFT_FIELD);
-    if (index < 1 || !draftAxis()) {
+  const withHoldColumn = (columns: GridColumn[]): GridColumn[] => {
+    const field = holdSwitch(opts.holdDef?.())?.field;
+    const index = columns.findIndex((column) => column.field === field);
+    if (index < 1) {
       return columns;
     }
-    const rest = columns.filter((column) => column.field !== DRAFT_FIELD);
+    const rest = columns.filter((column) => column.field !== field);
     return [rest[0]!, columns[index]!, ...rest.slice(1)];
   };
 
@@ -661,15 +639,13 @@ function buildEntryFileSource(opts: EntryFileSourceOptions): GridSource {
     async rows(): Promise<GridRowsResult> {
       await load();
       // The perspective is applied to the LISTING, not the load: `entries` keeps every parsed file,
-      // So the Draft column still knows the collection has an axis while its drafts are hidden, and
-      // Turning the perspective back on is a re-list rather than a re-read of the directory.
-      const listed = opts.drafts
-        ? applyDraftFilter(
-            [...entries.entries()],
-            ([, entry]) => entry.frontmatter,
-            includingDrafts(),
-          )
-        : [...entries.entries()];
+      // So turning the perspective back on is a re-list rather than a re-read of the directory.
+      const listed = applyHoldFilter(
+        [...entries.entries()],
+        opts.holdDef?.(),
+        ([, entry]) => entry.frontmatter,
+        includingHeld(),
+      );
       const rows = listed.map(([path, entry]) => rowFor(path, entry));
       return { rows, total: rows.length };
     },
@@ -687,7 +663,7 @@ export function createCollectionSource(typeName: string): GridSource {
   };
 
   return createEntryFileSource({
-    drafts: true,
+    holdDef: () => collectionInfo(typeName)?.def,
     id: makeGridTabId({ kind: "collection", name: typeName }),
     insertFormatName: (path) => {
       const info = requireInfo();

package/src/locale/element-names.ts

@@ -0,0 +1,131 @@
+/**
+ * What Studio calls an HTML element, in the reader's language: "Heading 1" for `h1`, "Bulleted
+ * list" for `ul`, and the names of the Insert palette's categories (§5.3).
+ *
+ * **No web-platform database carries these names.** `@webref/elements` lists each element's tag and
+ * interface and nothing a person reads, and MDN's translated pages are prose, not data. So the
+ * names are Studio's own, kept as one catalog per language under `data/locales/<language>/`.
+ * English (`data/locales/en/elements.json`) is the source: it names every tag the palette offers,
+ * which `tests/locale-element-names.test.ts` holds it to, and a translation is a copy of that file
+ * with its values translated and its keys left alone, registered in {@link CATALOGS}.
+ *
+ * **The language is the reader's, and Studio has no setting for it yet.** {@link studioLocale}
+ * takes the first of the browser's preferred languages that has a catalog, by exact tag and then by
+ * base language (`fr-CA` reads `fr`), and falls back to English. A name the chosen catalog lacks
+ * falls back to the English one, and a tag no catalog knows is shown as itself, so a translation
+ * can land incomplete and an element a future `@webref` release adds is never nameless.
+ *
+ * Three surfaces read this module, so they cannot disagree about a name: the Insert palette's
+ * cards, the slash menu, and the block action bar's convert menu.
+ *
+ * @docs studio/design/elements
+ */
+
+import en from "../../data/locales/en/elements.json";
+
+/** One element's entry: the name a card shows, and the line that says what it is for. */
+export interface ElementEntry {
+  name: string;
+  description: string;
+}
+
+/** One language's catalog: category names by key, and element entries by tag. */
+export interface ElementCatalog {
+  categories: Readonly<Record<string, string>>;
+  elements: Readonly<Record<string, ElementEntry>>;
+}
+
+/** The language every lookup falls back to, and the catalog that is complete by contract. */
+export const SOURCE_LOCALE = "en";
+
+/** The source catalog, read through the open shape every other catalog has. */
+const SOURCE: ElementCatalog = en;
+
+/**
+ * Every catalog Studio ships, keyed by BCP 47 language tag. Adding a language is a new
+ * `data/locales/<tag>/elements.json` and one entry here.
+ */
+const CATALOGS = new Map([[SOURCE_LOCALE, SOURCE]]);
+
+/**
+ * The best catalog for a list of preferred languages, most preferred first.
+ *
+ * Each preference is tried whole and then by its base language before the next one is, because a
+ * reader who asked for Canadian French first wants French before their second choice. The match is
+ * case-insensitive, as BCP 47 tags are.
+ *
+ * @param {readonly string[]} preferred - Language tags, most preferred first
+ * @param {readonly string[]} available - The tags a catalog exists for
+ * @returns {string} One of `available`, or {@link SOURCE_LOCALE}
+ */
+export function resolveLocale(
+  preferred: readonly string[],
+  available: readonly string[] = [...CATALOGS.keys()],
+): string {
+  const byLower = new Map(available.map((tag) => [tag.toLowerCase(), tag]));
+  for (const tag of preferred) {
+    const lower = tag.toLowerCase();
+    const match = byLower.get(lower) ?? byLower.get(lower.split("-")[0] ?? "");
+    if (match) {
+      return match;
+    }
+  }
+  return SOURCE_LOCALE;
+}
+
+/**
+ * The browser's preferred languages, or none where there is no `navigator` to ask. Anything that is
+ * not a non-empty string is dropped: an embedder or a privacy setting can blank the answer, and a
+ * reader with no stated language gets English rather than an exception.
+ */
+function preferredLanguages(): readonly string[] {
+  if (typeof navigator === "undefined") {
+    return [];
+  }
+  /* SAFETY: the DOM typings promise both members, but a navigator outside a browser window (Bun's
+     own, a worker's in some engines) lacks `languages`, so each is read as possibly absent and
+     checked before use. */
+  const { language, languages } = navigator as Partial<Pick<Navigator, "language" | "languages">>;
+  const listed: readonly unknown[] = languages && languages.length > 0 ? languages : [language];
+  return listed.filter((tag): tag is string => typeof tag === "string" && tag !== "");
+}
+
+/** The language Studio names elements in for this reader. */
+export function studioLocale(): string {
+  return resolveLocale(preferredLanguages());
+}
+
+/** The catalog for `locale`, or the source catalog when there is none. */
+function catalog(locale: string): ElementCatalog {
+  return CATALOGS.get(locale) ?? SOURCE;
+}
+
+/**
+ * The name of the element `tag`: the catalog's, else the English one, else the tag itself.
+ *
+ * @param {string} tag
+ * @param {string} [locale]
+ */
+export function elementName(tag: string, locale: string = studioLocale()): string {
+  return catalog(locale).elements[tag]?.name ?? SOURCE.elements[tag]?.name ?? tag;
+}
+
+/**
+ * What the element `tag` is for, in one line, or `""` when no catalog says.
+ *
+ * @param {string} tag
+ * @param {string} [locale]
+ */
+export function elementDescription(tag: string, locale: string = studioLocale()): string {
+  return catalog(locale).elements[tag]?.description ?? SOURCE.elements[tag]?.description ?? "";
+}
+
+/**
+ * The name of the palette category `key` (§5.3), else the English one, else the key.
+ *
+ * @param {string} key
+ * @param {string} [locale]
+ */
+export function categoryName(key: string, locale: string = studioLocale()): string {
+  return catalog(locale).categories[key] ?? SOURCE.categories[key] ?? key;
+}

package/src/panels/block-action-bar.ts

@@ -1193,11 +1193,10 @@ function openMergeTagMenu(anchor: HTMLElement): void {
   // No live `$map` in edit mode — the perimeter renders one glyph template — so fields resolve
   // Parent-side from schema, keyed off the selected element's doc path (which carries a `map` segment).
   const selPath = getEditSnapshot().snapshot?.path ?? primarySelection(tab?.session.selection);
-  const arrayNode = tab && selPath ? findEnclosingRepeater(tab.doc.document, selPath) : null;
-  if (arrayNode && tab) {
+  if (tab && selPath && findEnclosingRepeater(tab.doc.document, selPath)) {
     const tokens = resolveRepeaterItemFields(
-      arrayNode,
-      tab.doc.document.state,
+      tab.doc.document,
+      selPath,
       projectState?.projectConfig,
     );
     tags.push(...buildRepeaterTagsFromFields(tokens));

package/src/panels/dnd.ts

@@ -41,6 +41,7 @@ import type { JxMutableNode } from "@jxsuite/schema/types";
 import type { ComponentEntry } from "../files/components.js";
 import type { ElementDragPayload } from "@atlaskit/pragmatic-drag-and-drop/element/adapter";
 import type { DropTargetRecord } from "@atlaskit/pragmatic-drag-and-drop/types";
+import { elementName } from "../locale/element-names";
 
 interface DragCanDragArgs {
   element: HTMLElement;
@@ -314,7 +315,8 @@ export function registerElementsDnD() {
       const preview = row.querySelector(".element-card-preview");
       if (preview && !preview.firstChild) {
         const el = document.createElement(unsafeTags.has(tag) ? "span" : tag);
-        el.textContent = tag;
+        // The specimen reads the card's own name, so a heading previews as "Heading 1", not "h1".
+        el.textContent = elementName(tag);
         preview.append(el);
       }
       const def = defaultDef(tag);