@jxsuite/studio 6.1.0 → 6.1.2

package/src/services/project-path.ts

@@ -2,15 +2,17 @@
  * Project-path.ts — the containment check the assistant's file tools run before they touch disk.
  *
  * `ai.md` §4: a file tool refuses a path outside the open project itself, rather than leaving the
- * server to. `list_files`, `read_file` and `write_file` always refused one; `create_component`
- * and `create_page` took the model's path as given and handed it to the platform write. One module,
- * so the two sets of tools cannot disagree about what "inside the project" means, and a leaf,
- * because the document tools and the project tools already import each other's neighbours.
+ * server to. `list_files`, `read_file` and `write_file` always refused one; `create_component` and
+ * `create_page` took the model's path as given and handed it to the platform write. One module, so
+ * the two sets of tools cannot disagree about what "inside the project" means, and a leaf, because
+ * the document tools and the project tools already import each other's neighbours.
  *
- * @docs studio/ai/chat
  * @license MIT
+ * @docs studio/ai/chat
  */
 
+import { isString } from "@jxsuite/schema/guards";
+import type { JsonValue } from "@jxsuite/schema/types";
 import type { ToolResult } from "@jxsuite/ai/tools";
 
 /**
@@ -18,11 +20,12 @@ import type { ToolResult } from "@jxsuite/ai/tools";
  * `..` segments, drive letters, a home directory). The server re-checks; this keeps the error
  * actionable.
  *
- * @param {unknown} path
+ * @param {JsonValue | undefined} path A tool argument as the model sent it — any JSON value, or
+ *   absent.
  * @returns {string | null}
  */
-export function normalizeRelPath(path: unknown): string | null {
-  if (typeof path !== "string" || !path.trim()) {
+export function normalizeRelPath(path: JsonValue | undefined): string | null {
+  if (!isString(path) || !path.trim()) {
     return null;
   }
   let p = path.trim().replaceAll("\\", "/");
@@ -42,10 +45,10 @@ export function normalizeRelPath(path: unknown): string | null {
  * The refusal a tool returns for a path {@link normalizeRelPath} rejected, quoting what the model
  * sent so it can see what to change.
  *
- * @param {unknown} path
+ * @param {JsonValue | undefined} path The tool argument as the model sent it.
  * @returns {ToolResult}
  */
-export function invalidPathResult(path: unknown): ToolResult {
+export function invalidPathResult(path: JsonValue | undefined): ToolResult {
   return {
     success: false,
     error: `Invalid path ${JSON.stringify(path)} — use a path relative to the project root (no leading "/", no "..").`,

package/src/services/render-critic.ts

@@ -3,10 +3,10 @@
  *
  * After a mutation passes schema validation, this module attempts a lightweight headless render
  * (buildScope → renderNode into a throwaway div) and reports render-time errors back through the
- * same { ok, error } shape that applyAndValidate consumes. The model can then self-correct
- * within the round budget instead of the user discovering a blank canvas.
+ * same { ok, error } shape that applyAndValidate consumes. The model can then self-correct within
+ * the round budget instead of the user discovering a blank canvas.
  *
- * v1 scope: catches render throws only (missing $ref, malformed Function body, bad template
+ * V1 scope: catches render throws only (missing $ref, malformed Function body, bad template
  * expressions). Does NOT detect empty/zero-node output or deep-render custom element internals
  * (connectedCallback doesn't fire on detached nodes).
  *
@@ -19,11 +19,12 @@ import type { JxDocument } from "@jxsuite/schema/types";
 /**
  * Translate a render-time error into an actionable message the model can fix.
  *
- * @param {Error} err
+ * @param {unknown} cause What the render threw — an Error in practice; anything else is printed
+ *   as-is.
  * @returns {string}
  */
-function translateRenderError(err: Error): string {
-  const msg = err.message || String(err);
+function translateRenderError(cause: unknown): string {
+  const msg = (cause instanceof Error && cause.message) || String(cause);
 
   if (msg.includes("is not defined") || msg.includes("Cannot read properties of")) {
     return `Render error: ${msg}\n  → Fix: A $ref or template expression references a name that doesn't exist in state. Check that all $ref paths and \${...} expressions match entries in the document's "state" object.`;
@@ -64,7 +65,7 @@ export async function renderCheck(
 
     return { ok: true };
   } catch (error) {
-    return { ok: false, error: translateRenderError(error as Error) };
+    return { ok: false, error: translateRenderError(error) };
   } finally {
     // Dispose all effects created synchronously by renderNode via the RUNTIME's runScoped — scope
     // Collection is per @vue/reactivity module instance, so a studio effectScope here would collect

package/src/services/settings/kernel.ts

@@ -35,13 +35,22 @@ import type { SettingsPatch } from "./write-queue";
 /** The synchronous source of truth. Absent key means unset — which is not the same as `""`. */
 const values = new Map<string, string>();
 
+/**
+ * The cache, when this realm has one. `lib.dom` declares `localStorage` unconditionally, but a
+ * realm without a DOM (Bun under test, a worker) has none — so it is looked up on every use, inside
+ * the caller's `try`, where an access that throws (storage disabled) is already handled.
+ */
+function cacheStorage(): Storage | undefined {
+  return typeof localStorage === "undefined" ? undefined : localStorage;
+}
+
 /** Mirror a value into the cache, so the next boot is correct before the backend answers. */
 function writeCache(key: string, value: string | null): void {
   try {
     if (value === null) {
-      globalThis.localStorage?.removeItem(key);
+      cacheStorage()?.removeItem(key);
     } else {
-      globalThis.localStorage?.setItem(key, value);
+      cacheStorage()?.setItem(key, value);
     }
   } catch {
     /* Storage unavailable (private mode) — the Map still serves this session. */
@@ -60,7 +69,7 @@ function writeCache(key: string, value: string | null): void {
  */
 try {
   for (const definition of ALL_SETTINGS) {
-    const cached = globalThis.localStorage?.getItem(definition.key);
+    const cached = cacheStorage()?.getItem(definition.key);
     if (cached !== null && cached !== undefined) {
       values.set(definition.key, cached);
     }
@@ -120,7 +129,7 @@ function announce(keys: readonly string[]): void {
 // ─── Writing ──────────────────────────────────────────────────────────────────
 
 const queue = createWriteQueue({
-  onError(error: unknown) {
+  onError(error) {
     notify("error", "Your settings could not be saved.", {
       detail: error instanceof Error ? error.message : String(error),
       key: "settings-write",

package/src/services/settings/write-queue.ts

@@ -2,18 +2,18 @@
  * A coalescing, serializing write queue.
  *
  * The defect it exists to make unrepresentable: saving a provider mutates three settings through
- * three setters, and each setter used to fire its own whole-map write. Three overlapping writes went
- * out against one file, each reading storage at a different moment, with no ordering between them —
- * so whichever landed last won. That was observed in the wild as a settings file holding
+ * three setters, and each setter used to fire its own whole-map write. Three overlapping writes
+ * went out against one file, each reading storage at a different moment, with no ordering between
+ * them — so whichever landed last won. That was observed in the wild as a settings file holding
  * `{"jx.ai.model": "gpt-4o"}`: the SECOND of three snapshots, landing last, a state storage itself
  * never rested in.
  *
  * Two rules, and they are different guarantees:
  *
- * 1.  **Coalesce.** Every mutation in one synchronous burst merges into a single patch, sent once
- *     the burst has finished. N setters produce one write, not N.
- * 2.  **Serialize.** At most one send is in flight. A mutation made while one is out waits for it
- *     rather than racing it, so the order the app made changes in is the order the store sees them.
+ * 1. **Coalesce.** Every mutation in one synchronous burst merges into a single patch, sent once the
+ *    burst has finished. N setters produce one write, not N.
+ * 2. **Serialize.** At most one send is in flight. A mutation made while one is out waits for it
+ *    rather than racing it, so the order the app made changes in is the order the store sees them.
  *
  * Generic over the transport so the kernel can hand it a platform call and a test can hand it an
  * array. `schedule` is injectable for the same reason.
@@ -34,7 +34,7 @@ export interface WriteQueueOptions {
   /** Deliver one merged patch. Rejection is reported through {@link WriteQueueOptions.onError}. */
   send: (patch: SettingsPatch) => Promise<void>;
   /** Called with the failure and the patch that did not land. */
-  onError?: (error: unknown, patch: SettingsPatch) => void;
+  onError?: (cause: unknown, patch: SettingsPatch) => void;
   /**
    * Defer to the end of the current burst. Defaults to `queueMicrotask`.
    *
@@ -89,7 +89,7 @@ export function createWriteQueue(opts: WriteQueueOptions): WriteQueue {
     }
     tail = tail
       .then(() => opts.send(patch))
-      .catch((error: unknown) => {
+      .catch((error) => {
         opts.onError?.(error, patch);
       });
     return tail;

package/src/services/token-lint.ts

@@ -6,7 +6,7 @@
  */
 
 import type { JxMutableNode } from "@jxsuite/schema/types";
-import { displayTagName } from "@jxsuite/schema/guards";
+import { displayTagName, isNonNullObject, isString } from "@jxsuite/schema/guards";
 
 interface TokenLintFinding {
   path: string;
@@ -25,7 +25,8 @@ interface TokenLintFinding {
 function buildTokenIndex(projectStyle: Record<string, string>) {
   const index = new Map<string, string>();
   for (const [key, value] of Object.entries(projectStyle)) {
-    if (!key.startsWith("--") || typeof value !== "string") {
+    // The style object comes from `project.json`, where a key can also hold a nested block.
+    if (!key.startsWith("--") || !isString(value)) {
       continue;
     }
     const norm = value.toLowerCase().trim();
@@ -43,7 +44,7 @@ function buildTokenIndex(projectStyle: Record<string, string>) {
  * @returns {boolean}
  */
 function isTokenRef(value: string) {
-  return typeof value === "string" && value.includes("var(--");
+  return value.includes("var(--");
 }
 
 /**
@@ -53,7 +54,7 @@ function isTokenRef(value: string) {
  * @returns {boolean}
  */
 function isTemplate(value: string) {
-  return typeof value === "string" && value.includes("${");
+  return value.includes("${");
 }
 
 /**
@@ -78,18 +79,19 @@ export function flagHardcodedTokens(
 
   const findings: TokenLintFinding[] = [];
 
-  function walk(node: unknown, pathPrefix: string) {
-    if (!node || typeof node !== "object") {
+  /* Every member is re-checked rather than trusted: callers hand over model output parsed from
+     JSON, so a "node" may be a primitive, a `style` may be a string, and a child may be anything. */
+  function walk(el: JxMutableNode, pathPrefix: string) {
+    if (!isNonNullObject(el)) {
       return;
     }
-    const el = node as JxMutableNode;
 
-    if (el.style && typeof el.style === "object") {
+    if (isNonNullObject(el.style)) {
       for (const [prop, val] of Object.entries(el.style)) {
         if (prop.startsWith("@")) {
           continue;
         }
-        if (typeof val !== "string") {
+        if (!isString(val)) {
           continue;
         }
         if (isTokenRef(val) || isTemplate(val)) {
@@ -112,7 +114,7 @@ export function flagHardcodedTokens(
     if (Array.isArray(el.children)) {
       for (let i = 0; i < el.children.length; i++) {
         const child = el.children[i];
-        if (child && typeof child === "object") {
+        if (isNonNullObject(child)) {
           walk(child, `${pathPrefix} > ${displayTagName(child.tagName) || `[${i}]`}`);
         }
       }

package/src/services/tool-executor.ts

@@ -20,7 +20,7 @@
 
 import type { createChatState } from "@jxsuite/ai/chat-state";
 import { DEFAULT_TURN_POLICY, runTurn } from "@jxsuite/ai/harness";
-import type { TurnRun } from "@jxsuite/ai/harness";
+import type { TurnInput, TurnRun } from "@jxsuite/ai/harness";
 import { toChatMessages, toOpenAITools } from "@jxsuite/ai/messages";
 import type { StreamingClient } from "@jxsuite/ai/streaming-client";
 import { createSessionFacts } from "@jxsuite/ai/tools";
@@ -36,6 +36,9 @@ import { studioTurnHooks } from "./harness/turn-hooks";
 /** What a turn that drew nothing says: the model answered with neither text nor a tool call. */
 export const EMPTY_TURN_TEXT = DEFAULT_TURN_POLICY.emptyText;
 
+/** {@link TurnInput} while this module assembles it: read-only to `runTurn`, not to its builder. */
+type TurnInputDraft = { -readonly [K in keyof TurnInput]: TurnInput[K] };
+
 interface RunAgentLoopOptions {
   chatState: ReturnType<typeof createChatState>;
   streamingClient: StreamingClient;
@@ -94,7 +97,7 @@ export async function runAgentLoop({
   let superseded = false;
   let run: TurnRun | undefined;
   try {
-    run = runTurn({
+    const input: TurnInputDraft = {
       history,
       system: [{ text: systemPrompt }],
       /* Projected from the chat store, the transcript of record. The streaming client is read on
@@ -104,13 +107,15 @@ export async function runAgentLoop({
           chatState.toMessagesArray(),
           toOpenAITools(request.tools),
           systemPrompt,
+          /* SAFETY: the one production caller, `document-assistant.ts`, always passes its turn
+             controller's signal; only tests that drive the loop directly omit it, and their stream
+             doubles record the absent signal rather than reading it — which the agent-trace
+             goldens (`signal: "none"`) pin. */
           signal as AbortSignal,
         ),
       modelInfo: { family: "openai-compat", model: chatState.model },
       tools: toolRegistry,
-      ...(signal ? { signal } : {}),
       turnId: ledger.turnId,
-      ...(placeholder ? { firstMessageId: placeholder.id } : {}),
       policy: { estimateTokens: estimatePromptTokens },
       hooks: studioTurnHooks({
         superseded: () =>
@@ -128,7 +133,14 @@ export async function runAgentLoop({
           applyHarnessEvent(chatState, event);
         }
       },
-    });
+    };
+    if (signal) {
+      input.signal = signal;
+    }
+    if (placeholder) {
+      input.firstMessageId = placeholder.id;
+    }
+    run = runTurn(input);
     await run.outcome;
   } finally {
     endBatch();

package/src/services/tool-outcomes.ts

@@ -26,23 +26,43 @@
  * @docs studio/ai/chat
  */
 
-import { isSealContent } from "@jxsuite/ai/messages";
+import { SEAL_RELOADED, isSealContent } from "@jxsuite/ai/messages";
 import type { ToolResult } from "@jxsuite/ai/tools";
+import { isBoolean, isNonNullObject, isString } from "@jxsuite/schema/guards";
 import type { PersistedMessage } from "./ai-session-store";
-import { UNANSWERED_TOOL_RESULT } from "./context-manager";
 
 /** The tool that suspends a turn on the author (services/ai-ask.ts). */
-const ASK_TOOL = "ask_user";
+export const ASK_TOOL = "ask_user";
 
-/** The outcome of an ordinary call that never ran to completion — the seal's own words. */
-const NEVER_COMPLETED = JSON.parse(UNANSWERED_TOOL_RESULT) as ToolResult;
+/**
+ * The outcome of an ordinary call that never ran to completion — the seal's own words: the object
+ * `context-manager.ts`'s `UNANSWERED_TOOL_RESULT` serializes, built from the same sentence.
+ */
+const NEVER_COMPLETED: ToolResult = { success: false, error: SEAL_RELOADED };
 
-/** A tool-call record as persisted: `id` and `name` are what pairing and the chip read. */
+/**
+ * A tool-call record as persisted: `id` and `name` are what pairing and the chip read. Every member
+ * is optional and unchecked, because the records come back out of storage; each is narrowed where
+ * it is read.
+ */
 interface PersistedToolCall {
   id?: unknown;
   name?: unknown;
   result?: unknown;
-  [key: string]: unknown;
+}
+
+/**
+ * Whether a persisted `toolCalls` entry is a record at all. Any object qualifies — every member of
+ * {@link PersistedToolCall} is optional — and a primitive (a corrupt or foreign payload) is passed
+ * through untouched by both directions.
+ */
+function isToolCallRecord(value: unknown): value is PersistedToolCall {
+  return isNonNullObject(value);
+}
+
+/** Whether a parsed tool message is a `ToolResult`: an object whose `success` is a boolean. */
+function isToolResult(value: unknown): value is ToolResult {
+  return isNonNullObject(value) && "success" in value && isBoolean(value.success);
 }
 
 /**
@@ -61,28 +81,29 @@ export function stripToolResults(messages: readonly PersistedMessage[]): Persist
     return {
       ...message,
       toolCalls: message.toolCalls.map((call) => {
-        if (!call || typeof call !== "object") {
+        if (!isToolCallRecord(call)) {
           return call;
         }
-        const { result: _result, ...rest } = call as PersistedToolCall;
+        const { result: _result, ...rest } = call;
         return rest;
       }),
     };
   });
 }
 
-/** A tool message's content as a `ToolResult`, or null when it is not one. */
-function parseToolResult(content: unknown): ToolResult | null {
-  if (typeof content !== "string") {
+/**
+ * A tool message's content as a `ToolResult`, or null when it is not one.
+ *
+ * The content is re-checked as a string although {@link PersistedMessage} declares one: the message
+ * came back out of storage, where a corrupt or foreign payload can hold anything.
+ */
+function parseToolResult(content: string): ToolResult | null {
+  if (!isString(content)) {
     return null;
   }
   try {
-    const parsed = JSON.parse(content) as unknown;
-    return parsed &&
-      typeof parsed === "object" &&
-      typeof (parsed as ToolResult).success === "boolean"
-      ? (parsed as ToolResult)
-      : null;
+    const parsed: unknown = JSON.parse(content);
+    return isToolResult(parsed) ? parsed : null;
   } catch {
     return null;
   }
@@ -114,7 +135,7 @@ export function backfillToolResults(messages: readonly PersistedMessage[]): Pers
         break;
       }
       const result = parseToolResult(reply.content);
-      if (typeof reply.toolCallId === "string" && result && !replies.has(reply.toolCallId)) {
+      if (isString(reply.toolCallId) && result && !replies.has(reply.toolCallId)) {
         replies.set(reply.toolCallId, result);
         if (isSealContent(reply.content)) {
           sealed.add(reply.toolCallId);
@@ -123,12 +144,11 @@ export function backfillToolResults(messages: readonly PersistedMessage[]): Pers
     }
     return {
       ...message,
-      toolCalls: message.toolCalls.map((call) => {
-        if (!call || typeof call !== "object") {
-          return call;
+      toolCalls: message.toolCalls.map((record) => {
+        if (!isToolCallRecord(record)) {
+          return record;
         }
-        const record = call as PersistedToolCall;
-        const id = typeof record.id === "string" ? record.id : undefined;
+        const id = isString(record.id) ? record.id : undefined;
         const answered = id === undefined ? undefined : replies.get(id);
         if (record.name === ASK_TOOL) {
           /* A question's only outcomes are an answer or none: a seal is not an answer, and a

package/src/services/trusted-types.ts

@@ -22,6 +22,20 @@
  * @docs studio/interface/problems-and-progress
  */
 
+/**
+ * A W3C `TrustedHTML`: opaque to script, accepted by an injection sink, and stringifying to the
+ * markup it wraps. This TypeScript's `lib.dom` does not declare it, so it is declared here with the
+ * one member a reader can rely on.
+ */
+export interface TrustedHtml {
+  toString: () => string;
+}
+
+/** The policy object `createPolicy` answers with, narrowed to the one factory the shell calls. */
+export interface StudioPolicy {
+  createHTML: (input: string) => TrustedHtml;
+}
+
 /** The subset of the Trusted Types API this module uses — typed here so no DOM lib is required. */
 interface TrustedTypesApi {
   createPolicy: (
@@ -31,7 +45,7 @@ interface TrustedTypesApi {
       createScript?: (input: string) => string;
       createScriptURL?: (input: string) => string;
     },
-  ) => { createHTML: (input: string) => unknown };
+  ) => StudioPolicy;
 }
 
 /** The policy name, which a CSP `trusted-types` directive would have to allow. */
@@ -75,18 +89,21 @@ export function assertSanitized(value: string): string {
 }
 
 /** Created once. A second `createPolicy` with the same name throws when policies are restricted. */
-let policy: { createHTML: (input: string) => unknown } | null = null;
+let policy: StudioPolicy | null = null;
 
 /**
  * The shell's Trusted Types policy, or null where the API does not exist.
  *
- * @returns {{ createHTML: (input: string) => unknown } | null}
+ * @returns {StudioPolicy | null}
  */
-export function studioPolicy(): { createHTML: (input: string) => unknown } | null {
+export function studioPolicy(): StudioPolicy | null {
   if (policy) {
     return policy;
   }
-  const api = (globalThis as unknown as { trustedTypes?: TrustedTypesApi }).trustedTypes;
+  /* SAFETY: `trustedTypes` is the member Trusted Types adds to the global scope, which this
+     `lib.dom` predates; the intersection only names it, typed as possibly absent, and an absent
+     member (a browser without Trusted Types, and the tests) is the `undefined` handled below. */
+  const api = (globalThis as typeof globalThis & { trustedTypes?: TrustedTypesApi }).trustedTypes;
   if (!api) {
     return null;
   }
@@ -110,9 +127,9 @@ export function studioPolicy(): { createHTML: (input: string) => unknown } | nul
  * guard that only fires under Trusted Types would be a guard that never fires in the tests.
  *
  * @param {string} value Markup from `markdownToHtml`.
- * @returns {unknown} A `TrustedHTML`, or the asserted string.
+ * @returns {TrustedHtml | string} A `TrustedHTML`, or the asserted string.
  */
-export function trustedHtml(value: string): unknown {
+export function trustedHtml(value: string): TrustedHtml | string {
   const active = studioPolicy();
   return active ? active.createHTML(value) : assertSanitized(value);
 }

package/src/settings/contexts-section.ts

@@ -76,6 +76,12 @@ export interface ContextEntry {
   kind: ContextKind;
 }
 
+/** A `$media` map, split: the base width, and every other entry classified. */
+export interface ContextSplit {
+  base: string;
+  entries: ContextEntry[];
+}
+
 /**
  * Which kind of context an entry is.
  *
@@ -98,12 +104,9 @@ export function contextKindOf(query: string): ContextKind {
  * Split a `$media` map into the base width and the three context groups.
  *
  * @param {Record<string, string> | undefined} media
- * @returns {{ base: string; entries: ContextEntry[] }}
+ * @returns {ContextSplit}
  */
-export function splitContexts(media?: Record<string, string> | undefined): {
-  base: string;
-  entries: ContextEntry[];
-} {
+export function splitContexts(media?: Record<string, string> | undefined): ContextSplit {
   const source = media ?? {};
   const entries: ContextEntry[] = [];
   for (const [key, raw] of Object.entries(source)) {
@@ -232,11 +235,11 @@ export function contextsError(container: HTMLElement): { target: string; message
  * a projection, which makes reading through to the store the thing that keeps them honest.
  */
 function currentConfig(): ProjectConfig {
-  return (projectState?.projectConfig || {}) as ProjectConfig;
+  return projectState?.projectConfig ?? {};
 }
 
 function currentMedia(): Record<string, string> {
-  return (currentConfig().$media || {}) as Record<string, string>;
+  return currentConfig().$media ?? {};
 }
 
 // ─── Writing ──────────────────────────────────────────────────────────────────
@@ -271,7 +274,7 @@ async function persistMedia(
   target: ErrorTarget,
 ): Promise<void> {
   const config = currentConfig();
-  const candidate = { ...config, $media: next } as unknown;
+  const candidate: ProjectConfig = { ...config, $media: next };
   let schemaErrors: string[] = [];
   let inherited: string[] = [];
   try {