@jxsuite/studio 6.1.1 → 6.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/studio",
-  "version": "6.1.1",
+  "version": "6.1.2",
   "description": "Jx Studio — visual builder for Jx documents",
   "license": "MIT",
   "repository": {
@@ -71,7 +71,7 @@
     "@jxsuite/schema": "^3.0.0",
     "@jxsuite/site": "^2.0.4",
     "@jxsuite/ui": "^0.5.1",
-    "@vue/reactivity": "3.5.43",
+    "@vue/reactivity": "3.5.44",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "lit-html": "^3.3.3",
@@ -80,11 +80,11 @@
     "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.14.6",
+    "@happy-dom/global-registrator": "^21.0.3",
     "@types/mdast": "^4.0.4",
-    "@webref/css": "^8.7.6",
-    "@webref/elements": "^2.9.1",
-    "@webref/idl": "^3.85.1"
+    "@webref/css": "^8.7.7",
+    "@webref/elements": "^2.9.2",
+    "@webref/idl": "^3.85.2"
   },
   "//vue-reactivity": "Exact pin required — must match @jxsuite/runtime to avoid cross-boundary proxy bugs"
 }

package/src/about/about-modal.ts

@@ -20,9 +20,10 @@ import { openAboutSurface } from "../surfaces/about";
 import { layerHost } from "../ui/layers";
 import { getPlatform } from "../platform";
 import { APP_NAME, BUILD_DATE, GIT_COMMIT, LINKS, VERSION } from "../version";
-import type { AboutRow, AboutSurfaceHandle } from "../surfaces/about";
+import type { AboutSurfaceHandle } from "../surfaces/about";
 import type { AppInfo } from "../types";
 import type { Command, CommandRegistry } from "../commands/registry";
+import type { SurfaceOption } from "../ui/surface";
 
 let _handle: AboutSurfaceHandle | null = null;
 
@@ -36,8 +37,8 @@ function formatBuildDate(iso: string): string {
 }
 
 /** The metadata rows, with the desktop's two appended when the platform reported them. */
-function metaRows(info: AppInfo | null): AboutRow[] {
-  const rows: AboutRow[] = [
+function metaRows(info: AppInfo | null): SurfaceOption[] {
+  const rows: SurfaceOption[] = [
     { label: "Version", value: VERSION },
     { label: "Build date", value: formatBuildDate(BUILD_DATE) },
     { label: "Commit", value: GIT_COMMIT },

package/src/account/action-flow.ts

@@ -22,12 +22,14 @@
  * @docs studio/interface/welcome-screen
  */
 
+import { isFunction } from "@jxsuite/schema/guards";
 import { hydrateAccountStatus, takeToastNotices } from "../account-status";
 import { getPlatform, hasPlatform } from "../platform";
 import { platformErrorInfo } from "../platform-errors";
 import { notify } from "../services/notify";
 import { resetModelCache } from "../services/ai-models";
 import { openDialogSurface } from "../surfaces/dialog";
+import type { DialogSurfaceOptions } from "../surfaces/dialog";
 import { layerHost } from "../ui/layers";
 import { onActionRequired } from "./action-required";
 import type { ActionRequiredReport } from "./action-required";
@@ -43,7 +45,7 @@ export interface ActionPrompt {
 
 /** Whether this platform can perform an offered action at all. */
 export function canPerformActions(): boolean {
-  return hasPlatform() && typeof getPlatform().performAction === "function";
+  return hasPlatform() && isFunction(getPlatform().performAction);
 }
 
 /** The action a surface leads with — the one marked primary, else the first — and one other. */
@@ -87,14 +89,14 @@ export function promptAction(prompt: ActionPrompt): Promise<boolean> {
  * whether the caller should now try again: false for any other error (nothing was offered) and for
  * an offer declined.
  */
-export async function actIfRequired(error: unknown): Promise<boolean> {
-  const info = platformErrorInfo(error);
+export async function actIfRequired(cause: unknown): Promise<boolean> {
+  const info = platformErrorInfo(cause);
   if (info.code !== "action-required" || !info.actions?.length) {
     return false;
   }
   return promptAction({
     actions: info.actions,
-    detail: error instanceof Error ? error.message : undefined,
+    detail: cause instanceof Error ? cause.message : undefined,
     heading: info.heading,
     retry: info.retry,
   });
@@ -137,6 +139,35 @@ function offer(
       });
     };
 
+    /* Follow a started action to its end. A function of its own rather than inline, so `phase` is
+       read as it stands when the action settles, not as it stood when the action began. */
+    const follow = async (flow: Promise<ActionOutcome | null>) => {
+      let outcome: ActionOutcome | null;
+      try {
+        outcome = await flow;
+      } catch (error) {
+        if (phase === "waiting") {
+          offerAgain(error instanceof Error ? error.message : String(error));
+        }
+        return;
+      }
+      /* A done action is re-read even when the dialog is already gone — the user may have
+         dismissed the waiting dialog and finished in the window anyway, and the account must
+         not go on saying otherwise. */
+      if (outcome?.status === "done") {
+        await settleDone();
+        finish(true);
+        return;
+      }
+      if (phase !== "waiting" || !outcome || outcome.status === "redirect") {
+        // Dismissed meanwhile, or the page is navigating to the action: nothing to draw.
+        return;
+      }
+      // Closed without saying: the account may have changed anyway, so re-read it, and offer again.
+      void hydrateAccountStatus();
+      offerAgain(message);
+    };
+
     const begin = (action: OfferedAction) => {
       if (phase !== "offer") {
         return;
@@ -157,34 +188,11 @@ function offer(
         message: "Finish in the window that opened. This closes by itself once it is done.",
         secondaryLabel: "",
       });
-      void flow.then(
-        async (outcome) => {
-          /* A done action is re-read even when the dialog is already gone — the user may have
-             dismissed the waiting dialog and finished in the window anyway, and the account must
-             not go on saying otherwise. */
-          if (outcome?.status === "done") {
-            await settleDone();
-            finish(true);
-            return;
-          }
-          if (phase !== "waiting" || !outcome || outcome.status === "redirect") {
-            // Dismissed meanwhile, or the page is navigating to the action: nothing to draw.
-            return;
-          }
-          // Closed without saying: the account may have changed anyway, so re-read it, and offer again.
-          void hydrateAccountStatus();
-          offerAgain(message);
-        },
-        (error: unknown) => {
-          if (phase === "waiting") {
-            offerAgain(error instanceof Error ? error.message : String(error));
-          }
-        },
-      );
+      void follow(flow);
     };
 
     const { lead, other } = leading;
-    const handle = openDialogSurface({
+    const options: DialogSurfaceOptions = {
       cancelLabel: "Not now",
       confirmLabel: lead.label,
       headline: prompt.heading ?? "One more step",
@@ -201,15 +209,14 @@ function offer(
         begin(lead);
       },
       region: "account/action",
-      ...(other
-        ? {
-            onSecondary: () => {
-              begin(other);
-            },
-            secondaryLabel: other.label,
-          }
-        : {}),
-    });
+    };
+    if (other) {
+      options.onSecondary = () => {
+        begin(other);
+      };
+      options.secondaryLabel = other.label;
+    }
+    const handle = openDialogSurface(options);
   });
 }
 

package/src/account-status.ts

@@ -4,6 +4,7 @@
  * (studio.ts) like the project-list cache; the welcome screen reads it synchronously to prompt
  * "install the GitHub App" when the user has no repository access yet.
  */
+import { isFunction } from "@jxsuite/schema/guards";
 import { getPlatform, hasPlatform } from "./platform";
 import type { AccountEntry, AccountNotice, AccountStatus } from "./types";
 
@@ -11,7 +12,7 @@ let cache: AccountStatus | null = null;
 
 /** Refresh the cache from the platform; null when unsupported, failing, or unknown. */
 export async function hydrateAccountStatus(): Promise<void> {
-  if (!hasPlatform() || typeof getPlatform().getAccountStatus !== "function") {
+  if (!hasPlatform() || !isFunction(getPlatform().getAccountStatus)) {
     cache = null;
     return;
   }
@@ -59,7 +60,11 @@ export function getRepoAccessLinks(): RepoAccessLinks | null {
   if (manage.length === 0 && !cache.appInstallUrl) {
     return null;
   }
-  return { manage, ...(cache.appInstallUrl ? { installUrl: cache.appInstallUrl } : {}) };
+  const links: RepoAccessLinks = { manage };
+  if (cache.appInstallUrl) {
+    links.installUrl = cache.appInstallUrl;
+  }
+  return links;
 }
 
 /** The rows the platform adds to Preferences › Accounts (desktop.md §10.4); none when absent. */

package/src/browse/library-layouts.ts

@@ -128,7 +128,7 @@ export function cellText(file: LibraryFile, field: string): string {
 }
 
 /** Row-shaped access for a caller holding grid cells rather than the typed record. */
-export function cellTextOf(value: GridCellValue): string {
+export function cellTextOf(value: GridCellValue | undefined): string {
   return value === null || value === undefined ? "" : String(value);
 }
 
@@ -172,6 +172,12 @@ function nameRow(file: LibraryFile): LibraryRow {
 
 // ─── Calendar ────────────────────────────────────────────────────────────────
 
+/** The calendar layout: its day sections, and the sentence naming the older days it left out. */
+export interface CalendarView {
+  groups: LibraryGroup[];
+  truncated: string;
+}
+
 /**
  * Calendar: one section per day, newest first, plus an explicit account of what it did not place.
  *
@@ -181,10 +187,7 @@ function nameRow(file: LibraryFile): LibraryRow {
  *
  * @returns The day sections, and the sentence naming the older days it did not draw.
  */
-export function calendarView(files: readonly LibraryFile[]): {
-  groups: LibraryGroup[];
-  truncated: string;
-} {
+export function calendarView(files: readonly LibraryFile[]): CalendarView {
   const { days, undated } = groupByDate(files);
   const shown = days.slice(0, CALENDAR_DAY_LIMIT);
   const hiddenDays = days.length - shown.length;

package/src/browse/library-model.ts

@@ -140,6 +140,9 @@ export function categoryFor(dir: string, ext: string): string {
  * @returns {string | null}
  */
 export function contentTypeFor(filePath: string): string | null {
+  /* SAFETY: `content` is the parser extension's opaque project section, which its project fragment
+     schema defines as a map of section entries; the loop reads only the optional `source`, and skips
+     an entry without one. */
   const content = (projectState?.projectConfig?.content ?? {}) as Record<
     string,
     ContentSectionEntry
@@ -199,7 +202,7 @@ async function walk(
       name: entry.name,
       path: entry.path,
       size: entry.size,
-      type: category === "Content" ? (contentTypeFor(entry.path) ?? ext ?? "file") : ext || "file",
+      type: category === "Content" ? (contentTypeFor(entry.path) ?? ext) : ext || "file",
     });
   }
   // Siblings in parallel, depth serialized per branch: the platform counts every call as in-flight,
@@ -278,7 +281,7 @@ export const LIBRARY_LAYOUT_LABELS: Readonly<Record<LibraryLayout, string>> = {
 
 /** Whether a string names a layout — the guard behind `library.setLayout`'s argument. */
 export function isLibraryLayout(value: string): value is LibraryLayout {
-  return (LIBRARY_LAYOUTS as readonly string[]).includes(value);
+  return LIBRARY_LAYOUTS.some((layout) => layout === value);
 }
 
 /** Layouts that draw a live preview per item. Table and Board draw text, and stay cheap. */
@@ -345,11 +348,20 @@ export function libraryLocales(files: readonly LibraryFile[]): string[] {
   return projectLocales().filter((tag) => present.has(tag));
 }
 
+/** One Calendar day: the files whose derived date is `date`. */
+export interface LibraryDay {
+  date: string;
+  files: LibraryFile[];
+}
+
 /** Calendar buckets, newest day first, plus the files no date could be derived for. */
-export function groupByDate(files: readonly LibraryFile[]): {
-  days: { date: string; files: LibraryFile[] }[];
+export interface LibraryDateGroups {
+  days: LibraryDay[];
   undated: LibraryFile[];
-} {
+}
+
+/** Calendar buckets, newest day first, plus the files no date could be derived for. */
+export function groupByDate(files: readonly LibraryFile[]): LibraryDateGroups {
   const byDay = new Map<string, LibraryFile[]>();
   const undated: LibraryFile[] = [];
   for (const file of files) {
@@ -366,7 +378,7 @@ export function groupByDate(files: readonly LibraryFile[]): {
     }
   }
   const days = [...byDay.entries()]
-    .map(([date, dayFiles]) => ({ date, files: dayFiles }))
+    .map(([date, dayFiles]): LibraryDay => ({ date, files: dayFiles }))
     .toSorted((a, b) => b.date.localeCompare(a.date));
   return { days, undated };
 }

package/src/browse/library-pane.ts

@@ -35,6 +35,7 @@ import { errorMessage } from "@jxsuite/schema/parse";
 import { notify } from "../services/notify";
 import { beginActivity } from "../panels/activity-panel";
 import { showPromptDialog } from "../ui/layers";
+import type { PromptDialogOptions } from "../ui/layers";
 import { openMenu } from "../surfaces/menu";
 import { rectOf } from "../utils/geometry";
 import { getPlatform } from "../platform";
@@ -63,7 +64,7 @@ import { paneRegion } from "../ui/regions";
 import { LAYOUT_METRICS, boardView, calendarView, columnsAt, libraryRow } from "./library-layouts";
 import { mountLibrarySurface } from "../surfaces/library-pane";
 import type { ActivityHandle } from "../panels/activity-panel";
-import type { FormatChoice } from "../files/files";
+import type { FormatChoice, NewFileRequest } from "../files/files";
 import type { EffectScope } from "@vue/reactivity";
 import type { MenuHandle, MenuRowProjection } from "../surfaces/menu";
 import type { LibraryFile, LibraryLayout } from "./library-model";
@@ -195,13 +196,18 @@ const SCAN_PROBLEM_KEY = "library.scan";
  * contract exists to end. The row is informational, and it only appears when the scan is slow
  * enough that its absence would look like a hang.
  */
+/** The scan's Activity row, filled in only once the scan outlasts {@link SCAN_ACTIVITY_DELAY_MS}. */
+interface SlowScanActivity {
+  handle: ActivityHandle | null;
+}
+
 async function loadLibrary(): Promise<void> {
   const current = librarySource();
   scanAttempted = true;
   libraryView.loading = true;
   bump();
 
-  const slow: { handle: ActivityHandle | null } = { handle: null };
+  const slow: SlowScanActivity = { handle: null };
   const timer = setTimeout(() => {
     slow.handle = beginActivity({
       source: "Library",
@@ -584,13 +590,16 @@ function showLibraryNewMenu(opener: HTMLElement): void {
  */
 async function renameLibraryFile(file: LibraryFile) {
   const message = await renamePromptMessage(file.path);
-  const newName = await showPromptDialog("Rename", {
+  const prompt: PromptDialogOptions = {
     confirmLabel: "Rename",
-    ...(message === undefined ? {} : { message }),
     select: "stem",
     validate: (value) => (value.trim() ? "" : "Enter a file name."),
     value: file.name,
-  });
+  };
+  if (message !== undefined) {
+    prompt.message = message;
+  }
+  const newName = await showPromptDialog("Rename", prompt);
   if (!newName || newName === file.name) {
     return;
   }
@@ -724,11 +733,11 @@ export function libraryNewEntries(): LibraryNewEntry[] {
  * through the format's own serializer, because this module knows no format's syntax.
  */
 /** How each document kind's extension is settled. Anything else falls back to the full picker. */
-const FORMAT_CHOICE_BY_KIND: Record<string, FormatChoice> = {
-  component: { defaultExt: ".json", docKind: "component", kind: "choose" },
-  layout: { ext: ".json", kind: "fixed" },
-  page: { defaultExt: ".json", docKind: "page", kind: "choose" },
-};
+const FORMAT_CHOICE_BY_KIND = new Map<string, FormatChoice>([
+  ["component", { defaultExt: ".json", docKind: "component", kind: "choose" }],
+  ["layout", { ext: ".json", kind: "fixed" }],
+  ["page", { defaultExt: ".json", docKind: "page", kind: "choose" }],
+]);
 
 /**
  * The body a new component starts as, when the reader picked a format rather than `.json`.
@@ -767,17 +776,22 @@ export async function createLibraryEntry(key: string): Promise<string | null> {
   if (!entry) {
     return null;
   }
-  const created =
-    entry.collection === undefined
-      ? await createFileIn({
-          ...(entry.key === "component" ? { content: componentSeed } : {}),
-          dir: entry.dir,
-          format: FORMAT_CHOICE_BY_KIND[entry.key] ?? { defaultExt: ".json", kind: "choose" },
-          source: "Library",
-          suggestedName: "untitled",
-          title: `New ${entry.label}`,
-        })
-      : await createEntry(entry.collection);
+  let created: string | null;
+  if (entry.collection === undefined) {
+    const request: NewFileRequest = {
+      dir: entry.dir,
+      format: FORMAT_CHOICE_BY_KIND.get(entry.key) ?? { defaultExt: ".json", kind: "choose" },
+      source: "Library",
+      suggestedName: "untitled",
+      title: `New ${entry.label}`,
+    };
+    if (entry.key === "component") {
+      request.content = componentSeed;
+    }
+    created = await createFileIn(request);
+  } else {
+    created = await createEntry(entry.collection);
+  }
   if (created === null) {
     return null;
   }
@@ -1017,6 +1031,8 @@ export function renderLibraryMode(surface: CanvasSurface, tab: Tab): void {
     },
     search: (value) => setLibrarySearch(value),
     setCategory: (key) => setLibraryCategory(key),
+    /* SAFETY: the surface's layout buttons pass `$map.item.key`, and the `layouts` state they map is
+       built from LIBRARY_LAYOUTS in the projection above, so every key is a LibraryLayout. */
     setLayout: (key) => setLibraryLayout(key as LibraryLayout),
     setLocale: (value) => setLibraryLocale(value === "all" ? "" : value),
     upload: (input) => {

package/src/browse/library-preview.ts

@@ -25,6 +25,7 @@ import {
   setCanvasAssetResolver,
   setSkipServerFunctions,
 } from "@jxsuite/runtime";
+import { isFunction } from "@jxsuite/schema/guards";
 import { assetContextFor, hostAssetDeclarations, resolveAssetRef } from "../canvas/asset-refs";
 import { assetVersionsSnapshot } from "../files/asset-versions";
 import { componentRegistry } from "../files/components";
@@ -74,12 +75,13 @@ export function createPreviewCache(limit: number = PREVIEW_CACHE_LIMIT): Preview
   const entries = new Map<string, HTMLElement>();
 
   function evict() {
-    // `size > limit` guarantees a first key, so the iterator result is never `done` here.
-    while (entries.size > limit) {
-      const oldest = entries.keys().next().value as string;
-      const stale = entries.get(oldest);
+    // Insertion order is LRU order, and deleting the entry being visited is safe mid-iteration.
+    for (const [oldest, stale] of entries) {
+      if (entries.size <= limit) {
+        break;
+      }
       entries.delete(oldest);
-      stale?.remove();
+      stale.remove();
     }
   }
 
@@ -127,8 +129,13 @@ export async function renderDocPreview(filePath: string): Promise<HTMLElement |
     let document_: JxDocument;
     if (formatForPath(filePath)) {
       const parsed = await parseSourceForPath(filePath, content);
+      /* SAFETY: a format class's parser returns its file as a Jx element tree (the format contract),
+         and the split hands that same tree back as `document`; a tree renderNode cannot draw throws
+         into the catch below, which is "no preview". */
       document_ = parsed.document as JxDocument;
     } else {
+      /* SAFETY: a `.json` file in the Library is a project document by the project layout; malformed
+         JSON or a shape renderNode cannot draw throws into the catch below, which is "no preview". */
       document_ = JSON.parse(content) as JxDocument;
     }
     const scope = await buildScope(document_, {}, location.href);
@@ -166,9 +173,7 @@ export async function previewFor(
   let rendered: HTMLElement | null | undefined;
   try {
     const component = componentRegistry.find((c: ComponentEntry) => c.path === path);
-    rendered = component
-      ? ((await renderComponentPreview(component)) as HTMLElement | undefined)
-      : await renderDocPreview(path);
+    rendered = component ? await renderComponentPreview(component) : await renderDocPreview(path);
   } catch {
     return undefined;
   }
@@ -219,7 +224,7 @@ export interface PreviewObserver {
  * retained on that path, so there is nothing for the sweep to find.
  */
 export function createPreviewObserver(onVisible: (element: Element) => void): PreviewObserver {
-  if (typeof IntersectionObserver !== "function") {
+  if (!isFunction(globalThis.IntersectionObserver)) {
     return {
       destroy() {
         /* Nothing to disconnect. */

package/src/browse/library-source.ts

@@ -93,7 +93,7 @@ export function createLibrarySource(dirs?: () => readonly string[]): LibrarySour
   let scan: LibraryScan | null = null;
   let inFlight: Promise<LibraryScan> | null = null;
 
-  const projectDirs = dirs ?? (() => (projectState?.projectDirs ?? []) as readonly string[]);
+  const projectDirs = dirs ?? (() => projectState?.projectDirs ?? []);
 
   async function ensureScan(): Promise<LibraryScan> {
     if (scan) {

package/src/canvas/asset-refs.ts

@@ -53,6 +53,9 @@ export function assetContextFor(
   const space = over?.space ?? "site";
   const mount = contentMountFor(
     documentPath,
+    /* SAFETY: `content` is the parser extension's opaque project section, which its project
+       fragment schema defines as a map of section entries; contentMountFor reads only each entry's
+       optional `source` and skips an entry without one. */
     projectState?.projectConfig?.content as Record<string, ContentSectionEntry> | undefined,
     projectLocales(),
   );
@@ -61,13 +64,16 @@ export function assetContextFor(
   if (space === "site" && !mount) {
     return null;
   }
-  return {
+  const context: AssetContext = {
     documentDir: dirOfPath(documentPath ?? ""),
-    ...(over?.fileBaseUrl === undefined ? {} : { fileBaseUrl: over.fileBaseUrl }),
     lanes: BUILD_LANES,
     mounts: mount ? [mount] : [],
     space,
   };
+  if (over?.fileBaseUrl !== undefined) {
+    context.fileBaseUrl = over.fileBaseUrl;
+  }
+  return context;
 }
 
 /**
@@ -99,6 +105,15 @@ export function previewAssetSrc(value: string): string {
   return loopbackAssetSrc(resolveAssetRef(value, versioned) ?? value);
 }
 
+/**
+ * The registered host's media declarations: its asset space, and the base project files serve
+ * under.
+ */
+export interface HostAssetDeclarations {
+  space?: "site" | "repo" | undefined;
+  fileBaseUrl: string;
+}
+
 /**
  * What the registered host says about media — the platform's `assetSpace`, and the base project
  * files are served under.
@@ -108,14 +123,14 @@ export function previewAssetSrc(value: string): string {
  * The canvas pipeline builds the same two values from the same two places; the difference is only
  * that it already has the document in hand.
  *
- * @returns {{ space?: "site" | "repo"; fileBaseUrl: string }} The host's declarations
+ * @returns {HostAssetDeclarations} The host's declarations
  */
-export function hostAssetDeclarations(): {
-  space?: "site" | "repo" | undefined;
-  fileBaseUrl: string;
-} {
-  return {
+export function hostAssetDeclarations(): HostAssetDeclarations {
+  const declarations: HostAssetDeclarations = {
     fileBaseUrl: documentBase(projectState?.projectRoot),
-    ...(hasPlatform() ? { space: getPlatform().assetSpace } : {}),
   };
+  if (hasPlatform()) {
+    declarations.space = getPlatform().assetSpace;
+  }
+  return declarations;
 }