@jxsuite/studio 6.1.1 → 8.0.0

package/src/media/media-pane.ts

@@ -29,9 +29,16 @@
 
 import { effect, effectScope } from "../reactivity";
 import { paneRegion } from "../ui/regions";
+import { localDay } from "../utils/local-day";
 import { mediaSiteUrl, previewFileSrc } from "../files/media-paths";
-import { formatBytes, loadMediaMeta, peekMediaMeta, recordImageSize } from "../files/media-meta";
-import { extensionOf, mediaKind } from "../files/media-upload";
+import {
+  formatBytes,
+  loadMediaMeta,
+  mediaMetaSettled,
+  peekMediaMeta,
+  recordImageSize,
+} from "../files/media-meta";
+import { FONT_EXTENSIONS, extensionOf, mediaKind } from "../files/media-upload";
 import { loadMediaUsages, mediaUsageHeadline, peekMediaUsages } from "../files/media-usage";
 import { mountMediaSurface } from "../surfaces/media-pane";
 import type { MediaStage, MediaSurfaceHandle, MediaView } from "../surfaces/media-pane";
@@ -43,9 +50,6 @@ import type { CanvasSurface } from "../canvas/canvas-surface";
 /** The `canvasMode` the media viewer draws under. */
 export const MEDIA_MODE = "media";
 
-/** Extensions the viewer renders as a font specimen rather than as a file it cannot show. */
-const FONT_EXTENSIONS = new Set([".woff", ".woff2", ".ttf", ".otf"]);
-
 /** The pangram the font specimen is set in — short, and every letter of the alphabet once. */
 const SPECIMEN = "The quick brown fox jumps over the lazy dog";
 
@@ -97,9 +101,11 @@ export function detachMediaPane(paneId: string): void {
  * Which element the stage should draw this file in.
  *
  * A font is decided by extension before anything else: `mediaKind` calls a `.woff2` a plain file,
- * and a file the browser cannot render is the last answer here rather than the first.
+ * and a file the browser cannot render is the last answer here rather than the first. Exported
+ * because the Media workspace's detail pane (`media/media-library.ts`) asks the same question, and
+ * two answers to it would drift.
  */
-function stageFor(path: string): MediaStage {
+export function mediaStageFor(path: string): MediaStage {
   const ext = extensionOf(path);
   if (FONT_EXTENSIONS.has(ext)) {
     return "font";
@@ -112,7 +118,7 @@ function stageFor(path: string): MediaStage {
 }
 
 /** Kind, dimensions, size and modified time — each omitted rather than zeroed when unknown. */
-function factsLine(path: string, meta: MediaMeta | null): string {
+export function factsLine(path: string, meta: MediaMeta | null): string {
   const facts: string[] = [mediaKind({ name: path })];
   if (meta?.width != null && meta.height != null) {
     facts.push(`${meta.width} × ${meta.height}`);
@@ -121,7 +127,8 @@ function factsLine(path: string, meta: MediaMeta | null): string {
     facts.push(formatBytes(meta.bytes));
   }
   if (meta?.modified) {
-    facts.push(`modified ${meta.modified.slice(0, 10)}`);
+    // The local day it was modified on (`utils/local-day.ts`), not the UTC one.
+    facts.push(`modified ${localDay(new Date(meta.modified))}`);
   }
   return facts.join(" · ");
 }
@@ -131,8 +138,30 @@ function specimenFamily(path: string): string {
   return `jx-specimen-${path.replaceAll(/[^a-zA-Z0-9]/g, "-")}`;
 }
 
+/** What a font specimen draws: its scoped face, the custom property naming it, and the pangram. */
+export interface FontSpecimen {
+  /** A `@font-face` rule for the generated family, loading the file from its preview src. */
+  fontFace: string;
+  /** `--jx-specimen-family: "<family>"`, the one inline declaration a specimen element carries. */
+  specimenFamily: string;
+  specimen: string;
+}
+
+/**
+ * The specimen for a font file, shared by the viewer and the Media workspace's detail pane, so a
+ * font is shown by being USED in both and the face is scoped the same way in both.
+ */
+export function specimenOf(path: string): FontSpecimen {
+  const family = specimenFamily(path);
+  return {
+    fontFace: `@font-face { font-family: "${family}"; src: url("${previewFileSrc(path)}"); }`,
+    specimen: SPECIMEN,
+    specimenFamily: `--jx-specimen-family: "${family}"`,
+  };
+}
+
 /** Which documents reference this file, or the honest reason there is no list. */
-function usageOf(
+export function usageOf(
   usage: UsageState | null,
 ): Pick<MediaView, "usageState" | "usageHeadline" | "usageFiles"> {
   const headline = mediaUsageHeadline(usage);
@@ -179,11 +208,10 @@ export function renderMediaMode(surface: CanvasSurface, tab: Tab): void {
   detachMediaPane(paneId);
 
   const path = tab.documentPath ?? "";
-  const family = specimenFamily(path);
   const src = previewFileSrc(path);
   const ref = mediaSiteUrl(path);
   const ext = extensionOf(path);
-  const kind = stageFor(path);
+  const kind = mediaStageFor(path);
 
   let panel: ActiveMediaPane | null = null;
   const redraw = () => {
@@ -197,25 +225,25 @@ export function renderMediaMode(surface: CanvasSurface, tab: Tab): void {
     const usage = peekMediaUsages(path);
     /* Asked on the first paint that finds it missing, never on every paint: both loaders cache and
        de-duplicate in flight, and both repaint through `redraw` when they land. */
-    if (meta === null) {
+    if (!mediaMetaSettled(path)) {
       void loadMediaMeta(path).then(redraw);
     }
     if (usage === null || usage.status === "pending") {
       void loadMediaUsages(path).then(redraw);
     }
+    /* The face is scoped to the generated family name, so two specimens open side by side cannot
+       claim the same one. Written only for a font: every other stage carries an empty sheet. */
+    const specimen = specimenOf(path);
     return {
       extLabel: ext || "this file",
       facts: factsLine(path, meta),
-      /* The face is scoped to the generated family name, so two specimens open side by side cannot
-         claim the same one. Written only for a font: every other stage carries an empty sheet. */
-      fontFace:
-        kind === "font" ? `@font-face { font-family: "${family}"; src: url("${src}"); }` : "",
+      fontFace: kind === "font" ? specimen.fontFace : "",
       kind,
       name: path.split("/").pop() ?? "",
       ref,
       region: paneRegion(paneId, "media"),
-      specimen: SPECIMEN,
-      specimenFamily: `--jx-specimen-family: "${family}"`,
+      specimen: specimen.specimen,
+      specimenFamily: specimen.specimenFamily,
       src,
       ...usageOf(usage),
     };
@@ -228,7 +256,10 @@ export function renderMediaMode(surface: CanvasSurface, tab: Tab): void {
   const scope = effectScope();
   const mounted = mountMediaSurface(canvasWrap, view(), {
     copyRef: () => {
-      void navigator.clipboard?.writeText(ref);
+      // `navigator.clipboard` is [SecureContext]: a plain-http host has none, whatever lib.dom says.
+      if ("clipboard" in navigator) {
+        void navigator.clipboard.writeText(ref);
+      }
     },
     imageLoaded: (width, height) => {
       /* The only honest source of pixel dimensions in a browser is an image that has loaded, and

package/src/new-project/add-repo-modal.ts

@@ -35,6 +35,7 @@
 
 import { actIfRequired } from "../account/action-flow";
 import { errorMessage } from "@jxsuite/schema/parse";
+import { isFunction } from "@jxsuite/schema/guards";
 import {
   getAccountStatus,
   getRepoAccessLinks,
@@ -90,7 +91,7 @@ let _resolve: ((result: { root: string } | null) => void) | null = null;
 /** True when the active platform can browse + adopt existing repositories. */
 export function platformSupportsAddRepo(): boolean {
   const platform = getPlatform();
-  return typeof platform.listRepos === "function" && typeof platform.importProject === "function";
+  return isFunction(platform.listRepos) && isFunction(platform.importProject);
 }
 
 /** True when the active platform routes Open Project through this repo picker. */
@@ -207,7 +208,7 @@ function loadRepos(): void {
         requestScan(_selected, "now");
       }
     })
-    .catch((error: unknown) => {
+    .catch((error) => {
       _repos = [];
       _error = errorMessage(error);
     })
@@ -492,11 +493,8 @@ async function adopt(fullName: string, dir: string, retried = false): Promise<vo
   _error = "";
   redraw();
   try {
-    const imported = await getPlatform().importProject?.({
-      name: repo.name,
-      owner: repo.owner,
-      ...(dir ? { dir } : {}),
-    });
+    const request = { name: repo.name, owner: repo.owner };
+    const imported = await getPlatform().importProject?.(dir ? { ...request, dir } : request);
     if (_handle !== handle) {
       return;
     }
@@ -604,13 +602,16 @@ function accessOf(): AddRepoView["access"] {
   ];
 }
 
-/** The chosen repository's pane: its state, its rows, and the sentence under the folder field. */
-function detailOf(repo: RepoInfo | undefined): Pick<
+/** The chosen repository's pane, plus the branch it is read at. */
+interface RepoDetail extends Pick<
   AddRepoView,
   "detailState" | "detailName" | "detailMeta" | "locations" | "folderHelp"
-> & {
+> {
   branch: string;
-} {
+}
+
+/** The chosen repository's pane: its state, its rows, and the sentence under the folder field. */
+function detailOf(repo: RepoInfo | undefined): RepoDetail {
   if (!repo) {
     return {
       branch: "",
@@ -623,12 +624,13 @@ function detailOf(repo: RepoInfo | undefined): Pick<
   }
   const scanned = _scans.get(repo.fullName);
   const branch = scanned?.status === "done" ? scanned.projects.branch : repo.defaultBranch;
+  const noLocations: AddRepoLocation[] = [];
   const base = {
     branch,
     detailMeta: [branch, repo.permission, ...(repo.private ? ["private"] : [])].join(" · "),
     detailName: repo.fullName,
     folderHelp: "The folder that holds project.json. Leave it empty for the repository root.",
-    locations: [] as AddRepoLocation[],
+    locations: noLocations,
   };
   if (!getPlatform().listRepoProjects) {
     return { ...base, detailState: "unlisted" };
@@ -640,17 +642,16 @@ function detailOf(repo: RepoInfo | undefined): Pick<
     return { ...base, detailState: "failed" };
   }
   const { locations, truncated } = scanned.projects;
-  return {
+  const detail: RepoDetail = {
     ...base,
     detailState: locations.length > 0 ? "listed" : "empty",
-    ...(truncated
-      ? {
-          folderHelp:
-            "This repository is too large to scan in full. Name the folder if its project isn't listed.",
-        }
-      : {}),
     locations: locations.map((location) => locationOf(location, repo)),
   };
+  if (truncated) {
+    detail.folderHelp =
+      "This repository is too large to scan in full. Name the folder if its project isn't listed.";
+  }
+  return detail;
 }
 
 /** Everything the dialog draws, as one record. The only place this module's state becomes a view. */

package/src/new-project/import-tab.ts

@@ -25,7 +25,9 @@ import { createModelPicker } from "../ui/ai-model-picker";
 import { destinationPath } from "./location-fields";
 import type { CreateProjectDestination, ImportBreakpointPolicy } from "../types";
 
-import { setPendingImportBrief } from "../services/import-seed";
+import { IMPORT_MAX_BREAKPOINTS } from "@jxsuite/protocol";
+
+import { MAX_IMPORT_DEPTH, setPendingImportBrief } from "../services/import-seed";
 import type { ImportBrief } from "../services/import-seed";
 
 /** The three answers the Breakpoints control offers. */
@@ -34,17 +36,6 @@ type BreakpointMode = "all" | "limit" | "explicit";
 /** How a kept width matches one the site declared. */
 type BreakpointRounding = "nearest" | "down" | "up";
 
-/** The most breakpoints the control will offer to keep — `@jxsuite/import`'s own ceiling. */
-const MAX_BREAKPOINTS = 12;
-
-/**
- * The deepest crawl the pipeline accepts.
- *
- * The field said 2 while `import_site` and the endpoint both clamped to 5, so the wizard could not
- * ask for a depth the backend was willing to run.
- */
-const MAX_DEPTH = 5;
-
 export interface ImportTabCtx {
   /** The wizard's shared name/directory state (the import destination slug). */
   form: { name: string; directory: string };
@@ -383,8 +374,8 @@ export function importView(ctx: ImportTabCtx): ImportView {
     canVerify: canVerify(),
     depth: String(_depth),
     error: _errorMsg,
-    maxBreakpoints: String(MAX_BREAKPOINTS),
-    maxDepth: String(MAX_DEPTH),
+    maxBreakpoints: String(IMPORT_MAX_BREAKPOINTS),
+    maxDepth: String(MAX_IMPORT_DEPTH),
     maxPages: String(_maxPages),
     minFidelity: String(_minFidelity),
     prompt: _prompt,
@@ -438,6 +429,8 @@ export function setImportMaxPages(value: string): void {
 
 /** Which of the three breakpoint answers the reader chose. */
 export function setBreakpointMode(value: string): void {
+  /* SAFETY: Studio's one caller is the `bp-mode` select's change handler (surfaces/new-project.json),
+     and that select's options are `importView().breakpointModes`: "limit", "explicit" and "all". */
   _breakpointMode = value as BreakpointMode;
 }
 
@@ -453,6 +446,9 @@ export function setBreakpointWidths(value: string): void {
 
 /** Which declared width backs a kept one. */
 export function setBreakpointRounding(value: string): void {
+  /* SAFETY: Studio's one caller is the `bp-rounding` select's change handler (surfaces/
+     new-project.json), and that select's options are `importView().roundings`: "nearest", "down"
+     and "up". */
   _breakpointRounding = value as BreakpointRounding;
 }
 

package/src/new-project/location-fields.ts

@@ -22,6 +22,7 @@
  */
 
 import { errorMessage } from "@jxsuite/schema/parse";
+import { isFunction } from "@jxsuite/schema/guards";
 import { getPlatform } from "../platform";
 import type { CreateProjectDestination, RepoInfo } from "../types";
 
@@ -211,7 +212,7 @@ export function locationView(slug: string): LocationView {
   return {
     browseLabel: _browsing ? "Choosing…" : "Browse…",
     browsing: _browsing,
-    canBrowse: typeof platform.pickDirectory === "function",
+    canBrowse: isFunction(platform.pickDirectory),
     destination: isRepo ? "repo" : "path",
     error: _error,
     owner: _owner,

package/src/new-project/new-project-modal.ts

@@ -41,6 +41,7 @@
 import { errorMessage } from "@jxsuite/schema/parse";
 import { layerHost } from "../ui/layers";
 import { enumArg, enumProperty } from "../commands/command-args";
+import type { CommandArgValues } from "../commands/command-args";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 import { getPlatform } from "../platform";
 import { installUrlOf } from "../platform-errors";
@@ -118,9 +119,9 @@ let _nameError = "";
 /** GitHub-App install link carried by a structured needs_installation_access failure. */
 let _errorInstallUrl = "";
 
-function captureError(error: unknown) {
-  _error = errorMessage(error);
-  _errorInstallUrl = installUrlOf(error) ?? "";
+function captureError(cause: unknown) {
+  _error = errorMessage(cause);
+  _errorInstallUrl = installUrlOf(cause) ?? "";
 }
 
 let _creating = false;
@@ -244,6 +245,8 @@ export function openNewProjectModal(options?: { tab?: NewProjectTab }): Promise<
           if (_creating) {
             return;
           }
+          /* SAFETY: `value` is the selected `jx-tab`'s value, and the strip renders one tab per
+             `viewOf().tabs` entry, whose values are "starter", "import" and "agent". */
           _tab = value as NewProjectTab;
           _error = "";
           redraw();
@@ -348,10 +351,10 @@ async function finishCreated(result: { root: string; config: ProjectConfig }) {
     getTab: () => null,
   });
   if (!adopted && !openedElsewhere) {
-    notify.warn("Created the project, but could not open it here.", {
-      ...(error === null ? {} : { detail: error }),
-      source: "New Project",
-    });
+    notify.warn(
+      "Created the project, but could not open it here.",
+      error === null ? { source: "New Project" } : { detail: error, source: "New Project" },
+    );
   }
   finish(result);
 }
@@ -708,9 +711,9 @@ export function newProjectCommands(): AnyCommand[] {
       group: "1_file",
       /* No `aiTool`: application-level, refused at registration; it opens the wizard, and the
          model's own door is `create_project` / `import_site` (studio-ui-guidelines.md §12.4). */
-      run: (_commandCtx, args) => {
+      run: (_commandCtx, args: CommandArgValues) => {
         const tab =
-          (args as { tab?: unknown }).tab === undefined
+          args.tab === undefined
             ? undefined
             : enumArg("project.new", args, "tab", NEW_PROJECT_TABS);
         void openNewProjectModal(tab === undefined ? {} : { tab });

package/src/packages/jxsuite-update.ts

@@ -29,9 +29,10 @@ import { openJxsuiteUpdateSurface } from "../surfaces/jxsuite-update";
 import { showProgressModal } from "../ui/progress-modal";
 import { notify } from "../services/notify";
 import { isUpgrade } from "./semver";
-import type { JxsuiteUpdateSurfaceHandle } from "../surfaces/jxsuite-update";
+import type { DialogLayerHandle } from "../ui/surface";
 
-const JXSUITE_PREFIX = "@jxsuite/";
+/** The npm scope every first-party package is published under. */
+export const JXSUITE_PREFIX = "@jxsuite/";
 
 export interface JxsuiteUpdate {
   name: string;
@@ -170,7 +171,7 @@ function askToUpdate(outdated: JxsuiteUpdate[]): Promise<boolean> {
       closing = true;
       handle.close();
     };
-    const handle: JxsuiteUpdateSurfaceHandle = openJxsuiteUpdateSurface({
+    const handle: DialogLayerHandle = openJxsuiteUpdateSurface({
       layer: layerHost("dialog"),
       onCancel: () => {
         takeDown();

package/src/packages/pull-package-sync.ts

@@ -10,11 +10,13 @@
  */
 
 import { errorMessage } from "@jxsuite/schema/parse";
+import { isJsonObject } from "@jxsuite/schema/guards";
+import type { JsonObject, JsonValue } from "@jxsuite/schema/types";
 import { getPlatform } from "../platform";
 import { showConfirmDialog } from "../ui/layers";
 import { showProgressModal } from "../ui/progress-modal";
 import { notify } from "../services/notify";
-import { applyJxsuiteUpdate, checkJxsuiteUpdate } from "./jxsuite-update";
+import { JXSUITE_PREFIX, applyJxsuiteUpdate, checkJxsuiteUpdate } from "./jxsuite-update";
 import type { GitStatusResult } from "../types";
 
 const PKG_PATHS = ["package.json", "bun.lock", "bun.lockb"];
@@ -29,20 +31,16 @@ const UNTRACKED_STATUSES = new Set(["??", "U"]);
 /** Above this many dirty files, skip the per-file upstream comparison and leave the error as-is. */
 const MAX_CONFLICT_SCAN = 25;
 
-const JXSUITE_PREFIX = "@jxsuite/";
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function sortKeys(value: unknown): unknown {
+/** A copy of a JSON value with every object's keys in sorted order, so equal data prints equal. */
+function sortKeys(value: JsonValue): JsonValue {
   if (Array.isArray(value)) {
     return value.map((entry) => sortKeys(entry));
   }
-  if (isRecord(value)) {
-    const out: Record<string, unknown> = {};
-    for (const key of Object.keys(value).toSorted()) {
-      out[key] = sortKeys(value[key]);
+  if (isJsonObject(value)) {
+    const out: JsonObject = {};
+    // Keys are unique, so the comparator never sees a tie; `<` is the default sort's code-unit order.
+    for (const [key, entry] of Object.entries(value).toSorted(([a], [b]) => (a < b ? -1 : 1))) {
+      out[key] = sortKeys(entry);
     }
     return out;
   }
@@ -50,11 +48,11 @@ function sortKeys(value: unknown): unknown {
 }
 
 /** Replace every @jxsuite/* version in dependencies/devDependencies so they compare equal. */
-function maskJxsuiteVersions(pkg: Record<string, unknown>): Record<string, unknown> {
+function maskJxsuiteVersions(pkg: JsonObject): JsonObject {
   const out = { ...pkg };
   for (const section of ["dependencies", "devDependencies"]) {
     const deps = out[section];
-    if (!isRecord(deps)) {
+    if (!isJsonObject(deps)) {
       continue;
     }
     const masked = { ...deps };
@@ -88,7 +86,7 @@ export function isAutomatedPackageDiff(
   } catch {
     return false;
   }
-  if (!isRecord(head) || !isRecord(working)) {
+  if (!isJsonObject(head) || !isJsonObject(working)) {
     return false;
   }
   return (
@@ -251,20 +249,20 @@ async function discardPullAndSync(plan: PackagePullPlan): Promise<void> {
   await syncPackagesAfterPull();
 }
 
-async function recoverAfterFailedPull(original: unknown): Promise<void> {
+async function recoverAfterFailedPull(cause: unknown): Promise<void> {
   const platform = getPlatform();
   let status: GitStatusResult;
   try {
     status = await platform.gitStatus();
   } catch {
-    throw original;
+    throw cause;
   }
   if (!(status.behind > 0)) {
-    throw original;
+    throw cause;
   }
   const plan = await planPackageDiscard(status);
   if (planIsEmpty(plan) || (await otherFilesConflict(status))) {
-    throw original;
+    throw cause;
   }
   if (!plan.automated) {
     const confirmed = await showConfirmDialog(
@@ -273,7 +271,7 @@ async function recoverAfterFailedPull(original: unknown): Promise<void> {
       { confirmLabel: "Discard and pull", destructive: true },
     );
     if (!confirmed) {
-      throw original;
+      throw cause;
     }
   }
   await discardPullAndSync(plan);
@@ -346,15 +344,18 @@ export async function pullWithPackageSync(): Promise<void> {
  */
 export async function autoSyncProjectOnOpen(): Promise<void> {
   const platform = getPlatform();
-  let status: GitStatusResult;
   try {
-    status = await platform.gitStatus();
+    /* The status is host wire data. A host may leave `remotes` out (as `deploy-checklist.ts` and
+       `publish-changes.ts` also allow), which reads as "nothing to sync"; a host that sends no status at
+       all throws on the first read and is caught below the same way, so a malformed status never
+       aborts the project open that awaits this. */
+    const status = await platform.gitStatus();
+    if (!status.isRepo || !Array.isArray(status.remotes) || status.remotes.length === 0) {
+      return;
+    }
   } catch {
     return;
   }
-  if (!status?.isRepo || (status.remotes?.length ?? 0) === 0) {
-    return;
-  }
   notify.info("Syncing project…", { key: "project.sync", source: "Source Control" });
   try {
     await pullWithPackageSync();