@jxsuite/studio 6.1.1 → 8.0.0

package/src/canvas/preview-navigate.ts

@@ -24,3 +24,19 @@ export function setPreviewNavigateHandler(next: PreviewNavigateHandler | null):
 export function getPreviewNavigateHandler(): PreviewNavigateHandler | null {
   return handler;
 }
+
+/**
+ * Hand a URL to the user's real browser.
+ *
+ * Reuses the seam the desktop launchers already register for Preview link clicks, which routes
+ * through the OS rather than navigating a webview with no address bar; the browser build falls back
+ * to a new tab. One function, because Open in Browser and the Publish workspace's Visit site and
+ * deployment links all mean the same thing by "open this outside Studio".
+ */
+export function openUrlExternally(url: string): void {
+  if (handler) {
+    handler(url);
+    return;
+  }
+  window.open(url, "_blank", "noopener,noreferrer");
+}

package/src/canvas/repeater-sources.ts

@@ -0,0 +1,200 @@
+/**
+ * The data a repeater is drawn from in Edit and Design, resolved before the canvas renders.
+ *
+ * Edit mode draws a repeater as one instance of its row template, with the repeater's first item as
+ * that instance's sample row (`utils/edit-display.ts`). A collection is a class-backed state entry
+ * (`ContentCollection`) the canvas runtime resolves through the dev proxy AFTER its first render,
+ * so the instance connected with an empty row: a component that formats a date or a locale threw,
+ * was reported as not rendered, and drew itself only when the data arrived. Resolving the entry
+ * here, the way `page-params.ts` bakes a param-bound entry for Preview, puts the row in the state
+ * the canvas builds its scope from, so the first render is a render of the data.
+ *
+ * The same resolution serves every mode for an entry that names an enabled extension's class by a
+ * bare `$prototype` ({@link extensionClassKeys}), which the build also resolves before rendering.
+ *
+ * Only an entry whose configuration holds no template is baked: one that does is re-resolved by the
+ * runtime whenever what it reads changes, and a baked copy would freeze it. Answers are cached by
+ * the entry's configuration until the project's content changes ({@link
+ * invalidateRepeaterSources}).
+ *
+ * @docs studio/interface/canvas
+ */
+
+import { isJsonObject, isNodeObject, isRef, isString } from "@jxsuite/schema/guards";
+import { getPlatform } from "../platform";
+import type {
+  JsonObject,
+  JsonValue,
+  JxDocumentValue,
+  JxMutableNode,
+  JxStateDefinition,
+} from "@jxsuite/schema/types";
+
+/** What the backend answered for one entry, or `null` when it could not resolve it. */
+type Resolved = JsonValue | null;
+
+/** Resolved entries by their request body, so a re-render does not ask the backend again. */
+let _cache = new Map<string, Promise<Resolved>>();
+
+/** Forget every resolved entry; the next render asks the backend again. */
+export function invalidateRepeaterSources(): void {
+  _cache = new Map();
+}
+
+/** The top-level state key a `#/state/<key>/…` pointer reads, or null for any other pointer. */
+function stateKeyOf(ref: string): string | null {
+  if (!ref.startsWith("#/state/")) {
+    return null;
+  }
+  const [key] = ref.slice("#/state/".length).split("/");
+  return key ? key.replaceAll("~1", "/").replaceAll("~0", "~") : null;
+}
+
+/** Whether a configuration value holds a `${…}` template anywhere inside it. */
+function holdsTemplate(value: JsonValue | undefined): boolean {
+  if (isString(value)) {
+    return value.includes("${");
+  }
+  if (Array.isArray(value)) {
+    return value.some((member) => holdsTemplate(member));
+  }
+  return isJsonObject(value) && Object.values(value).some((member) => holdsTemplate(member));
+}
+
+/** Extension class names to their descriptor paths, as `getEffectiveImports` merges them. */
+export type ClassPaths = Readonly<Record<string, string>>;
+
+/**
+ * The `$src` a class-backed state entry resolves from: its own, else the enabled extension class
+ * its bare `$prototype` names (spec.md §12.5), else null.
+ */
+function classSourceOf(entry: JsonObject, classes: ClassPaths): string | null {
+  if (isString(entry.$src)) {
+    return entry.$src;
+  }
+  return isString(entry.$prototype) && Object.hasOwn(classes, entry.$prototype)
+    ? (classes[entry.$prototype] ?? null)
+    : null;
+}
+
+/** Whether a state entry is a class-backed source the backend can resolve once, for good. */
+function isStaticClassEntry(
+  entry: JxStateDefinition | undefined,
+  classes: ClassPaths = {},
+): entry is JsonObject {
+  return (
+    isJsonObject(entry) &&
+    isString(entry.$prototype) &&
+    classSourceOf(entry, classes) !== null &&
+    !holdsTemplate(entry)
+  );
+}
+
+/**
+ * The state keys of `doc` that name an enabled extension's class by a bare `$prototype` (a layout's
+ * `{ "$prototype": "ContentEntry", ... }`) and can be resolved once.
+ *
+ * The build resolves these before any template runs (`compiler/src/site/prototype-resolver.ts`).
+ * Left to the canvas runtime, the class's descriptor path, a file on disk, was first fetched as a
+ * URL of the canvas, answered 404, and only then asked of the dev proxy: one failed request per
+ * entry per render, on every page of a site whose layout reads its navigation this way.
+ */
+export function extensionClassKeys(doc: JxMutableNode, classes: ClassPaths): string[] {
+  return Object.entries(doc.state ?? {})
+    .filter(
+      ([, entry]) =>
+        isJsonObject(entry) && !isString(entry.$src) && isStaticClassEntry(entry, classes),
+    )
+    .map(([key]) => key);
+}
+
+/**
+ * The state keys `doc`'s repeaters read their items from, among them only the class-backed entries
+ * {@link bakeRepeaterSources} can resolve.
+ */
+export function repeaterSourceKeys(doc: JxMutableNode): string[] {
+  const keys = new Set<string>();
+  const walk = (value: JxDocumentValue | undefined): void => {
+    if (Array.isArray(value)) {
+      for (const member of value) {
+        walk(member);
+      }
+      return;
+    }
+    if (!isNodeObject(value)) {
+      return;
+    }
+    if (value.$prototype === "Array" && isRef(value.items)) {
+      const key = stateKeyOf(value.items.$ref);
+      if (key) {
+        keys.add(key);
+      }
+    }
+    walk(value.map);
+    walk(value.children);
+    for (const branch of Object.values(value.cases ?? {})) {
+      walk(branch);
+    }
+  };
+  walk(doc.children);
+  const state = doc.state ?? {};
+  return [...keys].filter((key) => isStaticClassEntry(state[key]));
+}
+
+/** Say why an entry could not be resolved, and answer that it was not. */
+function unresolved(key: string, error: Error | string): Resolved {
+  console.warn(`canvas: could not resolve state.${key} before the render:`, error);
+  return null;
+}
+
+/**
+ * `renderDoc` with each of `keys` replaced by its resolved value, or `renderDoc` itself when there
+ * is nothing to resolve. A rebuild, never a write: the render document shares its `state` with the
+ * tab's source document. An entry the backend cannot resolve is left as written, and the runtime's
+ * own resolution remains the fallback.
+ */
+export async function bakeRepeaterSources(
+  renderDoc: JxMutableNode,
+  keys: readonly string[],
+  docBase?: string,
+  classes: ClassPaths = {},
+): Promise<JxMutableNode> {
+  const platform = getPlatform();
+  const { resolveClass } = platform;
+  const source = renderDoc.state;
+  if (keys.length === 0 || !resolveClass || !source) {
+    return renderDoc;
+  }
+  const state = { ...source };
+  await Promise.all(
+    keys.map(async (key) => {
+      const entry = state[key];
+      if (!isStaticClassEntry(entry, classes)) {
+        return;
+      }
+      const body: JsonObject = { ...entry, $src: classSourceOf(entry, classes) };
+      if (docBase) {
+        body.$base = docBase;
+      }
+      const id = JSON.stringify(body);
+      let pending = _cache.get(id);
+      if (!pending) {
+        pending = resolveClass.call(platform, body).then(
+          (value): Resolved => value ?? null,
+          (error: Error | string) => {
+            _cache.delete(id);
+            return unresolved(key, error);
+          },
+        );
+        _cache.set(id, pending);
+      }
+      const value = await pending;
+      if (value !== null) {
+        /* SAFETY: the backend answers with the class's resolved JSON value (no `$prototype`), which
+           the runtime reads as a naked-value state entry, so it is a JxStateDefinition. */
+        state[key] = value as JxStateDefinition;
+      }
+    }),
+  );
+  return { ...renderDoc, state };
+}

package/src/canvas/serialize-scope.ts

@@ -12,6 +12,10 @@
  * Pure and DOM-free — no reactivity/runtime imports — so it stays trivially unit-testable.
  */
 
+import { isFunction } from "@jxsuite/schema/guards";
+import type { JsonObject, JsonValue } from "@jxsuite/schema/types";
+import type { JxScope } from "@jxsuite/runtime/types";
+
 /**
  * Per-value size cap (in JSON-string chars). A single large content collection can be tens of KB;
  * past this cap we store a small placeholder so one big data source can't bloat every render's
@@ -34,18 +38,21 @@ const LARGE_VALUE_PLACEHOLDER = "[large value omitted]";
  * @param defs The resolved `$defs` scope (may be a Vue reactive proxy).
  * @returns A plain object safe to `postMessage` (every value is JSON-round-trippable).
  */
-export function serializeDataScope(defs: Record<string, unknown>): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
+export function serializeDataScope(defs: JxScope): JsonObject {
+  const out: JsonObject = {};
   for (const key of Object.keys(defs)) {
     try {
       // Reading through the reactive proxy auto-unwraps a top-level ref/computed to its value, and
       // Can THROW (a computed getter that throws) — done inside the try so that maps the key to null
       // Rather than aborting the whole snapshot.
       const value = defs[key];
-      if (typeof value === "function") {
+      if (isFunction(value)) {
         continue; // Data sources only — a resolved server/handler fn isn't a "value".
       }
-      const json = JSON.stringify(value);
+      /* SAFETY: a widening of lib.d.ts's `string` to the real range. JSON.stringify answers
+       * undefined for a top-level undefined, a symbol, or a value whose toJSON() returns undefined
+       * (ECMA-262 SerializeJSONProperty), and the branch below depends on seeing that. */
+      const json = JSON.stringify(value) as string | undefined;
       if (json === undefined) {
         // JSON.stringify returns undefined for a bare function/symbol/undefined at the top level.
         out[key] = null;
@@ -55,7 +62,8 @@ export function serializeDataScope(defs: Record<string, unknown>): Record<string
         out[key] = LARGE_VALUE_PLACEHOLDER;
         continue;
       }
-      out[key] = JSON.parse(json) as unknown;
+      // SAFETY: `json` is JSON.stringify's own output above, so it parses back to JSON data.
+      out[key] = JSON.parse(json) as JsonValue;
     } catch {
       // A circular structure or a throwing getter → the key exists but carries no serializable value.
       out[key] = null;

package/src/canvas/stage-scrollbar.ts

@@ -32,6 +32,7 @@
  */
 
 import { PANE_SELECTOR } from "../surfaces/pane-grid";
+import { stageOf } from "./surface-registry";
 import type { CanvasSurface } from "./surface-registry";
 
 /**
@@ -61,7 +62,7 @@ export function scrollbarWidthOf(scroller: HTMLElement): number {
 
 /** The cell a stage belongs to, or the document root when it is outside every cell. */
 function cellOf(surface: CanvasSurface): HTMLElement {
-  return surface.wrap?.closest<HTMLElement>(PANE_SELECTOR) ?? document.documentElement;
+  return stageOf(surface)?.closest<HTMLElement>(PANE_SELECTOR) ?? document.documentElement;
 }
 
 /**
@@ -91,10 +92,14 @@ export function trackStageScrollbar(surface: CanvasSurface, scroller: HTMLElemen
   const write = () => {
     cell.style.setProperty(STAGE_SCROLLBAR_VAR, `${scrollbarWidthOf(scroller)}px`);
   };
+  /* No measurement here: observing an element delivers its first notification after the frame's
+     layout, so the observer's own first call is the initial write. Reading `offsetWidth` here, on a
+     stage the render has just rebuilt, forced a style recalculation of the whole document (24 ms on
+     each return to Design in the perf trace); the cell keeps the `0px` the release wrote until
+     then, which is what a stage with no scrollbar yet has. */
   const observer = new ResizeObserver(write);
   observer.observe(scroller);
   surface.stageScrollbar = { observer, scroller };
-  write();
 }
 
 /**

package/src/canvas/surface-registry.ts

@@ -101,6 +101,12 @@ export interface CanvasSurface {
    */
   prevStylebookFilter: string | null;
   prevStylebookCustomizedOnly: boolean | null;
+  /**
+   * The breakpoint this stage's catalogue was drawn at. The sheet is ONE artboard at the active
+   * breakpoint, so a size switch changes which board exists and must rebuild it, exactly as a
+   * filter change does. `undefined` is "never drawn"; `null` is the base.
+   */
+  prevStylebookMedia?: string | null | undefined;
   /** Teardown for this stage's source-mode collab binding (unbind + release the lock). */
   sourceCollabCleanup: (() => void) | null;
   /**
@@ -154,7 +160,7 @@ export function surfaceForPane(paneId: string): CanvasSurface {
 
 /** A surface record with nothing in it. One place the per-stage defaults are written down. */
 function freshSurface(paneId: string): CanvasSurface {
-  return {
+  const record: Omit<CanvasSurface, "wrap"> & { wrap: HTMLElement | null } = {
     centerObserver: null,
     monacoDiffEditor: null,
     monacoEditor: null,
@@ -171,8 +177,26 @@ function freshSurface(paneId: string): CanvasSurface {
     renderGeneration: 0,
     sourceCollabCleanup: null,
     stageScrollbar: null,
-    wrap: null as unknown as HTMLElement,
+    wrap: null,
   };
+  /* SAFETY: `wrap` is the only member that differs from CanvasSurface, and it is null only until
+   * registerCanvasSurface attaches the pane's stage. The grid registers a cell's stage as it builds
+   * the cell, before any renderer runs (§18.1 rule 1), and the paths that can run earlier read the
+   * element through stageOf(), which keeps the nullable type. */
+  return record as CanvasSurface;
+}
+
+/**
+ * The surface's stage element, or null before {@link registerCanvasSurface} attaches one.
+ *
+ * `wrap` is typed non-null for the renderers, which only run after registration. The gestures and
+ * teardowns that can reach a surface before its host exists read it through here instead.
+ *
+ * @param {CanvasSurface} surface
+ * @returns {HTMLElement | null}
+ */
+export function stageOf(surface: CanvasSurface): HTMLElement | null {
+  return surface.wrap;
 }
 
 /**
@@ -199,7 +223,7 @@ export function stageContaining(node: Node | null): CanvasSurface | null {
     return null;
   }
   for (const surface of _surfaces.values()) {
-    if (surface.wrap?.contains(node)) {
+    if (stageOf(surface)?.contains(node)) {
       return surface;
     }
   }

package/src/collab/collab-commands.ts

@@ -19,7 +19,12 @@ import { collabState } from "./collab-state";
 import { isCollabEnabled, setCollabEnabled } from "./collab-session";
 import { notify } from "../services/notify";
 import { activeTab } from "../workspace/workspace";
-import { booleanArg, booleanProperty, stringProperty } from "../commands/command-args";
+import {
+  booleanArg,
+  booleanProperty,
+  optionalStringArg,
+  stringProperty,
+} from "../commands/command-args";
 
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 import type { Tab } from "../tabs/tab";
@@ -173,7 +178,7 @@ export function collabCommands(): AnyCommand[] {
         if (!active) {
           return;
         }
-        const login = (args as { login?: string } | undefined)?.login;
+        const login = optionalStringArg("collab.follow", args, "login");
         const { peers } = collabState(active);
         const peer = login ? peers.find((p) => p.state.user.login === login) : peers[0];
         if (!peer) {