@jxsuite/studio 10.5.0 → 10.6.0

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/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);

package/src/panels/elements-panel.ts

@@ -1,6 +1,9 @@
 /// <reference lib="dom" />
 /**
- * Elements panel — the Insert palette: the blocks and components a page is built out of.
+ * Elements panel — the Insert palette: the blocks and components a page is built out of, on two
+ * tabs, Elements and Components (§5.3). Each element card is named in the reader's language
+ * (`locale/element-names.ts`), with its tag beside the name, and the categories lead with what a
+ * first page is made of: text, lists, media and layout before forms, tables and inline formatting.
  *
  * **The body is a Jx document** (`surfaces/panel-elements.json`, mounted by
  * `surfaces/panel-elements.ts`), so `render` draws nothing and `afterRender` mounts. What stays
@@ -30,6 +33,7 @@ import { mountElementsSurface } from "../surfaces/panel-elements";
 import { mutateInsertNode, transactDoc } from "../tabs/transact";
 import { primarySelection } from "../tabs/selection";
 import { registerPanel } from "./panel-registry";
+import { categoryName, elementDescription, elementName } from "../locale/element-names";
 import { activeTab } from "../workspace/workspace";
 import { view } from "../view";
 
@@ -38,8 +42,10 @@ import type {
   ComponentCardView,
   ElementCategoryView,
   ElementsActions,
+  ElementsEmptyState,
   ElementsSurfaceHandle,
   ElementsValues,
+  InsertTab,
 } from "../surfaces/panel-elements";
 import type { JxElement, JxMutableNode } from "@jxsuite/schema/types";
 import type { NavigatorPanelContext, NavigatorPanelDeps, PanelBody } from "./panel-registry";
@@ -49,8 +55,13 @@ interface ElementsWebdata {
   elements?: Record<string, { tag: string }[]>;
 }
 
-/** The Components section's name — its accordion label AND its key in `view.elementsCollapsed`. */
-const COMPONENTS = "Components";
+/**
+ * The categories that start closed: inline formatting and the advanced remainder (§5.3). Both are
+ * long, and neither is where somebody building their first page looks, so a newcomer sees the
+ * everyday blocks first and opens these when they want them. A filter opens them too, unless the
+ * reader has closed one by hand.
+ */
+const CLOSED_AT_FIRST: ReadonlySet<string> = new Set(["inline", "advanced"]);
 
 /**
  * What the palette is built from, held at module scope rather than closed over at mount.
@@ -76,18 +87,37 @@ function needle(): string {
   return view.elementsFilter.toLowerCase();
 }
 
-/** The categories that still have something in them, with the filter applied. */
+/** Whether a section is drawn open: the reader's own choice, else its default. */
+function sectionOpen(key: string, filter: string): boolean {
+  return view.elementsOpen.get(key) ?? (filter !== "" || !CLOSED_AT_FIRST.has(key));
+}
+
+/**
+ * The categories that still have something in them, with the filter applied, in the order
+ * `webdata.elements` declares them (§5.3). A card matches on its name in the reader's language or
+ * on its tag, so "image" and "img" both find the same card.
+ */
 function categoryViews(webdata: ElementsWebdata, filter: string): ElementCategoryView[] {
   const sections: ElementCategoryView[] = [];
-  for (const [name, elements] of Object.entries(webdata.elements ?? {})) {
-    const matched = filter ? elements.filter((entry) => entry.tag.includes(filter)) : elements;
+  for (const [key, elements] of Object.entries(webdata.elements ?? {})) {
+    const cards = elements.map(({ tag }) => ({
+      description: elementDescription(tag),
+      name: elementName(tag),
+      tag,
+    }));
+    const matched = filter
+      ? cards.filter(
+          (card) => card.tag.includes(filter) || card.name.toLowerCase().includes(filter),
+        )
+      : cards;
     if (matched.length === 0) {
       continue;
     }
     sections.push({
-      elements: matched.map(({ tag }) => ({ tag })),
-      name,
-      open: !view.elementsCollapsed.has(name),
+      elements: matched,
+      key,
+      name: categoryName(key),
+      open: sectionOpen(key, filter),
     });
   }
   return sections;
@@ -145,23 +175,51 @@ function componentViews(filter: string): ComponentCardView[] {
     }));
 }
 
+/** Which body a tab shows: its cards, or why it has none. */
+function emptyState(count: number, filter: string): ElementsEmptyState {
+  if (count > 0) {
+    return "none";
+  }
+  return filter ? "filtered" : "empty";
+}
+
+/** The other tab, which a filtered-out tab offers to switch to. */
+function otherTab(tab: InsertTab): InsertTab {
+  return tab === "elements" ? "components" : "elements";
+}
+
+/** "Show 1 matching component", "Show 3 matching elements": the other tab's offer. */
+function otherMatchesLabel(tab: InsertTab, count: number): string {
+  const noun = tab === "elements" ? "element" : "component";
+  return `Show ${count} matching ${noun}${count === 1 ? "" : "s"}`;
+}
+
 /** Everything the document draws, as one value. */
 function panelValues(source: NavigatorPanelDeps): ElementsValues {
   const filter = needle();
+  const tab = view.insertTab;
   /* SAFETY: `webdata` is wired in studio.ts from the bundled data/webdata.json, whose `elements`
-     maps each category name to an array of `{ tag }` entries. */
+     maps each category key to an array of `{ tag }` entries. */
   const categories = categoryViews(source.webdata as ElementsWebdata, filter);
   const components = componentViews(filter);
-  const bare = categories.length === 0 && components.length === 0;
+  const elementCount = categories.reduce((sum, section) => sum + section.elements.length, 0);
+  const counts: Record<InsertTab, number> = {
+    components: components.length,
+    elements: elementCount,
+  };
+  const other = otherTab(tab);
+  const showOffer = filter !== "" && counts[tab] === 0 && counts[other] > 0;
   return {
     categories,
     components,
-    componentsOpen: !view.elementsCollapsed.has(COMPONENTS),
-    emptyState: bare ? (filter ? "filtered" : "empty") : "none",
+    componentsEmpty: emptyState(components.length, filter),
+    elementsEmpty: emptyState(elementCount, filter),
     /* The reader's own text, not `filter`: the field is bound to this, and a scope holding the
        lower-cased form would rewrite what was typed on every keystroke. */
     filter: view.elementsFilter,
-    hasComponents: components.length > 0,
+    filterLabel: tab === "elements" ? "Filter elements" : "Filter components",
+    otherMatches: showOffer ? otherMatchesLabel(other, counts[other]) : "",
+    tab,
   };
 }
 
@@ -207,6 +265,17 @@ function refresh(): void {
 
 /** What the document's controls do. Every one of them is a decision this module owns. */
 const ACTIONS: ElementsActions = {
+  /* The strip announces any value its tabs carry; only the two this panel draws are taken. */
+  selectTab: (tab) => {
+    if (tab === "elements" || tab === "components") {
+      view.insertTab = tab;
+      refresh();
+    }
+  },
+  showOtherTab: () => {
+    view.insertTab = otherTab(view.insertTab);
+    refresh();
+  },
   clearFilter: () => {
     view.elementsFilter = "";
     refresh();
@@ -223,31 +292,20 @@ const ACTIONS: ElementsActions = {
       insertAtSelection(panelDeps.defaultDef(tag) as JxMutableNode);
     }
   },
-  setComponentsOpen: (open) => {
-    setCollapsed(COMPONENTS, !open);
-    refresh();
-  },
   /* The echo: what the field now holds goes into the state the palette is filtered by, before
      anything is decided about it. */
   setFilter: (value) => {
     view.elementsFilter = value;
     refresh();
   },
-  setSectionOpen: (name, open) => {
-    setCollapsed(name, !open);
+  /* Remembered across repaints and panel switches, and from then on it outranks the section's
+     default, the filter's included. */
+  setSectionOpen: (key, open) => {
+    view.elementsOpen.set(key, open);
     refresh();
   },
 };
 
-/** Remember a section's disclosure across repaints and across panel switches. */
-function setCollapsed(name: string, collapsed: boolean): void {
-  if (collapsed) {
-    view.elementsCollapsed.add(name);
-  } else {
-    view.elementsCollapsed.delete(name);
-  }
-}
-
 /**
  * Draw the panel body — mounting the document the first time, updating it every time after.
  *
@@ -277,13 +335,13 @@ export function mountElementsPanel(ctx: NavigatorPanelContext, host: HTMLElement
 }
 
 /**
- * Contribute the Insert panel — **off the rail** (`rail: false`).
+ * Contribute the Insert panel — the first button of the rail's DOCUMENT group (§5.1).
  *
- * §5.1 keeps Insert off the Navigator rail because it is not a view of anything: it is an insert
- * palette, and a palette belongs at the caret (slash menu), on the canvas (`+`) and behind ⌘⇧A, all
- * of which are the Insert command family. The record survives so the surface stays reachable —
- * `view.setActivity {tab:"insert"}`, the palette, and the screenshot pipeline all still address it
- * — and giving up its rail slot is what keeps the DOCUMENT group at four.
+ * It is the place an author picks an element or component from and drags it onto the canvas, so it
+ * stays on screen while they work: a card is a choice to look at, compare and drag, and a palette
+ * that has to be summoned by name before it can be seen is one only a reader of the command list
+ * finds. The slash menu and the canvas `+` stay the inserts at the caret; this is the one an author
+ * browses.
  *
  * `level: "document"`, per §13.2's own worked example: it READS the project's component registry
  * and WRITES the document tree.
@@ -295,7 +353,6 @@ export function registerInsertPanel(): void {
     level: "document",
     dock: "navigator",
     icon: "grid-four",
-    rail: false,
     // The body is a document, so lit draws nothing and the mount happens against the painted DOM.
     // `afterRender` runs on every repaint; {@link mountElementsPanel} is idempotent.
     render: (): PanelBody => nothing,

package/src/panels/imports-panel.ts

@@ -50,6 +50,7 @@ import type {
 } from "../surfaces/panel-imports";
 import type { JxMutableNode } from "@jxsuite/schema/types";
 import type { SurfaceOption } from "../ui/surface";
+import { isProjectConfigPath } from "@jxsuite/schema/project-file";
 
 /** What the panel is drawn against. `left-panel.ts`'s context, reduced to what this reads. */
 export interface ImportsContext {
@@ -204,7 +205,7 @@ function documentView(ctx: ImportsContext): ImportsView {
 
 /** What the panel shows right now. `project.json` is the one document with the other mood. */
 function view(ctx: ImportsContext): ImportsView {
-  return ctx.documentPath?.endsWith("project.json") ? siteView() : documentView(ctx);
+  return isProjectConfigPath(ctx.documentPath) ? siteView() : documentView(ctx);
 }
 
 /** Push the current projection into the standing surface, in this turn. */
@@ -295,7 +296,7 @@ async function onToggleComponent(id: string, checked: boolean): Promise<void> {
   if (!ctx || !comp) {
     return;
   }
-  if (ctx.documentPath?.endsWith("project.json")) {
+  if (isProjectConfigPath(ctx.documentPath)) {
     const before = siteElements();
     const updated = checked
       ? enableElement(before, comp, null)

package/src/panels/navigator-panels.ts

@@ -8,9 +8,9 @@
  * the second definition site the registry exists to prevent.
  *
  * **Registration order is rail order** within a level group: PROJECT (Site, then Files with the
- * developer panels on) above the divider, DOCUMENT (Outline · Data, then Packages with the
- * developer panels on) below it (§5.1). Search, Languages and Insert are registered rail-less:
- * reachable by `view.setActivity` and the palette, with no button.
+ * developer panels on) above the divider, DOCUMENT (Insert · Outline · Data, then Packages with the
+ * developer panels on) below it (§5.1). Search and Languages are registered rail-less: reachable by
+ * `view.setActivity` and the palette, with no button.
  *
  * **Every rail button opens the Navigator.** Problems used to hold the fourth PROJECT slot while
  * its body was drawn in the Bottom dock, and paying for that took a per-dock branch in three
@@ -84,13 +84,13 @@ export function registerNavigatorPanels(): void {
   registerI18nPanel();
 
   // ── DOCUMENT group ──────────────────────────────────────────────────────────
+  /* Insert leads the group: it is where a page's elements and components are picked from and
+     dragged onto the canvas, the verb a Design session is mostly made of (§5.1, §5.3). */
+  registerInsertPanel();
   registerLayersPanel();
   registerDataPanel();
   registerPackagesPanel();
 
-  // ── Off-rail: reachable by command and palette, no rail button ──────────────
-  registerInsertPanel();
-
   // ── The Bottom dock's tabs (§16.3): Problems · Logic · Activity ──────────────
   // Composed here, in the one place panel records are gathered, so the shell has ONE composition
   // Site rather than one per dock. Importing the module is also what attaches the dock to the
@@ -122,10 +122,10 @@ export function navigatorPanelSet(): readonly PanelRecord[] {
  * The roster `panel.focus.*` is generated from: rail order first, then the rail-less Navigator
  * panels.
  *
- * Not `railPanelSet()`: Insert and Languages have no rail button and no chord, and they still need
- * a `Show …` command and a palette row, which is the whole point of `rail: false` (a surface
- * reachable by name, not by number). State used to be the third of them and is gone: its editor is
- * the Data panel's now, so there is no second record to roster.
+ * Not `railPanelSet()`: Languages has no rail button and no chord, and it still needs a `Show …`
+ * command and a palette row, which is the whole point of `rail: false` (a surface reachable by
+ * name, not by number). State and Insert were rail-less beside it once: State's editor is the Data
+ * panel's now, and Insert is back on the rail (§5.1).
  *
  * The Bottom dock's three tabs are deliberately absent — Problems as of this change, and Logic and
  * Activity all along. Each is `rail: false` AND hosted there, so each is addressed by

package/src/panels/panel-registry.ts

@@ -153,9 +153,9 @@ export interface PanelRecord {
    *
    * Not a hiding mechanism — a rail-less panel is still reachable by `view.setActivity`, by the
    * palette and by another surface linking to it. It is how a record survives the interval between
-   * losing its rail slot and gaining its real home (Insert, reachable from the canvas and palette;
-   * State, folded into Data — §5.1). Declaring it `false` also removes the panel's `rail/<level>`
-   * placement, which is what keeps the rail inside its four-per-group budget.
+   * losing its rail slot and gaining its real home (State, folded into Data — §5.1). Declaring it
+   * `false` also removes the panel's `rail/<level>` placement, which is what keeps the rail inside
+   * its four-per-group budget.
    *
    * `"developer"` is a rail button only while **Show developer panels** is on (§5.1,
    * `settings/developer-panels.ts`): Files and Packages, which a site author does not need on the

package/src/panels/site-panel.ts

@@ -71,6 +71,7 @@ import type {
   SiteSectionState,
 } from "../surfaces/site-panel";
 import type { SiteComponentRow, SiteMediaRow, SitePageFact } from "./site-model";
+import { isProjectConfigPath } from "@jxsuite/schema/project-file";
 
 // ─── The project index ───────────────────────────────────────────────────────
 
@@ -213,7 +214,7 @@ export function mayDefineComponent(path: string): boolean {
   }
   return (
     path.endsWith(".json") &&
-    path !== "project.json" &&
+    !isProjectConfigPath(path) &&
     !NON_COMPONENT_DIRS.some((dir) => path.startsWith(dir))
   );
 }

package/src/panels/style-panel.ts

@@ -54,6 +54,7 @@ import {
   isNumber,
   isString,
 } from "@jxsuite/schema/guards";
+import { PROJECT_FILE_NAME } from "@jxsuite/schema/project-file";
 import { effect, effectScope, reactive } from "../reactivity";
 import {
   cancelStyleDebounce,
@@ -374,7 +375,7 @@ function stylebookTagOf(selector: string | null): string | null {
  * elements of its own for "in this document" to be about.
  */
 function isProjectStylesheet(path: string): boolean {
-  return /(?:^|\/)project\.json$/.test(path);
+  return path.split("/").pop() === PROJECT_FILE_NAME;
 }
 
 /**

package/src/panels/styles-panel.ts

@@ -34,7 +34,7 @@ import { effect, effectScope } from "../reactivity";
 import { projectState } from "../store";
 import { setDockCollapsed, shell } from "../shell";
 import { workspace } from "../workspace/workspace";
-import { PROJECT_CONFIG_PATH } from "../tabs/tab";
+import { projectConfigPath } from "../tabs/tab";
 import { componentRegistry } from "../files/components";
 import { runActiveReported } from "../commands/run-reported";
 import { showSettingsDocument } from "../settings/settings-document";
@@ -88,7 +88,7 @@ export interface StylesPanelInput {
  * opened with.
  */
 export function stylesConfig(): StylesPanelInput["config"] {
-  const tab = workspace.tabs.get(PROJECT_CONFIG_PATH);
+  const tab = workspace.tabs.get(projectConfigPath());
   return (tab ? tab.doc.document : projectState?.projectConfig) ?? null;
 }
 

package/src/platforms/cloud.ts

@@ -20,6 +20,7 @@ import type { WsCollabConnection } from "@jxsuite/collab/client";
 import { isBoolean, isJsonObject, isNonNullObject, isString } from "@jxsuite/schema/guards";
 import type { JsonObject, JsonValue, JxMutableNode, ProjectConfig } from "@jxsuite/schema/types";
 import { componentMetaFrom } from "@jxsuite/schema/component-meta";
+import { isJxnPath, isNativeDocumentPath, parseJxn } from "@jxsuite/schema/jxn";
 import { streamImport } from "../services/import-client";
 import type {
   AccountEntry,
@@ -1403,7 +1404,7 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
             if (!SKIP.has(entry.name) && !entry.name.startsWith(".")) {
               dirs.push(entry.path);
             }
-          } else if (entry.name.endsWith(".json") && jsonPaths.length < MAX_FILES) {
+          } else if (isNativeDocumentPath(entry.name) && jsonPaths.length < MAX_FILES) {
             jsonPaths.push(entry.path);
           }
         }
@@ -1414,7 +1415,9 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
       const metas = await Promise.all(
         jsonPaths.map(async (path) => {
           try {
-            return componentMetaFrom(parseJson(await platform.readFile(path)), path);
+            const text = await platform.readFile(path);
+            const document = isJxnPath(path) ? parseJxn(text) : parseJson(text);
+            return componentMetaFrom(isJsonObject(document) ? document : null, path);
           } catch {
             return null; // Not JSON, not readable, or not a component — all the same answer here.
           }

package/src/services/ai-command-tools.ts

@@ -84,6 +84,7 @@ import type { CommandContext } from "../commands/context";
 import type { AiToolReport, AnyCommand, CommandRegistry } from "../commands/registry";
 import type { Tab } from "../tabs/tab";
 import { runAsActor } from "../tabs/transact";
+import { projectConfigPath } from "../tabs/tab";
 
 /**
  * The record a selection-level projection composes through.
@@ -328,7 +329,7 @@ function defaultPaths(command: AnyCommand, tab: Tab | null): string[] {
     return [tab?.documentPath ?? "(untitled)"];
   }
   if (command.undo === "project") {
-    return ["project.json"];
+    return [projectConfigPath()];
   }
   return ["(unknown file)"];
 }

package/src/services/ai-project-tools.ts

@@ -17,6 +17,7 @@
 import { JX_TOOL_FACTS } from "@jxsuite/ai/jx-tools";
 import { createToolDefinition } from "@jxsuite/ai/tools";
 import { isJsonObject, isNumber } from "@jxsuite/schema/guards";
+import { classifyJxn, isJxnPath, isNativeDocumentPath, parseJxn } from "@jxsuite/schema/jxn";
 import type { CreateProjectDestination, StudioPlatform } from "../types";
 import type { ToolRegistry } from "@jxsuite/ai/tools";
 import type { JsonValue, JxMutableNode, ProjectConfig } from "@jxsuite/schema/types";
@@ -30,6 +31,7 @@ import { validateDoc, validateProjectConfig } from "./jx-validate";
 import { flagHardcodedTokens, formatTokenHints } from "./token-lint";
 import type { CandidateDocument, RenderProbe } from "./ai-write-report";
 import { invalidPathResult, normalizeRelPath } from "./project-path";
+import { isProjectConfigPath } from "@jxsuite/schema/project-file";
 
 /** Directories the file tools never descend into or report. */
 const EXCLUDED_DIRS = new Set(["node_modules", "dist", ".git", ".jx-cache"]);
@@ -49,7 +51,7 @@ const NOT_UNDOABLE = "(saved to disk; not undoable with Cmd+Z)";
  * {@link looksLikeJxDoc} sniff.
  */
 function isJxDocPath(path: string): boolean {
-  return /^(pages|layouts|components|elements)\//.test(path) && path.endsWith(".json");
+  return /^(pages|layouts|components|elements)\//.test(path) && isNativeDocumentPath(path);
 }
 
 /** Structural sniff for Jx-document-shaped JSON values. */
@@ -299,8 +301,19 @@ export function registerProjectTools(
 
         // Pre-validate Jx documents — disk writes have no undo to lean on.
         let parsed: JsonValue | undefined;
-        const isJson = relPath.endsWith(".json") && relPath !== "project.json";
-        if (isJson) {
+        const isJxn = isJxnPath(relPath) && classifyJxn(content) !== "project";
+        const isJson = relPath.endsWith(".json") && !isProjectConfigPath(relPath);
+        if (isJxn) {
+          try {
+            const document = parseJxn(content);
+            parsed = isJsonObject(document) ? document : null;
+          } catch (error) {
+            return {
+              success: false,
+              error: `Content is not valid Jx Notation: ${error instanceof Error ? error.message : String(error)}`,
+            };
+          }
+        } else if (isJson) {
           try {
             // SAFETY: `JSON.parse` without a reviver yields nothing but JSON values.
             parsed = JSON.parse(content) as JsonValue;
@@ -312,7 +325,7 @@ export function registerProjectTools(
           }
         }
         let tokenHints = "";
-        // The parse above sets `parsed` exactly when `isJson` holds: it never yields `undefined`.
+        // The parse above sets `parsed` exactly when one of those holds: it never yields `undefined`.
         if (parsed !== undefined && (isJxDocPath(relPath) || looksLikeJxDoc(parsed))) {
           const errors = await validate(parsed);
           if (errors.length > 0) {
@@ -345,7 +358,7 @@ export function registerProjectTools(
         /* Parsed as `unknown` because that is what it is until the schema says otherwise — this is
            model-authored text, and the gate below is the whole reason we do not trust its shape. */
         let projectConfig: ProjectConfig | undefined;
-        if (relPath === "project.json") {
+        if (isProjectConfigPath(relPath)) {
           let parsedConfig: JsonValue;
           try {
             // SAFETY: `JSON.parse` without a reviver yields nothing but JSON values.