@jxsuite/studio 6.1.1 → 8.0.0

package/src/services/popover-report.ts

@@ -23,6 +23,7 @@
 
 import { activeTab } from "../workspace/workspace";
 import { clearProblems, notify, problemFindings } from "./notify";
+import type { NotifyOptions } from "./notify";
 import {
   findPopoverDefects,
   popoverDisplayRepair,
@@ -39,7 +40,8 @@ import {
 } from "../tabs/transact";
 import { getNodeAtPath } from "../state";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
-import type { JxElement, JxMutableNode } from "@jxsuite/schema/types";
+import type { CommandArgValues } from "../commands/command-args";
+import type { JxElement } from "@jxsuite/schema/types";
 import type { JxPath } from "../state";
 import type { PopoverFix, PopoverPath } from "@jxsuite/schema/overlays";
 
@@ -100,7 +102,7 @@ export function reportPopoverProblems(doc: JxElement, path?: string): number {
   const defects = findPopoverDefects(doc, KIT_SCOPE);
   for (const defect of defects) {
     const action = defect.fix === undefined ? undefined : REPAIR_COMMAND[defect.fix];
-    notify(defect.severity, defect.message, {
+    const options: NotifyOptions = {
       detail: defect.detail,
       /* Keyed by RULE AND PATH, not by rule alone: a header with two popovers can carry the same
          defect twice, and a key that collapsed them would report one and silently drop the other.
@@ -109,32 +111,45 @@ export function reportPopoverProblems(doc: JxElement, path?: string): number {
       key: problemKey(seen, "popover", defect.rule, defect.path),
       source: POPOVER_PROBLEM_SOURCE,
       tier: "problem",
-      ...(action === undefined ? {} : { action, actionArgs: { path: defect.path } }),
-      ...(path === undefined ? {} : { path }),
-    });
+    };
+    if (action !== undefined) {
+      options.action = action;
+      options.actionArgs = { path: defect.path };
+    }
+    if (path !== undefined) {
+      options.path = path;
+    }
+    notify(defect.severity, defect.message, options);
   }
   /* The dialog and invoker-command rules (`spec.md` §8.7) file under the same source: one report
      for everything the platform overlays. They carry no repair button yet — the popover repairs
      move `display` into `:popover-open`, and a dialog's open rule is a different selector. */
   const dialogDefects = findDialogDefects(doc, KIT_SCOPE);
   for (const defect of dialogDefects) {
-    notify(defect.severity, defect.message, {
+    const options: NotifyOptions = {
       detail: defect.detail,
       key: problemKey(seen, "dialog", defect.rule, defect.path),
       source: POPOVER_PROBLEM_SOURCE,
       tier: "problem",
-      ...(path === undefined ? {} : { path }),
-    });
+    };
+    if (path !== undefined) {
+      options.path = path;
+    }
+    notify(defect.severity, defect.message, options);
   }
   return defects.length + dialogDefects.length;
 }
 
 /** Read the path argument a repair command was invoked with, or throw naming the command. */
-function repairPath(id: string, args: Record<string, unknown> | undefined): JxPath {
+function repairPath(id: string, args: CommandArgValues | undefined): JxPath {
   const path = args?.path;
   if (!Array.isArray(path)) {
     throw new RangeError(`command "${id}" needs a "path" argument naming the popover`);
   }
+  /* SAFETY: every repair record below declares `path` as an array whose items are
+     `["string", "number"]`, which `coerceArgs` reads as a path argument and checks segment by
+     segment (`pathArg`) before `run` is called — so an array that reached here holds only string
+     keys and numeric indexes. */
   return path as JxPath;
 }
 
@@ -217,7 +232,7 @@ export function popoverCommands(): AnyCommand[] {
         const id = "document.repairPopoverDisplay";
         const tab = repairTab(id);
         const path = repairPath(id, args);
-        const node = getNodeAtPath(tab.doc.document, path) as JxMutableNode | undefined;
+        const node = getNodeAtPath(tab.doc.document, path);
         const repair = popoverDisplayRepair(node?.style);
         if (!repair) {
           throw new RangeError(`command "${id}": nothing to move — this popover sets no display`);

package/src/services/preview-eval.ts

@@ -10,12 +10,15 @@
  */
 
 import { evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
+import { isNonNullObject } from "@jxsuite/schema/guards";
 import { toRaw } from "../reactivity";
 // Imported for local use AND re-exported below so existing consumers keep their import site.
 // oxlint-disable-next-line unicorn/prefer-export-from
 import { formatPreviewValue } from "../utils/preview-format";
+import type { PreviewValue } from "../utils/preview-format";
 
-import type { ExpressionNode } from "@jxsuite/runtime/expression";
+import type { JxScope } from "@jxsuite/runtime/types";
+import type { JxExpressionNode, JxExpressionOperand } from "@jxsuite/schema/types";
 
 export interface ExpressionPreview {
   /** Path-keyed display values: "" is the root node, "value/target" a nested operand, etc. */
@@ -36,14 +39,14 @@ export { formatPreviewValue };
  * (canvas not yet rendered) — the editor renders no badges rather than wrong ones.
  */
 export function previewExpression(
-  node: unknown,
-  scope?: Record<string, unknown> | null,
+  node: JxExpressionOperand | undefined,
+  scope?: JxScope | null,
 ): ExpressionPreview | null {
-  if (!scope || !node || typeof node !== "object" || !("operator" in node)) {
+  if (!scope || !isNonNullObject(node) || !("operator" in node)) {
     return null;
   }
 
-  let state: Record<string, unknown>;
+  let state: JxScope;
   try {
     // Callers hand over tab.session.canvas.scope, which the reactive session tree wraps in a
     // Proxy — structuredClone rejects proxies, so unwrap to the raw snapshot first.
@@ -54,11 +57,20 @@ export function previewExpression(
   }
 
   const values = new Map<string, string>();
-  const expr = node as ExpressionNode;
+  /* SAFETY: an operand object carrying `operator` is the expression-node member of the operand
+     union (the plain-object member is an options bag, which has no operator), and a node whose
+     other members are malformed throws inside `evaluateExpression`, which this preview reports
+     as its `error` rather than trusting. */
+  const expr = node as JxExpressionNode;
   let errorMessage: string | null = null;
   try {
-    evaluateExpression(expr, state, null, undefined, {
-      report: (path, value) => values.set(path.join("/"), formatPreviewValue(value)),
+    void evaluateExpression(expr, state, null, undefined, {
+      report: (path, value) => {
+        /* SAFETY: the trace reports raw runtime values, and PreviewValue names every category a JS
+           value falls in (primitive, bigint, symbol, function, array, record); formatting relies on
+           nothing beyond what JSON.stringify and String() accept for any value. */
+        values.set(path.join("/"), formatPreviewValue(value as PreviewValue));
+      },
     });
   } catch (error) {
     errorMessage = error instanceof Error ? error.message : String(error);

package/src/services/profile.ts

@@ -40,7 +40,7 @@ export interface StartupProfile {
  * `default` is not a no-op by omission — it is a named state, so "the app started normally" and
  * "the profile was unrecognised" are different outcomes and the second one is loud.
  */
-export const STARTUP_PROFILES: Readonly<Record<string, StartupProfile>> = {
+export const STARTUP_PROFILES = {
   default: {
     description: "Resume whatever was persisted — layout, recents, settings, chat history.",
     id: "default",
@@ -51,7 +51,10 @@ export const STARTUP_PROFILES: Readonly<Record<string, StartupProfile>> = {
     id: "fresh",
     reset: "app-state",
   },
-};
+} satisfies Readonly<Record<string, StartupProfile>>;
+
+/** {@link STARTUP_PROFILES} by id, for a lookup whose id arrives from the query string. */
+const PROFILES_BY_ID = new Map<string, StartupProfile>(Object.entries(STARTUP_PROFILES));
 
 export const DEFAULT_PROFILE_ID = "default";
 
@@ -77,7 +80,8 @@ export function isStudioStorageKey(key: string): boolean {
  * @returns The keys removed, so a caller (Preferences, a test) can report what it did.
  */
 export function clearStudioStorage(): string[] {
-  const store = globalThis.localStorage as Storage | undefined;
+  // `localStorage` is absent outside a browser realm (Bun without a DOM shim), whatever lib.dom says.
+  const store = typeof localStorage === "undefined" ? undefined : localStorage;
   if (!store) {
     return [];
   }
@@ -105,10 +109,10 @@ export function clearStudioStorage(): string[] {
  *   `default` would start the app in the state the caller was trying to avoid.
  */
 export function applyProfile(id: string): StartupProfile {
-  const profile = STARTUP_PROFILES[id];
+  const profile = PROFILES_BY_ID.get(id);
   if (!profile) {
     throw new RangeError(
-      `unknown startup profile "${id}"; declared: ${Object.keys(STARTUP_PROFILES).join(", ")}`,
+      `unknown startup profile "${id}"; declared: ${[...PROFILES_BY_ID.keys()].join(", ")}`,
     );
   }
   if (profile.reset === "app-state") {
@@ -137,7 +141,10 @@ export function applyStartupProfile(search?: string): StartupState {
   if (_startup) {
     return _startup;
   }
-  const query = new URLSearchParams(search ?? globalThis.location?.search ?? "");
+  // `location` is absent outside a browser realm, which is why the tests pass `search` themselves.
+  const query = new URLSearchParams(
+    search ?? (typeof location === "undefined" ? "" : location.search),
+  );
   const profile = applyProfile(query.get("profile") ?? DEFAULT_PROFILE_ID);
   const clockParam = query.get("clock");
   _startup = { clock: clockParam === null ? null : pinClock(clockParam), profile };

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,27 +3,36 @@
  *
  * 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).
  *
  * @license MIT
  */
 
-import { buildScope, renderNode, runScoped, setSkipServerFunctions } from "@jxsuite/runtime";
+import {
+  buildScope,
+  renderNode,
+  runScoped,
+  setResolveToken,
+  setSkipServerFunctions,
+  setTemplateErrorHandler,
+} from "@jxsuite/runtime";
 import type { JxDocument } from "@jxsuite/schema/types";
+import { hostResolveToken } from "../canvas/canvas-origin";
 
 /**
  * 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.`;
@@ -51,8 +60,17 @@ export async function renderCheck(
   doc: JxDocument,
 ): Promise<{ ok: true } | { ok: false; error: string }> {
   let stopRender: (() => void) | null = null;
+  /* A binding that throws no longer unwinds the render (spec.md §6.1) — it renders empty and waits
+     for its data — so the throw is collected here instead. The first one is the verdict: a page
+     whose template can never evaluate is exactly what this check exists to refuse. */
+  const bindingErrors: Error[] = [];
+  setTemplateErrorHandler((error) => {
+    bindingErrors.push(error);
+  });
   try {
     setSkipServerFunctions(true);
+    // The desktop dev proxy refuses a class resolve without the token the canvas carries.
+    setResolveToken(hostResolveToken());
 
     const state = await buildScope(doc, {});
 
@@ -62,10 +80,12 @@ export async function renderCheck(
     });
     stopRender = stop;
 
-    return { ok: true };
+    const [first] = bindingErrors;
+    return first ? { ok: false, error: translateRenderError(first) } : { ok: true };
   } catch (error) {
-    return { ok: false, error: translateRenderError(error as Error) };
+    return { ok: false, error: translateRenderError(error) };
   } finally {
+    setTemplateErrorHandler(null);
     // 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
     // Nothing. Effects from the async buildScope (prototype/computed setup) still escape the scope;

package/src/services/settings/definitions.ts

@@ -2,23 +2,23 @@
  * The settings registry — every application setting Studio holds, declared once.
  *
  * Before this table the answer to "which settings roam, and what is each one's default" lived in
- * four places: a `PERSISTED_SETTINGS_KEYS` array, a private `const` per key in each `*-settings.ts`,
- * a bespoke getter/setter pair beside it, and whatever the getter's `||` happened to fall back to.
- * Adding a roaming setting meant editing all four and hoping; the key strings themselves were
- * duplicated between the array and the module that owned them.
+ * four places: a `PERSISTED_SETTINGS_KEYS` array, a private `const` per key in each
+ * `*-settings.ts`, a bespoke getter/setter pair beside it, and whatever the getter's `||` happened
+ * to fall back to. Adding a roaming setting meant editing all four and hoping; the key strings
+ * themselves were duplicated between the array and the module that owned them.
  *
  * Two properties of this table are load-bearing rather than tidy:
  *
- * 1.  **Scope is declared, not inferred.** {@link USER_SETTINGS} is DERIVED from it, so a setting
- *     roams because it says `scope: "user"` — not because someone remembered to add its key to a
- *     second list. `device` is the honest name for the rest: panel geometry and a palette's MRU
- *     describe *this window*, and a user with two windows open wants them to differ.
- * 2.  **A default is not a value.** The default is what a *reader* sees when nothing is stored; it
- *     is never itself stored. `getModel()` used to mask unset as `"gpt-4o"` with `||`, a form
- *     prefilled from it, and Save wrote the mask back — which is how an install whose owner had
- *     configured an entirely different provider was left holding `jx.ai.model: "gpt-4o"` and
- *     nothing else. {@link readSetting} and {@link readStoredSetting} in `kernel.ts` are two
- *     functions for exactly this reason.
+ * 1. **Scope is declared, not inferred.** {@link USER_SETTINGS} is DERIVED from it, so a setting roams
+ *    because it says `scope: "user"` — not because someone remembered to add its key to a second
+ *    list. `device` is the honest name for the rest: panel geometry and a palette's MRU describe
+ *    _this window_, and a user with two windows open wants them to differ.
+ * 2. **A default is not a value.** The default is what a _reader_ sees when nothing is stored; it is
+ *    never itself stored. `getModel()` used to mask unset as `"gpt-4o"` with `||`, a form prefilled
+ *    from it, and Save wrote the mask back — which is how an install whose owner had configured an
+ *    entirely different provider was left holding `jx.ai.model: "gpt-4o"` and nothing else.
+ *    {@link readSetting} and {@link readStoredSetting} in `kernel.ts` are two functions for exactly
+ *    this reason.
  *
  * @license MIT
  */
@@ -144,6 +144,17 @@ export const SETTINGS = {
     normalize: trimmed,
     scope: "user",
   },
+  /**
+   * Whether the Design rail draws the developer panels — Files and Packages (`specs/studio.md`
+   * §5.1). Unset, the default, keeps them off the rail; `settings/developer-panels.ts` reads it.
+   * Roams, for the reason `showIgnoredFiles` does: it is a way of working, not a window's.
+   */
+  developerPanels: {
+    default: "",
+    key: "jx.panels.developer",
+    normalize: trimmed,
+    scope: "user",
+  },
   cfAccountId: {
     default: "",
     key: "jx.cf.accountId",

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();