@jxsuite/studio 6.1.0 → 6.1.2

package/src/files/files.ts

@@ -59,6 +59,7 @@ import {
   dropTargetForElements,
   monitorForElements,
 } from "@atlaskit/pragmatic-drag-and-drop/element/adapter";
+import type { ElementDragPayload } from "@atlaskit/pragmatic-drag-and-drop/element/adapter";
 import { combine } from "@atlaskit/pragmatic-drag-and-drop/combine";
 import {
   PRIMARY_PANE,
@@ -99,9 +100,12 @@ import { restoreSession } from "../workspace/session";
 import { cleanupGitPanel } from "../panels/git-panel";
 import { addRecentProject, trackRecentFile } from "../recent-projects";
 import { listWindow, revealListRow, watchListWindow } from "../ui/virtual-window";
-import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { JsonObject, JxMutableNode } from "@jxsuite/schema/types";
+import { isFunction, isString } from "@jxsuite/schema/guards";
+import type { CommandArgValues } from "../commands/command-args";
+import type { FormatFrontmatter } from "../format/format-host";
 import type { ResolvedI18n } from "@jxsuite/schema/locale";
-import type { ChoiceOption } from "../ui/layers";
+import type { ChoiceOption, PromptDialogOptions } from "../ui/layers";
 import { emptyFilesPanelValues, mountFilesPanelSurface } from "../surfaces/files-panel";
 import { openMenu } from "../surfaces/menu";
 import type {
@@ -136,6 +140,42 @@ export async function loadDirectory(dirPath: string) {
   }
 }
 
+/** The project directories the Library scans and the tree opens expanded, when present. */
+const CONVENTIONAL_DIRS = new Set([
+  "pages",
+  "layouts",
+  "components",
+  "content",
+  "data",
+  "public",
+  "styles",
+]);
+
+/**
+ * Load the project root, expand and load each conventional directory it holds, and record them as
+ * `projectDirs` — the list the Library scans.
+ *
+ * One function because there are four doors into a project (the folder picker, a recent project,
+ * the `?project=` boot and the root probe a fresh window runs), and each used to carry its own copy
+ * of this walk. Two of the copies expanded the directories without recording them, so on desktop
+ * the file tree was full and the Library said the project had no files.
+ */
+export async function loadProjectDirectories(): Promise<void> {
+  if (!projectState) {
+    return;
+  }
+  await loadDirectory(".");
+  const found: string[] = [];
+  for (const entry of projectState.dirs.get(".") ?? []) {
+    if (entry.type === "directory" && CONVENTIONAL_DIRS.has(entry.name)) {
+      found.push(entry.name);
+      projectState.expanded.add(entry.path || entry.name);
+      await loadDirectory(entry.path || entry.name);
+    }
+  }
+  projectState.projectDirs = found;
+}
+
 /**
  * Whether the tree currently draws the files `.gitignore` masks.
  *
@@ -196,7 +236,7 @@ export async function loadProject() {
         await loadFormats();
         refreshExtensionUi(platform);
       }
-      await loadDirectory(".");
+      await loadProjectDirectories();
       await loadComponentRegistry();
       await openLastSessionOrHome();
       void maybePromptJxsuiteUpdate(meta.root);
@@ -268,30 +308,9 @@ export async function openProject({
       await loadFormats();
       refreshExtensionUi(platform);
     }
-    await loadDirectory(".");
+    await loadProjectDirectories();
     await loadComponentRegistry();
 
-    // Auto-expand key directories and populate projectDirs for Browse view
-    const conventionalDirs = new Set([
-      "pages",
-      "layouts",
-      "components",
-      "content",
-      "data",
-      "public",
-      "styles",
-    ]);
-    const entries = requireProjectState().dirs.get(".") || [];
-    const foundDirs = [];
-    for (const e of entries) {
-      if (e.type === "directory" && conventionalDirs.has(e.name)) {
-        foundDirs.push(e.name);
-        requireProjectState().expanded.add(e.path || e.name);
-        await loadDirectory(e.path || e.name);
-      }
-    }
-    requireProjectState().projectDirs = foundDirs;
-
     // Source control, the stylebook selection and the settings tab describe the project being
     // Left behind. The poll timer goes with them; the panel re-arms it on its next render.
     cleanupGitPanel();
@@ -460,35 +479,6 @@ function fileIconName(name: string, type: string, expanded: boolean): string {
   }
 }
 
-/**
- * The Navigator no longer draws this panel with lit.
- *
- * The record below returns `nothing` and mounts `surfaces/files-panel.json` in `afterRender`, so
- * this is a stub: it survives only because `NavigatorPanelDeps` still declares the injection and
- * `studio.ts` still passes it. Both go in the change that deletes this.
- *
- * @deprecated The panel is `surfaces/files-panel.json`; call {@link mountFilesPanel}.
- */
-export function renderFilesTemplate(): typeof nothing {
-  return nothing;
-}
-
-/**
- * Drag-and-drop is registered against the row elements the DOCUMENT creates, as they are created.
- *
- * The pass this replaced ran on a `requestAnimationFrame` after every repaint, found the tree and
- * its rows by class, and re-registered every one of them — which is exactly the acquisition
- * `studio-ui-guidelines.md` §9.4 objects to, and which a WINDOWED list makes wrong rather than
- * merely wasteful: the rows are re-used for different files as the window slides, so a pass that
- * arrives one frame late hands a file's drag source to whichever file is standing in its place.
- * {@link mountFilesPanel} adopts each row through `onNodeCreated` instead.
- *
- * @deprecated Registration is `onNodeCreated`; this exists for the deps entry alone.
- */
-export function registerFileTreeDnD(_ctx: { renderLeftPanel: () => void }): void {
-  // Intentionally nothing: see the note above.
-}
-
 // ─── The row model, and the window onto it ───────────────────────────────────
 
 /**
@@ -1183,10 +1173,9 @@ export function canMoveInto(srcPath: string, targetDir: string): boolean {
 }
 
 /** {@link canMoveInto} for a ROW: only a directory has an inside to move something into. */
-function acceptsDrop(srcPath: unknown, targetPath: string, targetType: string): boolean {
-  return (
-    targetType === "directory" && typeof srcPath === "string" && canMoveInto(srcPath, targetPath)
-  );
+function acceptsDrop(source: ElementDragPayload, targetPath: string, targetType: string): boolean {
+  const srcPath = source.data.path;
+  return targetType === "directory" && isString(srcPath) && canMoveInto(srcPath, targetPath);
 }
 
 /**
@@ -1310,15 +1299,15 @@ function adoptFileRow(element: HTMLElement, path: string, type: string): void {
       },
       element,
       getData({ source }) {
-        return acceptsDrop(source.data.path, path, type)
+        return acceptsDrop(source, path, type)
           ? { targetDir: path, type: "file-tree-target" }
           : { type: "file-tree-refused" };
       },
       onDrag({ source }) {
-        setRowUnderDrag(path, acceptsDrop(source.data.path, path, type));
+        setRowUnderDrag(path, acceptsDrop(source, path, type));
       },
       onDragEnter({ source }) {
-        setRowUnderDrag(path, acceptsDrop(source.data.path, path, type));
+        setRowUnderDrag(path, acceptsDrop(source, path, type));
       },
       onDragLeave() {
         setRowUnderDrag("", false);
@@ -1361,7 +1350,8 @@ function adoptFileTreeElement(element: HTMLElement): void {
      pointer — {@link syncRootDrop} — because the row is what the drop will reach. */
   const rootCleanup = dropTargetForElements({
     canDrop({ source }) {
-      return source.data.type === "file-tree" && canMoveInto(source.data.path as string, ".");
+      const srcPath = source.data.path;
+      return source.data.type === "file-tree" && isString(srcPath) && canMoveInto(srcPath, ".");
     },
     element,
     getData() {
@@ -1393,9 +1383,11 @@ function adoptFileTreeElement(element: HTMLElement): void {
         return;
       }
 
-      const srcPath = source.data.path as string;
-      const targetDirPath = target.data.targetDir as string;
-      if (!canMoveInto(srcPath, targetDirPath)) {
+      // A file-tree row's drag source always carries its string `path`, and an accepting row's
+      // Target its string `targetDir` (see `adoptFileRow`); anything else is not a move.
+      const srcPath = source.data.path;
+      const targetDirPath = target.data.targetDir;
+      if (!isString(srcPath) || !isString(targetDirPath) || !canMoveInto(srcPath, targetDirPath)) {
         return;
       }
       const fileName = srcPath.split("/").pop();
@@ -1520,8 +1512,8 @@ function dismissFileContextMenu(): void {
  * Entry Form" is not offered on it. A command whose required arguments this row cannot answer is
  * skipped — never rendered into a refusal the author cannot act on.
  */
-function fileRowFacts(entry: { path: string; type: string }): Record<string, unknown> {
-  const facts: Record<string, unknown> = {};
+function fileRowFacts(entry: { path: string; type: string }): CommandArgValues {
+  const facts: CommandArgValues = {};
   if (entry.type === "directory") {
     // The collection's own SOURCE ROOT, not any directory beneath it: "Edit Collection in Grid"
     // Opens the whole collection, so offering it on `content/posts/2026` would be a row whose label
@@ -1579,13 +1571,11 @@ function placedFileRows(entry: { path: string; type: string }): MenuRowProjectio
   const facts = fileRowFacts(entry);
   const rows: MenuRowProjection[] = [];
   for (const command of registry.forPlacement("context/file")) {
-    const schema = command.args as
-      | { properties?: Record<string, unknown>; required?: readonly string[] }
-      | undefined;
+    const schema = command.args;
     if (!(schema?.required ?? []).every((key) => key in facts)) {
       continue;
     }
-    const args: Record<string, unknown> = {};
+    const args: CommandArgValues = {};
     for (const key of Object.keys(schema?.properties ?? {})) {
       if (key in facts) {
         args[key] = facts[key];
@@ -1926,27 +1916,28 @@ export async function createFileIn(request: NewFileRequest): Promise<string | nu
   };
 
   let picked = initialPick;
-  const entered = await showPromptDialog(request.title ?? "New File", {
-    ...(rows === null
-      ? {}
-      : {
-          choice: {
-            initial: initialPick,
-            label: "Format",
-            onChange: (next: string) => {
-              picked = next;
-            },
-            options: () => rows,
-          },
-        }),
+  const promptOptions: PromptDialogOptions = {
     confirmLabel: "Create",
     message: dir === "." ? "Creating in the project root." : `Creating in ${dir}/`,
-    ...(request.suggestedName === undefined ? {} : { placeholder: request.suggestedName }),
     // With a picker there is no extension in the field to preserve, so the whole name is the stem.
     select: rows === null ? "stem" : "all",
     validate,
     value: request.suggestedName ?? "untitled.json",
-  });
+  };
+  if (rows !== null) {
+    promptOptions.choice = {
+      initial: initialPick,
+      label: "Format",
+      onChange: (next: string) => {
+        picked = next;
+      },
+      options: () => rows,
+    };
+  }
+  if (request.suggestedName !== undefined) {
+    promptOptions.placeholder = request.suggestedName;
+  }
+  const entered = await showPromptDialog(request.title ?? "New File", promptOptions);
   if (!entered) {
     return null;
   }
@@ -1955,10 +1946,9 @@ export async function createFileIn(request: NewFileRequest): Promise<string | nu
   const path = dir === "." ? fileName : `${dir}/${fileName}`;
   markLocalMutation(path);
   const format = formatForPath(fileName);
-  const suppliedBody =
-    typeof request.content === "function"
-      ? await request.content(extensionOfName(fileName), fileName)
-      : request.content;
+  const suppliedBody = isFunction(request.content)
+    ? await request.content(extensionOfName(fileName), fileName)
+    : request.content;
   /*
    * What a new file starts as, in precedence order.
    *
@@ -2069,13 +2059,16 @@ async function createNewFile(dirPath: string, renderLeftPanel: () => void) {
  */
 async function showRenameFileDialog(currentName: string, path: string): Promise<string | null> {
   const message = await renamePromptMessage(path);
-  return showPromptDialog("Rename", {
+  const promptOptions: PromptDialogOptions = {
     confirmLabel: "Rename",
-    ...(message === undefined ? {} : { message }),
     select: "stem",
     validate: (v) => (v.trim() ? "" : "Enter a file name."),
     value: currentName,
-  });
+  };
+  if (message !== undefined) {
+    promptOptions.message = message;
+  }
+  return showPromptDialog("Rename", promptOptions);
 }
 
 /** Build the status-bar message for a rename, summarising any reference/tag rewrites. */
@@ -2376,8 +2369,8 @@ export async function openFileInTab(path: string, opts: OpenFileOpts = {}) {
     }
 
     await loadFormats();
-    let document: Record<string, unknown>;
-    let frontmatter: Record<string, unknown> | undefined;
+    let document: JxMutableNode | JsonObject;
+    let frontmatter: FormatFrontmatter | undefined;
     // The layout the JSON was written in, so a save reproduces it (`json-layout.ts`, issue 308). A
     // Format-class file has none: its serializer owns its layout.
     let layout: JsonLayout | null = null;
@@ -2522,6 +2515,8 @@ export async function reloadFileInTab(path: string, opts: { onlyIfChanged?: bool
           if (opts.onlyIfChanged && deepEqual(parsed.document, tab.doc.document)) {
             return;
           }
+          /* SAFETY: this tab was opened on this `.json` path as a Jx document, and the file's schema
+             Makes its top-level object a node — the object `parseJsonDocument` states it returns. */
           tab.doc.document = parsed.document as JxMutableNode;
         }
         tab.doc.dirty = false;

package/src/files/media-meta.ts

@@ -23,6 +23,7 @@
  * @docs studio/projects/media
  */
 
+import { isNumber } from "@jxsuite/schema/guards";
 import { getPlatform } from "../platform";
 import { baseName, dirName, normalizeProjectPath } from "./media-paths";
 import { notedListing } from "./asset-versions";
@@ -67,7 +68,7 @@ function metaFrom(path: string, entry: DirEntry | undefined): MediaMeta {
   const name = baseName(path);
   const dims = measured.get(path);
   return {
-    bytes: typeof entry?.size === "number" ? entry.size : null,
+    bytes: isNumber(entry?.size) ? entry.size : null,
     ext: extensionOf(name),
     height: dims?.height ?? null,
     kind: mediaKind({ name }),

package/src/files/media-paths.ts

@@ -66,6 +66,9 @@ export function dirName(path: string): string {
 /** The open project's content sections, or null when no project (or no `content:`) is loaded. */
 function contentSections(): Record<string, ContentSectionEntry> | null {
   const content = projectState?.projectConfig?.content;
+  /* SAFETY: `content` is the parser extension's section, which the schema types leave opaque; its
+     Project fragment schema shapes every entry as a `ContentSectionEntry`, and `contentMountFor`
+     (the only reader) touches nothing but an entry's optional `source` behind `def?.source`. */
   return (content as Record<string, ContentSectionEntry> | undefined) ?? null;
 }
 
@@ -134,5 +137,7 @@ export function previewFileSrc(path: string): string {
   if (space === "repo") {
     return withVersion(`${fileBaseUrl}${encodeProjectPath(normalized)}`, versionOf(normalized));
   }
-  return loopbackAssetSrc(mediaSiteUrl(normalized));
+  /* Encoded per segment for the `src` only. `mediaSiteUrl` is also what an author's document is
+     given, and stays as typed; a `#` or `?` in a filename would cut this URL short. */
+  return loopbackAssetSrc(`/${encodeProjectPath(mediaSiteUrl(normalized).slice(1))}`);
 }

package/src/files/serialize-document.ts

@@ -40,7 +40,7 @@ export async function serializeDocument(tab: Tab): Promise<string> {
   await loadFormats();
   const sourceFormat = formatByName(tab.doc.sourceFormat);
   if (sourceFormat?.capabilities.serialize) {
-    const fm = tab.doc.content?.frontmatter || {};
+    const fm = tab.doc.content.frontmatter;
     const doc = tab.doc.document;
     const fullDoc = { ...fm, ...doc, children: doc.children ?? [] };
     return formatSerialize(sourceFormat.name, fullDoc, { mode: "roundtrip" });
@@ -48,7 +48,7 @@ export async function serializeDocument(tab: Tab): Promise<string> {
   if (tab.doc.mode === "content") {
     const format = defaultContentFormat();
     if (format) {
-      const fm = tab.doc.content?.frontmatter ?? {};
+      const fm = tab.doc.content.frontmatter;
       const hasFrontmatter = Object.keys(fm).length > 0;
       const fullDoc = { ...fm, ...tab.doc.document };
       return formatSerialize(format.name, fullDoc, {

package/src/format/constraints.ts

@@ -84,7 +84,7 @@ export function createNestingValidator(elements?: ElementsHints): NestingValidat
  *
  * Returned as a plain object because it crosses to the canvas frame with the render message.
  */
-export function formatEditableVerdicts(elements?: ElementsHints): Record<string, boolean> {
+export function formatEditableVerdicts(elements?: ElementsHints) {
   const verdicts: Record<string, boolean> = {};
   for (const [tag, rule] of Object.entries(elements?.nesting ?? {})) {
     // "_root" is the document itself, not an element.

package/src/format/convert-file.ts

@@ -29,6 +29,10 @@ import {
 import { convertTargetExtensions, convertTargets } from "./format-choices";
 import { parseJsonDocument, serializeJson } from "@jxsuite/schema/json-layout";
 import type { JsonLayout } from "@jxsuite/schema/json-layout";
+import { isString } from "@jxsuite/schema/guards";
+import type { JsonValue, JxMutableNode } from "@jxsuite/schema/types";
+import type { CommandArgValues } from "../commands/command-args";
+import type { FormatFrontmatter } from "./format-host";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 
 /** What a conversion will do, resolved in full before the reader is asked to confirm it. */
@@ -72,14 +76,17 @@ function withExtension(path: string, ext: string): string {
 async function readDocument(
   path: string,
   source: string,
-): Promise<{ document: Record<string, unknown>; frontmatter: Record<string, unknown> }> {
+): Promise<{ document: JxMutableNode; frontmatter: FormatFrontmatter }> {
   const { formatForPath } = await import("./format-host");
   if (formatForPath(path)) {
     const { parseSourceForPath } = await import("../files/file-ops");
     const parsed = await parseSourceForPath(path, source);
     return { document: parsed.document, frontmatter: parsed.frontmatter };
   }
-  return { document: JSON.parse(source) as Record<string, unknown>, frontmatter: {} };
+  /* SAFETY: a path no format claims is a `.json` document in pages/ or components/ (the only files
+     `convertTargets` offers a conversion for), and that file's schema requires a top-level object;
+     `JSON.parse` without a reviver yields a JSON value, so the object is a Jx document. */
+  return { document: JSON.parse(source) as JxMutableNode, frontmatter: {} };
 }
 
 /**
@@ -94,8 +101,8 @@ async function readDocument(
  */
 async function writeDocument(
   targetExt: string,
-  document: Record<string, unknown>,
-  frontmatter: Record<string, unknown>,
+  document: JxMutableNode,
+  frontmatter: FormatFrontmatter,
 ): Promise<string> {
   const merged = { ...frontmatter, ...document };
   if (targetExt === ".json") {
@@ -194,7 +201,9 @@ export async function buildPlan(
        errors, which is indistinguishable from a valid document. Claiming validity on the strength of
        a schema that was never compiled is the "never render 0" defect one layer down. */
     const { validateDocOrNull } = await import("../services/jx-validate");
-    const errors = await validateDocOrNull(JSON.parse(text));
+    /* SAFETY: `text` is what `serializeJson` just wrote, and `JSON.parse` without a reviver yields
+       a JSON value. */
+    const errors = await validateDocOrNull(JSON.parse(text) as JsonValue);
     if (errors === null) {
       lines.push(
         "The result could not be checked against the document schema — that is not the same as " +
@@ -292,7 +301,9 @@ export async function convertFile(path: string, targetExt?: string): Promise<str
 
   let original: string;
   try {
-    original = (await platform.readFile(path)) ?? "";
+    // The read crosses the PAL's wire, which can answer without a `content` field: read that as empty.
+    const read = await platform.readFile(path);
+    original = isString(read) ? read : "";
   } catch (error) {
     return fail(`Could not read ${path}.`, errorMessage(error));
   }
@@ -373,8 +384,8 @@ async function rebuildTab(from: string, to: string, text: string): Promise<void>
   const { formatForPath } = await import("./format-host");
   renameTab(from, to, to);
   const format = formatForPath(to);
-  let document: Record<string, unknown>;
-  let frontmatter: Record<string, unknown> | undefined;
+  let document: JxMutableNode;
+  let frontmatter: FormatFrontmatter | undefined;
   // The layout of the JSON just written, as every other JSON reader records it (`files/files.ts`,
   // `files/file-ops.ts`): the text is the serializer's own, so the record says what a layout-less
   // Write would do anyway — but the tab reads its file rather than assuming it.
@@ -392,14 +403,17 @@ async function rebuildTab(from: string, to: string, text: string): Promise<void>
     // Points at the file, and reopening it is one click.
     return;
   }
-  openTab({
+  const options: Parameters<typeof openTab>[0] = {
     document,
     documentPath: to,
-    ...(frontmatter === undefined ? {} : { frontmatter }),
     id: to,
     layout,
     sourceFormat: format?.name ?? null,
-  });
+  };
+  if (frontmatter !== undefined) {
+    options.frontmatter = frontmatter;
+  }
+  openTab(options);
 }
 
 const CANNOT_CONVERT =
@@ -499,8 +513,8 @@ export function fileFormatCommands(): AnyCommand[] {
       undo: "none",
       /* No `aiTool`, by studio-ui-guidelines.md §12.4's second deletion rule: `run` awaits a
          confirm dialog the person answers. */
-      run: async (_ctx, args: Record<string, unknown>) => {
-        const target = typeof args.format === "string" ? args.format : undefined;
+      run: async (_ctx, args: CommandArgValues) => {
+        const target = isString(args.format) ? args.format : undefined;
         await convertFile(
           stringArg("file.convertFormat", args, "source"),
           ...(target === undefined ? [] : [target]),

package/src/format/format-choices.ts

@@ -11,6 +11,7 @@
  * context menu is built during a render and cannot await anything.
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import { collectionForFile } from "../content/collection-match";
 import { documentExtensions, formatByExtension, formatForPath, getFormats } from "./format-host";
 import { projectState } from "../store";
@@ -76,7 +77,7 @@ function declaresDocumentKind(kinds: readonly string[]): boolean {
  */
 function isLayoutPath(path: string): boolean {
   const declared = projectState?.projectConfig?.layout;
-  if (typeof declared !== "string") {
+  if (!isString(declared)) {
     return false;
   }
   return normalize(declared).toLowerCase() === normalize(path).toLowerCase();