@jxsuite/studio 6.1.1 → 8.0.0

package/src/recent-projects.ts

@@ -1,7 +1,7 @@
 /// <reference lib="dom" />
 import { getPlatform, hasPlatform } from "./platform";
 import { now } from "./services/clock";
-import type { RecentProjectEntry } from "./types";
+import type { RecentProjectEntry, StudioPlatform } from "./types";
 
 interface RecentFile {
   path: string;
@@ -33,9 +33,7 @@ function backend(): StudioRecentStore | null {
     return null;
   }
   const platform = getPlatform();
-  return platform.getRecentProjects && platform.saveRecentProjects
-    ? (platform as StudioRecentStore)
-    : null;
+  return isRecentStore(platform) ? platform : null;
 }
 
 interface StudioRecentStore {
@@ -43,14 +41,21 @@ interface StudioRecentStore {
   saveRecentProjects: (projects: RecentProjectEntry[]) => Promise<void>;
 }
 
+/** True when the platform implements both halves of the optional recent-projects store. */
+function isRecentStore(platform: StudioPlatform): platform is StudioPlatform & StudioRecentStore {
+  return Boolean(platform.getRecentProjects && platform.saveRecentProjects);
+}
+
 function loadFromLocalStorage(): RecentProjectEntry[] {
   try {
     const raw = localStorage.getItem(STORAGE_KEY);
     if (!raw) {
       return [];
     }
-    const parsed = JSON.parse(raw) as RecentProjectEntry[];
-    return Array.isArray(parsed) ? parsed : [];
+    const parsed: unknown = JSON.parse(raw);
+    /* SAFETY: STORAGE_KEY is written only by this module, as JSON.stringify of a
+       RecentProjectEntry[]; the Array.isArray check discards any other value found under it. */
+    return Array.isArray(parsed) ? (parsed as RecentProjectEntry[]) : [];
   } catch {
     return [];
   }
@@ -132,8 +137,10 @@ function loadRecentFiles(): RecentFile[] {
     if (!raw) {
       return [];
     }
-    const parsed = JSON.parse(raw) as RecentFile[];
-    return Array.isArray(parsed) ? parsed : [];
+    const parsed: unknown = JSON.parse(raw);
+    /* SAFETY: FILES_STORAGE_KEY is written only by trackRecentFile below, as JSON.stringify of a
+       RecentFile[]; the Array.isArray check discards any other value found under it. */
+    return Array.isArray(parsed) ? (parsed as RecentFile[]) : [];
   } catch {
     return [];
   }

package/src/resize-edges.ts

@@ -1,17 +1,27 @@
 /// <reference lib="dom" />
-const g = globalThis as unknown as {
-  __jxPlatform?: {
-    windowControls?: {
-      getFrame: () => Promise<{
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-      }>;
-      setFrame: (x: number, y: number, w: number, h: number) => void;
-    };
-  };
-};
+import { isFunction, isNonNullObject } from "@jxsuite/schema/guards";
+import type { SerializableRect } from "./canvas/iframe-protocol";
+
+/** The desktop shell's frame controls; only desktop adapters add them to the platform. */
+interface ResizeWindowControls {
+  getFrame: () => Promise<SerializableRect>;
+  setFrame: (x: number, y: number, w: number, h: number) => void;
+}
+
+/** True when `value` is a windowControls object that can at least read the window frame. */
+function isResizeWindowControls(value: unknown): value is ResizeWindowControls {
+  return isNonNullObject(value) && "getFrame" in value && isFunction(value.getFrame);
+}
+
+/** The registered platform's window controls, when it is a desktop shell that exposes them. */
+function readWindowControls(): ResizeWindowControls | undefined {
+  const platform = globalThis.__jxPlatform;
+  if (platform == null || !("windowControls" in platform)) {
+    return undefined;
+  }
+  const controls = platform.windowControls;
+  return isResizeWindowControls(controls) ? controls : undefined;
+}
 
 const EDGES = [
   "top",
@@ -30,8 +40,8 @@ const MIN_HEIGHT = 300;
 let mounted = false;
 
 export function mountResizeEdges() {
-  const wc = g.__jxPlatform?.windowControls;
-  if (!wc || !wc.getFrame || mounted) {
+  const wc = readWindowControls();
+  if (!wc || mounted) {
     return;
   }
   mounted = true;
@@ -49,27 +59,7 @@ export function mountResizeEdges() {
   document.body.append(container);
 }
 
-/**
- * @param {MouseEvent} e
- * @param {string} edge
- * @param {{
- *   getFrame: () => Promise<{ x: number; y: number; width: number; height: number }>;
- *   setFrame: (x: number, y: number, w: number, h: number) => void;
- * }} wc
- */
-async function startResize(
-  e: MouseEvent,
-  edge: string,
-  wc: {
-    getFrame: () => Promise<{
-      x: number;
-      y: number;
-      width: number;
-      height: number;
-    }>;
-    setFrame: (x: number, y: number, w: number, h: number) => void;
-  },
-) {
+async function startResize(e: MouseEvent, edge: string, wc: ResizeWindowControls) {
   e.preventDefault();
   e.stopPropagation();
 

package/src/services/a11y-report.ts

@@ -38,8 +38,10 @@
 import { activeTab } from "../workspace/workspace";
 import { clearProblems, notify, problemFindings } from "./notify";
 import { findA11yDefects } from "@jxsuite/schema/a11y";
+import { isNonNullObject, isNumber, isString } from "@jxsuite/schema/guards";
+import type { NotifyOptions } from "./notify";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
-import type { JxElement } from "@jxsuite/schema/types";
+import type { JxAttributeValue, JxElement } from "@jxsuite/schema/types";
 
 /** WCAG success criteria these checks bind to, by the id ATAG B.3.1 asks a report to carry. */
 export type A11yCriterion =
@@ -113,14 +115,14 @@ const VAGUE_LINK_TEXT = new Set([
 ]);
 
 /** The attribute bag, whatever shape the author wrote it in. */
-function attrs(node: JxElement): Record<string, unknown> {
-  return (node.attributes ?? {}) as Record<string, unknown>;
+function attrs(node: JxElement): Record<string, JxAttributeValue> {
+  return node.attributes ?? {};
 }
 
 /** An attribute's literal string value, or null when it is absent or a binding. */
 function literal(node: JxElement, name: string): string | null {
   const value = attrs(node)[name];
-  return typeof value === "string" ? value : null;
+  return isString(value) ? value : null;
 }
 
 /** Whether an attribute is present at all, however it was written. */
@@ -131,15 +133,15 @@ function has(node: JxElement, name: string): boolean {
 /** The element's own text, when it is a literal rather than a binding. */
 function ownText(node: JxElement): string {
   const parts: string[] = [];
-  if (typeof node.textContent === "string") {
+  if (isString(node.textContent)) {
     parts.push(node.textContent);
   }
   const { children } = node;
   if (Array.isArray(children)) {
     for (const child of children) {
-      if (typeof child === "string") {
+      if (isString(child)) {
         parts.push(child);
-      } else if (child && typeof child === "object") {
+      } else if (isNonNullObject(child)) {
         parts.push(ownText(child));
       }
     }
@@ -158,13 +160,13 @@ function* walk(node: JxElement): Generator<JxElement> {
   const { children } = node;
   if (Array.isArray(children)) {
     for (const child of children) {
-      if (child && typeof child === "object") {
+      if (isNonNullObject(child)) {
         yield* walk(child);
       }
     }
   }
   for (const branch of Object.values(node.cases ?? {})) {
-    if (branch && typeof branch === "object") {
+    if (isNonNullObject(branch)) {
       yield* walk(branch);
     }
   }
@@ -177,7 +179,7 @@ function hasAccessibleName(node: JxElement): boolean {
     literal(node, "aria-labelledby") !== null ||
     has(node, "aria-label") ||
     has(node, "aria-labelledby") ||
-    (typeof node.title === "string" && node.title !== "") ||
+    (isString(node.title) && node.title !== "") ||
     ownText(node) !== ""
   );
 }
@@ -197,7 +199,7 @@ export function checkDocument(doc: JxElement): A11yFinding[] {
 
   for (const node of walk(doc)) {
     index += 1;
-    const tag = typeof node.tagName === "string" ? node.tagName.toLowerCase() : "";
+    const tag = isString(node.tagName) ? node.tagName.toLowerCase() : "";
     const where = tag === "" ? `element ${index}` : `<${tag}>`;
 
     // ── 1.1.1 Non-text Content ────────────────────────────────────────────────
@@ -308,7 +310,7 @@ export function checkDocument(doc: JxElement): A11yFinding[] {
     }
 
     // ── 2.4.3 Focus Order — a positive tabindex reorders the whole page ──────
-    if (typeof node.tabIndex === "number" && node.tabIndex > 0) {
+    if (isNumber(node.tabIndex) && node.tabIndex > 0) {
       findings.push({
         criterion: "1.3.1",
         detail:
@@ -322,7 +324,7 @@ export function checkDocument(doc: JxElement): A11yFinding[] {
     }
 
     // ── 4.1.1 Parsing — a duplicate id breaks every reference to it ──────────
-    if (typeof node.id === "string" && node.id !== "") {
+    if (isString(node.id) && node.id !== "") {
       const seen = seenIds.get(node.id);
       if (seen !== undefined) {
         findings.push({
@@ -354,7 +356,7 @@ export function checkDocument(doc: JxElement): A11yFinding[] {
   }
 
   // ── 3.1.1 Language of Page ────────────────────────────────────────────────
-  if (typeof doc.lang !== "string" || doc.lang === "") {
+  if (!isString(doc.lang) || doc.lang === "") {
     findings.push({
       criterion: "3.1.1",
       detail:
@@ -370,7 +372,7 @@ export function checkDocument(doc: JxElement): A11yFinding[] {
   // The structural rules, from the engine every judge of a Jx document shares.
   for (const defect of findA11yDefects(doc)) {
     findings.push({
-      criterion: defect.criterion as A11yCriterion,
+      criterion: defect.criterion,
       detail: defect.detail,
       id: `${defect.rule}:${defect.path.join("/")}`,
       message: defect.message,
@@ -457,14 +459,19 @@ export function reportA11yProblems(doc: JxElement, path?: string): number {
   clearProblems((record) => record.source === A11Y_PROBLEM_SOURCE);
   const findings = checkDocument(doc);
   for (const finding of findings) {
-    notify(finding.severity, finding.message, {
+    const options: NotifyOptions = {
       detail: `WCAG ${finding.criterion} — ${finding.detail}`,
       key: `a11y.${finding.id}`,
       source: A11Y_PROBLEM_SOURCE,
       tier: "problem",
-      ...(finding.action === undefined ? {} : { action: finding.action }),
-      ...(path === undefined ? {} : { path }),
-    });
+    };
+    if (finding.action !== undefined) {
+      options.action = finding.action;
+    }
+    if (path !== undefined) {
+      options.path = path;
+    }
+    notify(finding.severity, finding.message, options);
   }
   /*
    * And then the honest half. A report that lists nothing reads as "this page is accessible", which

package/src/services/agent-seed.ts

@@ -10,11 +10,19 @@
  * @license MIT
  */
 
+import { isJsonObject, isNumber, isString } from "@jxsuite/schema/guards";
+import type { JsonValue } from "@jxsuite/schema/types";
+
 const PENDING_PROMPT_PREFIX = "jx.ai.pendingAgentPrompt";
 
 /** Entries older than this are considered stale and dropped on read. */
 const MAX_AGE_MS = 15 * 60 * 1000;
 
+/** `localStorage`, or `undefined` on a host that has none (a worker, a test run without a DOM). */
+function storage(): Storage | undefined {
+  return typeof localStorage === "undefined" ? undefined : localStorage;
+}
+
 function storageKey(root: string) {
   return `${PENDING_PROMPT_PREFIX}:${root}`;
 }
@@ -27,21 +35,25 @@ function storageKey(root: string) {
  */
 function readEntry(root: string): { prompt: string; ts: number } | null {
   try {
-    const raw = globalThis.localStorage?.getItem(storageKey(root));
+    const raw = storage()?.getItem(storageKey(root));
     if (!raw) {
       return null;
     }
-    const parsed = JSON.parse(raw) as { prompt?: unknown; ts?: unknown };
-    const valid =
-      typeof parsed.prompt === "string" &&
-      typeof parsed.ts === "number" &&
-      Date.now() - parsed.ts <= MAX_AGE_MS;
-    if (!valid) {
+    // SAFETY: `JSON.parse` without a reviver yields nothing but JSON values.
+    const parsed = JSON.parse(raw) as JsonValue;
+    if (parsed === null) {
+      /* A stored JSON `null` reads as "no entry" but is left in place rather than dropped as
+         malformed, matching how this reader has always treated it. */
+      return null;
+    }
+    const prompt = isJsonObject(parsed) ? parsed.prompt : undefined;
+    const ts = isJsonObject(parsed) ? parsed.ts : undefined;
+    if (!isString(prompt) || !isNumber(ts) || !(Date.now() - ts <= MAX_AGE_MS)) {
       // Stale or malformed — remove so it never seeds a later session.
-      globalThis.localStorage?.removeItem(storageKey(root));
+      storage()?.removeItem(storageKey(root));
       return null;
     }
-    return { prompt: parsed.prompt as string, ts: parsed.ts as number };
+    return { prompt, ts };
   } catch {
     return null;
   }
@@ -55,7 +67,7 @@ function readEntry(root: string): { prompt: string; ts: number } | null {
  */
 export function setPendingAgentPrompt(root: string, prompt: string): void {
   try {
-    globalThis.localStorage?.setItem(storageKey(root), JSON.stringify({ prompt, ts: Date.now() }));
+    storage()?.setItem(storageKey(root), JSON.stringify({ prompt, ts: Date.now() }));
   } catch {
     /* LocalStorage unavailable — the prompt is simply not handed off. */
   }
@@ -83,7 +95,7 @@ export function consumePendingAgentPrompt(root: string): string | null {
     return null;
   }
   try {
-    globalThis.localStorage?.removeItem(storageKey(root));
+    storage()?.removeItem(storageKey(root));
   } catch {
     /* LocalStorage unavailable — nothing to delete. */
   }

package/src/services/ai-ask.ts

@@ -12,8 +12,8 @@
  *
  * - **A skip is a SUCCESS.** "You decide" is a real answer to a question; only a stopped turn is a
  *   failure. Reporting a skip as an error would make the model apologise for having asked.
- * - **The answer never becomes a user message.** `toMessagesArray` serialises the array verbatim
- *   and a provider requires a `tool` reply to follow its `tool_calls` request; a user turn spliced
+ * - **The answer never becomes a user message.** `toMessagesArray` serialises the array verbatim and
+ *   a provider requires a `tool` reply to follow its `tool_calls` request; a user turn spliced
  *   between them is a 400. The answer travels as the tool result, and the chat view renders it into
  *   the question's own chip.
  *
@@ -24,6 +24,7 @@
  */
 
 import { createToolDefinition, toolError, toolSuccess } from "@jxsuite/ai/tools";
+import { isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 
 import type { ToolRegistry } from "@jxsuite/ai/tools";
@@ -212,17 +213,13 @@ export function registerAskTool(
         required: ["question"],
       },
       execute: async (args, ctx) => {
-        /* Everything `unknown`, and every field narrowed by `typeof` rather than by `?.`. The
-           registry's `validate()` is "a lightweight structural check, not a JSON Schema validator",
+        /* Every field is any JSON value, narrowed by a guard rather than by `?.`. The registry's
+           `validate()` is "a lightweight structural check, not a JSON Schema validator",
            `strict: false` skips it entirely, and this tool may be registered into someone else's
            registry — so an argument that is a number is a case, not an impossibility. Optional
            chaining guards null, not type: `context?.trim()` threw on one. */
-        const { question, options, context } = args as {
-          question?: unknown;
-          options?: unknown;
-          context?: unknown;
-        };
-        if (typeof question !== "string" || !question.trim()) {
+        const { question, options, context } = args;
+        if (!isString(question) || !question.trim()) {
           return toolError('Pass "question" — the question to put to the user.');
         }
         if (isAwaitingAnswer()) {
@@ -230,13 +227,13 @@ export function registerAskTool(
         }
         const choices = Array.isArray(options)
           ? options
-              .filter((o): o is string => typeof o === "string" && o.trim().length > 0)
+              .filter((o): o is string => isString(o) && o.trim().length > 0)
               .slice(0, MAX_OPTIONS)
           : [];
 
         const answering = askUser(
           {
-            context: typeof context === "string" ? context.trim() : "",
+            context: isString(context) ? context.trim() : "",
             /* The tool-call id, so the chip the transcript draws and the question this registers
                are the same thing. Without it a restored, permanently unanswered question would
                render identically to the live one. */