@jxsuite/studio 6.1.1 → 8.0.0

package/src/utils/google-fonts.ts

@@ -1,5 +1,6 @@
 /** Google Fonts helpers — shared between head-panel (per-page) and head-editor (project-level). */
 
+import { isString } from "@jxsuite/schema/guards";
 import type { JxHeadEntry } from "@jxsuite/schema/types";
 
 export const GFONTS_CSS_PREFIX = "https://fonts.googleapis.com/css2?";
@@ -11,29 +12,30 @@ export const GFONTS_PRECONNECT_ORIGINS = [
 /**
  * Check if a `$head` entry is a Google Fonts stylesheet link.
  *
- * @param {JxHeadEntry} entry
+ * @param {JxHeadEntry | null | undefined} entry A `$head` slot; a JSON array can hold `null`.
  * @returns {boolean}
  */
-export function isGoogleFontEntry(entry: JxHeadEntry) {
+export function isGoogleFontEntry(entry: JxHeadEntry | null | undefined) {
   return (
     entry?.tagName === "link" &&
-    entry?.attributes?.rel === "stylesheet" &&
-    typeof entry?.attributes?.href === "string" &&
-    (entry.attributes.href as string).startsWith(GFONTS_CSS_PREFIX)
+    entry.attributes?.rel === "stylesheet" &&
+    isString(entry.attributes.href) &&
+    entry.attributes.href.startsWith(GFONTS_CSS_PREFIX)
   );
 }
 
 /**
  * Check if a `$head` entry is a Google Fonts preconnect link.
  *
- * @param {JxHeadEntry} entry
+ * @param {JxHeadEntry | null | undefined} entry A `$head` slot; a JSON array can hold `null`.
  * @returns {boolean}
  */
-export function isGoogleFontPreconnect(entry: JxHeadEntry) {
+export function isGoogleFontPreconnect(entry: JxHeadEntry | null | undefined) {
   return (
     entry?.tagName === "link" &&
-    entry?.attributes?.rel === "preconnect" &&
-    GFONTS_PRECONNECT_ORIGINS.includes(entry?.attributes?.href as string)
+    entry.attributes?.rel === "preconnect" &&
+    isString(entry.attributes.href) &&
+    GFONTS_PRECONNECT_ORIGINS.includes(entry.attributes.href)
   );
 }
 
@@ -68,14 +70,13 @@ export function buildGoogleFontUrl(family: string) {
  */
 export function ensureGoogleFontPreconnects(head: JxHeadEntry[]) {
   for (const origin of GFONTS_PRECONNECT_ORIGINS) {
+    // A `$head` array is JSON, so a slot can hold `null` whatever the element type says.
     const exists = head.some(
-      (e: JxHeadEntry) =>
-        e?.tagName === "link" &&
-        e?.attributes?.rel === "preconnect" &&
-        e?.attributes?.href === origin,
+      (e: JxHeadEntry | null | undefined) =>
+        e?.tagName === "link" && e.attributes?.rel === "preconnect" && e.attributes.href === origin,
     );
     if (!exists) {
-      const attrs: Record<string, string | boolean> = {
+      const attrs: NonNullable<JxHeadEntry["attributes"]> = {
         href: origin,
         rel: "preconnect",
       };

package/src/utils/inherited-style.ts

@@ -13,6 +13,7 @@
  * that drops it, for callers that only want the value.
  */
 
+import { getNestedStyle, isNumber, isString } from "@jxsuite/schema/guards";
 import type { JxStyle } from "@jxsuite/schema/types";
 
 /** One inherited property: the value that shows through, and the breakpoint it was set on. */
@@ -42,30 +43,29 @@ export function computeInheritedSources(
     return {};
   }
 
-  const inherited: Record<string, InheritedSource> = {};
+  // A Map re-set keeps the key's first position, exactly as reassigning an object property does.
+  const inherited = new Map<string, InheritedSource>();
 
   /** Layer one block over the accumulator, recording `donor` for everything it contributes. */
-  const layer = (block: JxStyle, donor: string | null) => {
-    for (const [p, v] of Object.entries(block)) {
-      if (typeof v !== "object") {
-        inherited[p] = { donor, value: (v as string | number) ?? "" };
+  const layer = (block: JxStyle | undefined, donor: string | null) => {
+    for (const [p, v] of Object.entries(block ?? {})) {
+      // Declarations only: nested blocks, block lists and `$ref` objects are not inherited values.
+      if (v === undefined || isString(v) || isNumber(v)) {
+        inherited.set(p, { donor, value: v ?? "" });
       }
     }
   };
 
   if (activeSelector) {
     // Selector inheritance: base selector → each media's selector block, in cascade order.
-    layer((style[activeSelector] || {}) as JxStyle, null);
+    layer(getNestedStyle(style, activeSelector), null);
     for (const name of mediaNames) {
       if (name === activeTab) {
         break;
       }
-      layer(
-        (((style[`@${name}`] || {}) as Record<string, unknown>)[activeSelector] || {}) as JxStyle,
-        name,
-      );
+      layer(getNestedStyle(getNestedStyle(style, `@${name}`), activeSelector), name);
     }
-    return inherited;
+    return Object.fromEntries(inherited);
   }
 
   // Base flat props first, then each media block in order until the current tab.
@@ -74,9 +74,9 @@ export function computeInheritedSources(
     if (name === activeTab) {
       break;
     }
-    layer((style[`@${name}`] || {}) as JxStyle, name);
+    layer(getNestedStyle(style, `@${name}`), name);
   }
-  return inherited;
+  return Object.fromEntries(inherited);
 }
 
 /**
@@ -95,11 +95,9 @@ export function computeInheritedStyle(
   activeTab: string | null,
   activeSelector: string | null = null,
 ): Record<string, string | number> {
-  const values: Record<string, string | number> = {};
-  for (const [prop, source] of Object.entries(
-    computeInheritedSources(style, mediaNames, activeTab, activeSelector),
-  )) {
-    values[prop] = source.value;
-  }
-  return values;
+  return Object.fromEntries(
+    Object.entries(computeInheritedSources(style, mediaNames, activeTab, activeSelector)).map(
+      ([prop, source]) => [prop, source.value],
+    ),
+  );
 }

package/src/utils/link-target.ts

@@ -71,7 +71,7 @@ export function classifyHref(href = ""): LinkTarget {
  * @param value The bare value for that kind (address/number/fragment/path/href)
  */
 export function composeHref(kind: LinkKind, value: string): string {
-  const bare = (value ?? "").trim();
+  const bare = value.trim();
   if (!bare) {
     return "";
   }

package/src/utils/local-day.ts

@@ -0,0 +1,18 @@
+/**
+ * An instant as the calendar day it is where Studio runs.
+ *
+ * A file's modification time, an upload's, "today": each is an instant, and the day a reader means
+ * by it is their own. `toISOString().slice(0, 10)` answers in UTC, so a file saved at 9 pm in
+ * Denver was listed as edited tomorrow. A date the author WROTE (`2026-06-03`) is not an instant
+ * and never goes through here: it is taken as written (`content/entry-summaries.ts` `entryDay`).
+ */
+
+/** `date` as `YYYY-MM-DD` in the local time zone, or "" for an invalid date. */
+export function localDay(date: Date): string {
+  if (Number.isNaN(date.getTime())) {
+    return "";
+  }
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${String(date.getFullYear()).padStart(4, "0")}-${month}-${day}`;
+}

package/src/utils/preview-format.ts

@@ -5,17 +5,39 @@
  * strip-events pattern) so importing it never grows the iframe bundle.
  */
 
+import type { JsonPrimitive } from "@jxsuite/schema/types";
+
 const MAX_BADGE_LENGTH = 48;
 
+/**
+ * A value an expression evaluated to, as a badge has to show it: JSON from state, a bigint or
+ * symbol a helper returned, a function, and arrays and records of those. A record can be cyclic,
+ * and a bigint cannot be stringified at all, which is why formatting falls back to `String()`.
+ */
+export type PreviewValue =
+  | JsonPrimitive
+  | undefined
+  | bigint
+  | symbol
+  | ((...args: never[]) => void)
+  | PreviewValue[]
+  | PreviewRecord;
+
+/** An object an expression evaluated to, read key by key. */
+export interface PreviewRecord {
+  [key: string]: PreviewValue;
+}
+
 /** Format a runtime value as a short badge string. */
-export function formatPreviewValue(value?: unknown): string {
+export function formatPreviewValue(value?: PreviewValue): string {
   if (value === undefined) {
     return "undefined";
   }
   let text: string;
   try {
-    text =
-      typeof value === "string" ? JSON.stringify(value) : (JSON.stringify(value) ?? "undefined");
+    // SAFETY: lib.d.ts declares a string, but JSON.stringify answers undefined for a function or a symbol.
+    const json = JSON.stringify(value) as string | undefined;
+    text = json ?? "undefined";
   } catch {
     text = String(value);
   }

package/src/utils/strip-events.ts

@@ -8,44 +8,71 @@
  * editor's reactive `store.ts`; `store.ts` re-exports it for the legacy in-realm patcher.
  */
 
-import { isEventBinding } from "@jxsuite/schema/guards";
-import type { JxMutableNode } from "@jxsuite/schema/types";
+import {
+  isEventBinding,
+  isJsonObject,
+  isNodeObject,
+  isNonNullObject,
+} from "@jxsuite/schema/guards";
+import type { JxDocumentValue, JxMutableNode } from "@jxsuite/schema/types";
 
-/** Strip all `on*` event-handler properties (and server-timed state) from a document tree. */
-export function stripEventHandlers(node: JxMutableNode): JxMutableNode {
-  if (!node || typeof node !== "object") {
-    return node;
-  }
+/**
+ * A node object as a document walker rebuilds it. Every key holds a document value, including the
+ * keys {@link JxMutableNode} names, because a walker copies whatever the source document holds;
+ * `undefined` is a key an editor cleared.
+ */
+export type RebuiltNode = Record<string, JxDocumentValue | undefined>;
+
+/**
+ * Whether a walker descends into `value`: any object, arrays included. A document is JSON, so every
+ * own value of such an object is itself a document value.
+ *
+ * @param value A value read out of a document.
+ */
+export function isDocumentContainer(
+  value: JxDocumentValue | undefined,
+): value is JxDocumentValue[] | Readonly<RebuiltNode> {
+  return isNonNullObject(value);
+}
+
+/**
+ * Strip all `on*` event-handler properties (and server-timed state) from a document tree. Arrays
+ * are stripped member by member, and primitives and a cleared (`undefined`) key return unchanged,
+ * so the walk can recurse through any document value.
+ */
+export function stripEventHandlers(node: JxMutableNode): JxMutableNode;
+export function stripEventHandlers(node: JxDocumentValue): JxDocumentValue;
+export function stripEventHandlers(node: JxDocumentValue | undefined): JxDocumentValue | undefined;
+export function stripEventHandlers(node: JxDocumentValue | undefined): JxDocumentValue | undefined {
   if (Array.isArray(node)) {
     // Arrays of nodes round-trip element-wise; the array itself is not a node.
-    return node.map((n: JxMutableNode) => stripEventHandlers(n)) as unknown as JxMutableNode;
+    return node.map((n) => stripEventHandlers(n));
   }
-  const out: Record<string, unknown> = {};
+  if (!isNodeObject(node)) {
+    return node;
+  }
+  const out: RebuiltNode = {};
   for (const [k, v] of Object.entries(node)) {
     if (k.startsWith("on") && isEventBinding(v)) {
       continue;
     }
     if (k === "children") {
-      out.children = Array.isArray(v)
-        ? v.map((c: JxMutableNode) => stripEventHandlers(c))
-        : stripEventHandlers(v as JxMutableNode);
-    } else if (k === "cases" && typeof v === "object") {
-      const cases: Record<string, unknown> = {};
-      for (const [ck, cv] of Object.entries(v as Record<string, unknown>)) {
-        cases[ck] = stripEventHandlers(cv as JxMutableNode);
+      out.children = Array.isArray(v) ? v.map((c) => stripEventHandlers(c)) : stripEventHandlers(v);
+    } else if (k === "cases" && isDocumentContainer(v)) {
+      const cases: RebuiltNode = {};
+      for (const [ck, cv] of Object.entries(v)) {
+        cases[ck] = stripEventHandlers(cv);
       }
       out.cases = cases;
-    } else if (k === "state" && typeof v === "object" && v !== null) {
-      const state: Record<string, unknown> = {};
-      for (const [sk, sv] of Object.entries(v as Record<string, unknown>)) {
-        if (sv && typeof sv === "object" && (sv as Record<string, unknown>).timing === "server") {
+    } else if (k === "state" && isDocumentContainer(v)) {
+      const state: RebuiltNode = {};
+      for (const [sk, sv] of Object.entries(v)) {
+        if (isJsonObject(sv) && sv.timing === "server") {
           continue;
         }
         state[sk] = sv;
       }
       out.state = state;
-    } else if (k === "style" || k === "attributes" || k === "$media") {
-      out[k] = v;
     } else {
       out[k] = v;
     }

package/src/utils/studio-utils.ts

@@ -6,7 +6,8 @@
 
 import { collectionForFile } from "../content/collection-match";
 import { defaultContentFormat } from "../format/format-host";
-import type { ProjectConfig } from "@jxsuite/schema/types";
+import type { JsonValue, ProjectConfig } from "@jxsuite/schema/types";
+import type { CssFontPreset } from "../panels/style-utils";
 
 /**
  * Convert camelCase property name to "Title Case" label (e.g. "backgroundColor" → "Background
@@ -39,31 +40,42 @@ export function kebabToLabel(val: string) {
   );
 }
 
+/**
+ * What a css-meta or html-meta entry says about the field that edits it: its label, and the keys
+ * {@link inferInputType} picks the control from. Every other key an entry carries is ignored here.
+ */
+export interface FieldControlMeta {
+  readonly $label?: string | undefined;
+  /** `true` on a shorthand row; css-meta puts the shorthand's own name on each longhand. */
+  readonly $shorthand?: string | boolean | undefined;
+  readonly $input?: string | undefined;
+  readonly $units?: readonly string[] | undefined;
+  readonly format?: string | undefined;
+  readonly type?: string | undefined;
+  readonly enum?: readonly JsonValue[] | undefined;
+  readonly examples?: readonly JsonValue[] | undefined;
+  readonly presets?: readonly (CssFontPreset | JsonValue)[] | undefined;
+}
+
 /**
  * Get display label from metadata entry or prop name
  *
- * @param {{ $label?: string; [key: string]: unknown } | null | undefined} entry
+ * @param {FieldControlMeta | null | undefined} entry
  * @param {string} prop
  * @returns {string}
  */
-export function propLabel(
-  entry: { $label?: string; [key: string]: unknown } | null | undefined,
-  prop: string,
-) {
+export function propLabel(entry: FieldControlMeta | null | undefined, prop: string) {
   return entry?.$label || camelToLabel(prop);
 }
 
 /**
  * Label for HTML attributes — handles kebab-case (aria-label → "Aria Label")
  *
- * @param {{ $label?: string; [key: string]: unknown } | null | undefined} entry
+ * @param {FieldControlMeta | null | undefined} entry
  * @param {string} attr
  * @returns {string}
  */
-export function attrLabel(
-  entry: { $label?: string; [key: string]: unknown } | null | undefined,
-  attr: string,
-) {
+export function attrLabel(entry: FieldControlMeta | null | undefined, attr: string) {
   if (entry?.$label) {
     return entry.$label;
   }
@@ -92,17 +104,17 @@ export function attrLabel(
  * @param {unknown} format - A schema entry's `format`
  * @returns {boolean}
  */
-export function isMediaFormat(format: unknown): boolean {
+export function isMediaFormat(format: unknown): format is "image" | "uri-reference" {
   return format === "image" || format === "uri-reference";
 }
 
 /**
  * Determine input widget type from a css-meta entry
  *
- * @param {Record<string, unknown>} entry
+ * @param {FieldControlMeta} entry
  * @returns {string}
  */
-export function inferInputType(entry: Record<string, unknown>) {
+export function inferInputType(entry: FieldControlMeta) {
   if (entry.$shorthand === true) {
     return "shorthand";
   }
@@ -248,6 +260,9 @@ export function parseCemType(typeText: string | undefined | null) {
  * both required for document snapshots and clipboard payloads.
  */
 export function jsonClone<T>(value: T): T {
+  /* SAFETY: callers pass documents and clipboard payloads, which are JSON-shaped, and a JSON round
+     trip rebuilds such a value with the same structure. The only keys it loses hold undefined or a
+     function, which is the normalization this helper exists to perform. */
   // oxlint-disable-next-line unicorn/prefer-structured-clone -- structuredClone throws on reactive proxies; JSON normalization is the point
   return JSON.parse(JSON.stringify(value)) as T;
 }

package/src/view.ts

@@ -66,8 +66,8 @@ export type MonacoSurface = editor.IStandaloneCodeEditor & {
  * offsets, the source-view Monaco and the render generation were all fields of "the canvas" — a
  * singular that stopped existing when the shell grew a pane grid. They are fields of a
  * {@link import("./canvas/canvas-surface").CanvasSurface} now, one record per pane, and
- * `scripts/check-pane-singletons.ts` fails the build if one grows back: the index signature below
- * means `view.panX` is not a type error, only a silently-`unknown` read.
+ * `scripts/check-pane-singletons.ts` fails the build if one grows back, and with no index signature
+ * on this record a read of `view.panX` is a type error as well.
  */
 interface ViewState {
   /**
@@ -103,7 +103,6 @@ interface ViewState {
   layerDragSourceHeight: number;
   _completionRegistered: boolean;
   _layersCollapsed: Set<string> | null;
-  [key: string]: unknown;
 }
 
 export const view: ViewState = {

package/src/workspace/pane-derive.ts

@@ -31,12 +31,13 @@
 
 import { effect } from "../reactivity";
 import { componentRegistry } from "../files/components";
-import { getNodeAtPath, parentElementPath } from "../store";
+import { parentElementPath } from "../store";
 
 import { canvasPerf } from "../canvas/canvas-perf";
 import { canvasModeOfTab, tabOfPane } from "../canvas/canvas-surface";
 import { parseMediaEntries } from "../utils/canvas-media";
 import { getEffectiveLayoutPath, getEffectiveLocales, getEffectiveMedia } from "../site-context";
+import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
 import { localeLabel, translationPathFor } from "@jxsuite/schema/locale";
 import { shell } from "../shell";
 import {
@@ -78,10 +79,10 @@ export type DerivePreset = (typeof DERIVE_PRESETS)[number];
  * The canvas mode a preset needs the SOURCE document to DECLARE, for the presets that need one.
  *
  * `tab.capabilities.modes` is the format's own answer to "what can this document be shown as", and
- * the preset menu consulted it nowhere: over a document that declares `["settings", "stylebook",
- * "source"]` it still offered "Same page at Base" — a lens whose stage can only draw an empty
- * artboard — and "Component definition", whose rule can never resolve because nothing in a settings
- * form is a component instance. Both produced a pane the author then had to close.
+ * the preset menu consulted it nowhere: over a document that declares `["stylebook", "source"]` it
+ * still offered "Same page at Base" — a lens whose stage can only draw an empty artboard — and
+ * "Component definition", whose rule can never resolve because nothing in a configuration object is
+ * a component instance. Both produced a pane the author then had to close.
  *
  * Two presets are absent, for two different reasons. `diff` needs no mode: a comparison is two
  * texts and every document has those, and it is already gated on the file having changes. `layout`
@@ -97,14 +98,14 @@ export type DerivePreset = (typeof DERIVE_PRESETS)[number];
  * pinned by a test (`per-preset refusals` · "Layout's gate is the layout RESOLVING") instead of
  * being asserted here in prose.
  */
-const MODE_FOR_PRESET: Readonly<Partial<Record<DerivePreset, string>>> = {
+const MODE_FOR_PRESET: Readonly<Partial<Record<DerivePreset, keyof typeof MODE_WORDS>>> = {
   breakpoint: "design",
   code: "source",
   component: "design",
 };
 
 /** How a mode is spelled in a refusal — the words on the Editor axis, not the internal ids. */
-const MODE_WORDS: Readonly<Record<string, string>> = { design: "Design", source: "Code" };
+const MODE_WORDS = { design: "Design", source: "Code" } as const;
 
 /** Said by a diff lens whose comparison came back empty. One sentence, one home. */
 const DIFF_UNREADABLE = "Could not read this file's comparison against HEAD.";
@@ -399,9 +400,7 @@ function companionTarget(
        hit is transient — `iframe-host.ts` clears it the moment the author clicks page content —
        so the page's own layout remains the answer for a derivation created from the preset menu. */
     const hit = shell.layoutSelection;
-    const path =
-      hit?.layoutFile ??
-      getEffectiveLayoutPath(source.doc.document.$layout as string | false | undefined);
+    const path = hit?.layoutFile ?? getEffectiveLayoutPath(source.doc.document.$layout);
     return path === null
       ? {
           ...base,
@@ -421,7 +420,7 @@ function companionTarget(
              was a condition with no false branch, and an unreachable branch is a claim nobody can
              check. What stops a node path from layout A landing inside layout B is
              {@link selectInPane}, which compares against the document actually on screen. */
-          select: hit ? (hit.layoutPath as JxPath) : null,
+          select: hit ? hit.layoutPath : null,
           status: "ready",
         };
   }
@@ -534,7 +533,7 @@ export function componentPathUnderSelection(tab: Tab | null): string | null {
     if (entry?.path) {
       return entry.path;
     }
-    path = parentElementPath(path) as JxPath | null;
+    path = parentElementPath(path);
   }
   return null;
 }
@@ -758,7 +757,7 @@ function loadDiffFor(paneId: string, target: DerivedTarget, deps: DerivationDeps
          cannot re-enter, because neither of those answers carries a `diffPath`. */
       applyDerivation(paneId, deps);
     })
-    .catch((error: unknown) => {
+    .catch((error) => {
       console.error("loadDiff error:", error);
     });
 }
@@ -808,7 +807,7 @@ function probeTranslationFor(paneId: string, target: DerivedTarget, deps: Deriva
          them carries a `probePath`, so this cannot re-enter. */
       applyDerivation(paneId, deps);
     })
-    .catch((error: unknown) => {
+    .catch((error) => {
       console.error("fileExists error:", error);
     });
 }
@@ -1016,8 +1015,7 @@ export function presetRefusal(
        which `paneIsEmpty` will not collapse, whose strip drew nothing and whose stage drew nothing.
        `component` is deliberately NOT refused the same way — "select an element inside a component"
        is a rule that resolves on the next click, which is the whole point of leaving it open. */
-    return getEffectiveLayoutPath(source.doc.document.$layout as string | false | undefined) ===
-      null
+    return getEffectiveLayoutPath(source.doc.document.$layout) === null
       ? "a page with a layout — this one declares none"
       : null;
   }