@jxsuite/studio 6.1.0 → 6.1.2

package/src/services/directory-picker.ts

@@ -32,6 +32,7 @@
  */
 
 import { LOCATION_ID_FILE } from "@jxsuite/protocol/routes";
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { errorMessage } from "@jxsuite/schema/parse";
 
 /** Re-exported so a caller wiring up `locate` need not also reach into the protocol package. */
@@ -57,11 +58,20 @@ type ShowDirectoryPicker = (opts?: {
   startIn?: string;
 }) => Promise<DirectoryHandle>;
 
+/** A realm that exposes the File System Access API's folder chooser. */
+type DirectoryPickerRealm = typeof globalThis & { showDirectoryPicker: ShowDirectoryPicker };
+
+/**
+ * Whether a realm carries `showDirectoryPicker`. The DOM lib this package compiles against does not
+ * declare it (the API is Chromium-only), so the global is probed rather than read.
+ */
+function hasDirectoryPicker(realm: typeof globalThis): realm is DirectoryPickerRealm {
+  return "showDirectoryPicker" in realm && typeof realm.showDirectoryPicker === "function";
+}
+
 /** Whether this browser can open a native folder chooser at all. */
 export function canPickDirectory(): boolean {
-  return (
-    typeof (globalThis as { showDirectoryPicker?: unknown }).showDirectoryPicker === "function"
-  );
+  return hasDirectoryPicker(globalThis);
 }
 
 /** A location id: URL-safe, unguessable enough that a concurrent pick cannot collide. */
@@ -76,13 +86,8 @@ function newLocationId(): string {
  * `showDirectoryPicker`, a test double) is not `instanceof Error` here, but it still says what it
  * is.
  */
-function nameOf(error: unknown): string {
-  return typeof error === "object" &&
-    error !== null &&
-    "name" in error &&
-    typeof error.name === "string"
-    ? error.name
-    : "";
+function nameOf(cause: unknown): string {
+  return isNonNullObject(cause) && "name" in cause && isString(cause.name) ? cause.name : "";
 }
 
 /**
@@ -111,12 +116,13 @@ function nameOf(error: unknown): string {
 export async function pickDirectoryPath(
   locate: (query: { name: string; id: string }) => Promise<string | null>,
 ): Promise<string | null> {
-  const show = (globalThis as { showDirectoryPicker?: ShowDirectoryPicker }).showDirectoryPicker;
-  if (typeof show !== "function") {
+  const realm = globalThis;
+  if (!hasDirectoryPicker(realm)) {
     throw new TypeError(
       "This browser has no folder chooser. Type the folder's path into Location instead.",
     );
   }
+  const show = realm.showDirectoryPicker;
 
   let handle: DirectoryHandle;
   try {

package/src/services/document-assistant.ts

@@ -42,6 +42,7 @@ import { getBaseUrl, getOpenAiKey } from "./ai-settings";
 import { preferredModel } from "./ai-models";
 import { pruneOrphanToolMessages, trimContext } from "./context-manager";
 import { renderCheck } from "./render-critic";
+import type { CandidateDocument, RenderVerdict } from "./ai-write-report";
 import { validateDoc } from "./jx-validate";
 import { reloadFileInTab } from "../files/files";
 import { getExtensionCatalog, refreshExtensionUi } from "../format/format-host";
@@ -59,6 +60,20 @@ function projectRoot() {
   return workspace.projectRoot || "";
 }
 
+/**
+ * The open project's configuration.
+ *
+ * @returns {ProjectConfig | null}
+ */
+function projectConfig(): ProjectConfig | null {
+  return workspace.projectConfig;
+}
+
+/* SAFETY: renderCheck runs the whole render inside a try and answers `{ ok: false, error }` for
+   anything it cannot render, so JSON that is not (yet) a valid document is exactly what it is safe
+   to hand; its JxDocument parameter names what renders, not what may be probed. */
+const probeRender = renderCheck as (doc: CandidateDocument) => Promise<RenderVerdict>;
+
 /**
  * Create a document-assistant session bound to the currently active tab.
  *
@@ -82,8 +97,10 @@ export function createDocumentAssistant() {
      `ctx.session`. New Chat starts over; a new session id keeps what the conversation knew. */
   let sessionFacts = createSessionFacts();
 
-  const getProjectStyle = () =>
-    (workspace.projectConfig as ProjectConfig | null)?.style as Record<string, string> | undefined;
+  /* SAFETY: the token tools read only the top-level `--*` keys of the project style block, and skip
+     any whose value is not a string, so the nested rule blocks a JxStyle may also hold are never
+     read as tokens. */
+  const getProjectStyle = () => projectConfig()?.style as Record<string, string> | undefined;
 
   const findOpenTab = (path: string): Tab | null => {
     for (const tab of workspace.tabs.values()) {
@@ -106,9 +123,7 @@ export function createDocumentAssistant() {
       const plat = getPlatform();
       await plat.writeFile(relPath, content);
     },
-    renderCheck: renderCheck as (
-      doc: unknown,
-    ) => Promise<{ ok: true } | { ok: false; error: string }>,
+    renderCheck: probeRender,
     getProjectStyle,
     findOpenTab,
     reloadTab: reloadFileInTab,
@@ -126,9 +141,7 @@ export function createDocumentAssistant() {
   });
   registerProjectTools(innerRegistry, {
     getTab: () => activeTab.value,
-    renderCheck: renderCheck as (
-      doc: unknown,
-    ) => Promise<{ ok: true } | { ok: false; error: string }>,
+    renderCheck: probeRender,
     getProjectStyle,
     findOpenTab,
     reloadTab: reloadFileInTab,
@@ -221,9 +234,7 @@ export function createDocumentAssistant() {
   const commandTools = createCommandToolRegistry({
     getProjectStyle,
     getTab: () => activeTab.value,
-    renderCheck: renderCheck as (
-      doc: unknown,
-    ) => Promise<{ ok: true } | { ok: false; error: string }>,
+    renderCheck: probeRender,
     validate: validateDoc,
   });
   const toolRegistry = composeToolRegistries(
@@ -263,16 +274,21 @@ export function createDocumentAssistant() {
        be two answers to "what can this project turn on". */
     const catalog: ExtensionCatalogSummary[] = [];
     for (const entry of getExtensionCatalog()) {
-      catalog.push({
+      const summary: ExtensionCatalogSummary = {
         name: entry.name,
         sections: entry.sections.map((section) => section.key),
-        ...(entry.title === undefined ? {} : { title: entry.title }),
-        ...(entry.description === undefined ? {} : { description: entry.description }),
-      });
+      };
+      if (entry.title !== undefined) {
+        summary.title = entry.title;
+      }
+      if (entry.description !== undefined) {
+        summary.description = entry.description;
+      }
+      catalog.push(summary);
     }
     return buildSystemPrompt({
       document: tab ? toRaw(tab.doc.document) : undefined,
-      projectConfig: (workspace.projectConfig as ProjectConfig | null) || undefined,
+      projectConfig: projectConfig() || undefined,
       components: componentRegistry.length > 0 ? componentRegistry : undefined,
       projectRoot: workspace.projectRoot || undefined,
       hasProject: Boolean(workspace.projectRoot),
@@ -285,8 +301,9 @@ export function createDocumentAssistant() {
       /* Read per turn from the live registry — a projected tool the gate will honour this round is
          listed this round, and one it will not is not. */
       commandTools: commandToolBlurbs(activeRegistry()),
-      ...(inventory && inventory.length > 0 ? { fileInventory: inventory } : {}),
-      ...(catalog.length > 0 ? { extensionCatalog: catalog } : {}),
+      // Absent and undefined read the same: every option is destructured without a default.
+      fileInventory: inventory && inventory.length > 0 ? inventory : undefined,
+      extensionCatalog: catalog.length > 0 ? catalog : undefined,
     });
   }
 
@@ -347,7 +364,7 @@ export function createDocumentAssistant() {
         baseUrl: getBaseUrl() || undefined,
         /* The persisted conversation, so the backend can keep its rounds on one warm prompt cache.
            Sent to the backend only, which hashes it before any provider sees it (specs/ai.md §2.5). */
-        sessionId: sessionId ?? undefined,
+        sessionId,
       });
 
       if (sessionFacts.sessionId !== sessionId) {
@@ -480,6 +497,9 @@ export function createDocumentAssistant() {
    */
   function pushRestoredMessages(msgs: sessionStore.PersistedMessage[]) {
     for (const m of backfillToolResults(msgs)) {
+      /* SAFETY: every persisted message was written by persistChat from a live message (its role,
+         tool calls and timestamp included) and its call results were restored by
+         backfillToolResults above; only the id a legacy entry may lack is synthesized here. */
       chatState.messages.push({
         ...m,
         id: m.id || `restored_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`,

package/src/services/gated-registry.ts

@@ -13,7 +13,7 @@
  * @license MIT
  */
 
-import type { ToolContext, ToolDefinition, ToolRegistry } from "@jxsuite/ai/tools";
+import type { ToolArguments, ToolContext, ToolDefinition, ToolRegistry } from "@jxsuite/ai/tools";
 
 export interface ToolAvailability {
   /** Whether the tool is currently advertised/executable. */
@@ -48,17 +48,21 @@ export function createGatedToolRegistry(
     },
     listForLLM() {
       const available = new Set(this.list().map((t) => t.name));
-      return inner
-        .listForLLM()
-        .filter((t) => available.has((t as { function?: { name?: string } }).function?.name ?? ""));
+      return inner.listForLLM().filter((t) => {
+        /* SAFETY: a @jxsuite/ai registry lists each tool in OpenAI function-calling form,
+           `{ type: "function", function: { name, … } }`; the registry interface types the entries
+           as bare objects, and the optional chain still answers "" for any other shape. */
+        const tool = t as { function?: { name?: string } };
+        return available.has(tool.function?.name ?? "");
+      });
     },
     getDefinition(toolName: string) {
       return inner.getDefinition(toolName);
     },
-    validate(toolName: string, args: object) {
+    validate(toolName: string, args: ToolArguments) {
       return inner.validate(toolName, args);
     },
-    async execute(toolName: string, args: object, ctx?: ToolContext) {
+    async execute(toolName: string, args: ToolArguments, ctx?: ToolContext) {
       if (inner.getDefinition(toolName) && !isAvailable(toolName)) {
         const gate = availability.get(toolName);
         return {

package/src/services/harness/chat-reducer.ts

@@ -11,11 +11,30 @@
 
 import type { createChatState } from "@jxsuite/ai/chat-state";
 import type { HarnessEvent, TurnOutcome } from "@jxsuite/ai/harness";
+import { isJsonObject, isNumber, isString } from "@jxsuite/schema/guards";
 import type { ImportProgressEvent } from "../../types";
 import { recordImportProgress } from "../import-run";
 
 type ChatStore = ReturnType<typeof createChatState>;
 
+/**
+ * Whether a tool's progress payload is an import progress line. The engine carries progress as
+ * opaque JSON; only the import tool reports any, and only in this shape. Exported so the test
+ * harness's tool context records exactly what this reducer records.
+ */
+export function isImportProgressEvent(value: unknown): value is ImportProgressEvent {
+  if (!isJsonObject(value)) {
+    return false;
+  }
+  const { phase, message, current, total } = value;
+  return (
+    isString(phase) &&
+    isString(message) &&
+    (current === undefined || isNumber(current)) &&
+    (total === undefined || isNumber(total))
+  );
+}
+
 /** How a turn's end reads in the transcript: the cap message, an error row, or nothing more. */
 function applyOutcome(chat: ChatStore, outcome: TurnOutcome): void {
   switch (outcome.kind) {
@@ -96,7 +115,10 @@ export function applyHarnessEvent(chat: ChatStore, event: HarnessEvent): void {
       break;
     }
     case "tool_progress": {
-      recordImportProgress(event.callId, event.progress as unknown as ImportProgressEvent);
+      // A call that is not an import run has no record to update either way.
+      if (isImportProgressEvent(event.progress)) {
+        recordImportProgress(event.callId, event.progress);
+      }
       break;
     }
     case "tool_result": {

package/src/services/import-client.ts

@@ -18,6 +18,7 @@ import type {
   ImportSiteOptions,
   ImportSiteSummary,
 } from "../types";
+import { isJsonObject } from "@jxsuite/schema/guards";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 
 /**
@@ -29,6 +30,34 @@ import type { ProjectConfig } from "@jxsuite/schema/types";
  */
 export const IMPORT_WARNING_PHASE = "warning";
 
+/** The request headers: JSON, plus the caller's AI credentials when it has them. */
+interface ImportRequestHeaders {
+  "Content-Type": string;
+  "X-Api-Key"?: string;
+  "X-Api-Base-URL"?: string;
+}
+
+/** The JSON body the import-site route reads; `model` travels as `aiModel`. */
+interface ImportRequestBody {
+  url: string;
+  directory: string;
+  depth: number;
+  maxPages: number;
+  aiComponents: boolean;
+  breakpoints?: ImportSiteOptions["breakpoints"];
+  aiModel?: ImportSiteOptions["model"];
+  verify?: boolean;
+  verifyThreshold?: number;
+  verifyMinFidelity?: number;
+}
+
+/** What a `done` line settles the stream with. */
+export interface ImportStreamResult {
+  root: string;
+  config: ProjectConfig;
+  result?: ImportSiteSummary;
+}
+
 interface StreamLine {
   type: string;
   phase?: string;
@@ -58,8 +87,8 @@ export async function streamImport(
   onProgress: (evt: ImportProgressEvent) => void,
   signal?: AbortSignal,
   onReady?: (evt: ImportReadyEvent) => void,
-): Promise<{ root: string; config: ProjectConfig; result?: ImportSiteSummary }> {
-  const headers: Record<string, string> = { "Content-Type": "application/json" };
+): Promise<ImportStreamResult> {
+  const headers: ImportRequestHeaders = { "Content-Type": "application/json" };
   if (opts.apiKey) {
     headers["X-Api-Key"] = opts.apiKey;
   }
@@ -67,32 +96,46 @@ export async function streamImport(
     headers["X-Api-Base-URL"] = opts.baseUrl;
   }
 
-  const res = await fetch(endpoint, {
-    body: JSON.stringify({
-      url: opts.url,
-      directory: opts.directory,
-      depth: opts.depth,
-      maxPages: opts.maxPages,
-      aiComponents: opts.aiComponents,
-      ...(opts.breakpoints === undefined ? {} : { breakpoints: opts.breakpoints }),
-      ...(opts.model === undefined ? {} : { aiModel: opts.model }),
-      ...(opts.verify === undefined ? {} : { verify: opts.verify }),
-      ...(opts.verifyThreshold === undefined ? {} : { verifyThreshold: opts.verifyThreshold }),
-      ...(opts.verifyMinFidelity === undefined
-        ? {}
-        : { verifyMinFidelity: opts.verifyMinFidelity }),
-    }),
-    headers,
+  const request: ImportRequestBody = {
+    url: opts.url,
+    directory: opts.directory,
+    depth: opts.depth,
+    maxPages: opts.maxPages,
+    aiComponents: opts.aiComponents,
+  };
+  if (opts.breakpoints !== undefined) {
+    request.breakpoints = opts.breakpoints;
+  }
+  if (opts.model !== undefined) {
+    request.aiModel = opts.model;
+  }
+  if (opts.verify !== undefined) {
+    request.verify = opts.verify;
+  }
+  if (opts.verifyThreshold !== undefined) {
+    request.verifyThreshold = opts.verifyThreshold;
+  }
+  if (opts.verifyMinFidelity !== undefined) {
+    request.verifyMinFidelity = opts.verifyMinFidelity;
+  }
+  // The spread is a plain record copy: an interface is not assignable to the `HeadersInit` record.
+  const init: RequestInit = {
+    body: JSON.stringify(request),
+    headers: { ...headers },
     method: "POST",
-    ...(signal === undefined ? {} : { signal }),
-  });
+  };
+  if (signal !== undefined) {
+    init.signal = signal;
+  }
+  const res = await fetch(endpoint, init);
 
   if (!res.ok) {
     let message = `Import failed (${res.status})`;
     try {
-      const body = (await res.json()) as { error?: string };
-      if (body.error) {
-        message = body.error;
+      const body: unknown = await res.json();
+      // `new Error()` stringifies a non-string message, so String() keeps any `error` value's text.
+      if (isJsonObject(body) && body.error) {
+        message = String(body.error);
       }
     } catch {
       /* Non-JSON error body — keep the status message. */
@@ -106,7 +149,7 @@ export async function streamImport(
   const reader = res.body.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
-  let result: { root: string; config: ProjectConfig; result?: ImportSiteSummary } | null = null;
+  let result: ImportStreamResult | null = null;
   /*
    * Lines the parser could not read. Tolerating one is right — an import that ran for two minutes
    * should not die on a garbled progress line — but doing it *silently* is not: the import then
@@ -115,37 +158,47 @@ export async function streamImport(
    */
   let unreadable = 0;
 
-  const handleLine = (line: string) => {
+  /** Apply one line; a `done` line's result is returned for the read loop to keep. */
+  const handleLine = (line: string): ImportStreamResult | undefined => {
     const trimmed = line.trim();
     if (!trimmed) {
-      return;
+      return undefined;
     }
     let parsed: StreamLine;
     try {
+      /* SAFETY: the import-site route writes every line as JSON.stringify of one stream line
+         object with a string `type`, and every other member is optional; each branch below
+         compares `type` to a literal and checks the members it reads before using them. */
       parsed = JSON.parse(trimmed) as StreamLine;
     } catch {
       unreadable += 1;
-      return; // Tolerate a mangled line rather than killing the whole import.
+      return undefined; // Tolerate a mangled line rather than killing the whole import.
     }
     if (parsed.type === "progress") {
-      onProgress({
+      const progress: ImportProgressEvent = {
         phase: parsed.phase ?? "",
         message: parsed.message ?? "",
-        ...(parsed.current === undefined ? {} : { current: parsed.current }),
-        ...(parsed.total === undefined ? {} : { total: parsed.total }),
-      });
+      };
+      if (parsed.current !== undefined) {
+        progress.current = parsed.current;
+      }
+      if (parsed.total !== undefined) {
+        progress.total = parsed.total;
+      }
+      onProgress(progress);
     } else if (parsed.type === "ready" && parsed.root !== undefined) {
       onReady?.({ root: parsed.root });
     } else if (parsed.type === "done" && parsed.root !== undefined && parsed.config) {
-      result = {
-        root: parsed.root,
-        config: parsed.config,
-        ...(parsed.result === undefined ? {} : { result: parsed.result }),
-      };
+      const settled: ImportStreamResult = { root: parsed.root, config: parsed.config };
+      if (parsed.result !== undefined) {
+        settled.result = parsed.result;
+      }
+      return settled;
     } else if (parsed.type === "error") {
       throw new Error(parsed.error || "Import failed");
     }
     // Heartbeats and unknown line types are ignored.
+    return undefined;
   };
 
   try {
@@ -159,10 +212,10 @@ export async function streamImport(
       const lines = buffer.split("\n");
       buffer = lines.pop() ?? "";
       for (const line of lines) {
-        handleLine(line);
+        result = handleLine(line) ?? result;
       }
     }
-    handleLine(buffer);
+    result = handleLine(buffer) ?? result;
   } finally {
     try {
       await reader.cancel();

package/src/services/import-seed.ts

@@ -5,8 +5,8 @@
  * the turn and runs the import as a tool call. This holds what the form gathered for the one turn
  * that consumes it.
  *
- * **Module state, and deliberately NOT a copy of `agent-seed.ts`.** That one uses localStorage keyed
- * by project root because the project it seeds opens in a NEW WINDOW, and the key is the
+ * **Module state, and deliberately NOT a copy of `agent-seed.ts`.** That one uses localStorage
+ * keyed by project root because the project it seeds opens in a NEW WINDOW, and the key is the
  * cross-window channel. Neither half of that applies here: the project does not exist yet at
  * hand-off time, so there is no root to key on, and the assistant taking the turn is in this window
  * — `import_site` is `no-project` tiered precisely because it runs before there is a project. A
@@ -18,6 +18,12 @@
 
 import type { ImportBreakpointPolicy } from "../types";
 
+/**
+ * The deepest crawl the import pipeline accepts: the bound `packages/server/src/import-api.ts`
+ * clamps to, which both the wizard's depth field and `import_site` honour.
+ */
+export const MAX_IMPORT_DEPTH = 5;
+
 /** What the wizard gathered, as the tool needs it. */
 export interface ImportBrief {
   /** Absolute http(s) URL of the site to clone. */

package/src/services/jx-validate.ts

@@ -19,21 +19,21 @@
 
 import coreDocumentSchema from "@jxsuite/schema/schema.json";
 import coreProjectSchema from "@jxsuite/schema/project-schema.json";
-
-type ValidateFn = ((doc: unknown) => boolean) & {
-  errors?: { instancePath?: string; message?: string; params?: Record<string, unknown> }[] | null;
-};
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
+import type { JsonObject, JsonValue, ProjectConfig } from "@jxsuite/schema/types";
+import type { ValidateFunction } from "ajv/dist/2020.js";
+import type { CandidateDocument } from "./ai-write-report";
 
 /** Which of the two entry documents a validator covers. */
 type SchemaKind = "document" | "project";
 
-const CORE: Record<SchemaKind, object> = {
-  document: coreDocumentSchema as object,
-  project: coreProjectSchema as object,
+const CORE: Record<SchemaKind, JsonObject> = {
+  document: coreDocumentSchema,
+  project: coreProjectSchema,
 };
 
-const active: Record<SchemaKind, object> = { ...CORE };
-const compiling: Record<SchemaKind, Promise<ValidateFn | null> | null> = {
+const active: Record<SchemaKind, JsonObject> = { ...CORE };
+const compiling: Record<SchemaKind, Promise<ValidateFunction | null> | null> = {
   document: null,
   project: null,
 };
@@ -49,9 +49,9 @@ let reportedFailure = false;
  * unavailable or the schema will not compile.
  *
  * @param {SchemaKind} kind - Which entry document to compile
- * @returns {Promise<ValidateFn | null>} The compiled validator, or null when unavailable
+ * @returns {Promise<ValidateFunction | null>} The compiled validator, or null when unavailable
  */
-function getValidator(kind: SchemaKind): Promise<ValidateFn | null> {
+function getValidator(kind: SchemaKind): Promise<ValidateFunction | null> {
   compiling[kind] ??= (async () => {
     try {
       // The generated schemas are JSON Schema draft 2020-12, so they need Ajv's 2020 build —
@@ -62,7 +62,7 @@ function getValidator(kind: SchemaKind): Promise<ValidateFn | null> {
       const { default: addFormats } = await import("ajv-formats");
       const ajv = new Ajv2020({ allErrors: true, strict: false, allowUnionTypes: true });
       addFormats(ajv);
-      return ajv.compile(active[kind]) as ValidateFn;
+      return ajv.compile(active[kind]);
     } catch (error) {
       if (!reportedFailure) {
         reportedFailure = true;
@@ -78,14 +78,9 @@ function getValidator(kind: SchemaKind): Promise<ValidateFn | null> {
   return compiling[kind];
 }
 
-/** A payload half that is usable as a JSON Schema — a non-empty, non-array object. */
-function asSchema(value: unknown): object | undefined {
-  return typeof value === "object" &&
-    value !== null &&
-    !Array.isArray(value) &&
-    Object.keys(value).length > 0
-    ? (value as object)
-    : undefined;
+/** Whether a payload half is usable as a JSON Schema — a non-empty, non-array object. */
+function isSchemaObject(value: unknown): value is JsonObject {
+  return isJsonObject(value) && Object.keys(value).length > 0;
 }
 
 /**
@@ -107,8 +102,10 @@ export function applyProjectSchemas(
    * an error envelope under `document` would not fail loudly — it would install a validator that
    * calls every document valid, and every consumer would go on trusting it.
    */
-  const document = asSchema(schemas?.document) ?? CORE.document;
-  const project = asSchema(schemas?.project) ?? CORE.project;
+  const documentHalf = schemas?.document;
+  const projectHalf = schemas?.project;
+  const document = isSchemaObject(documentHalf) ? documentHalf : CORE.document;
+  const project = isSchemaObject(projectHalf) ? projectHalf : CORE.project;
   const applied = document !== CORE.document || project !== CORE.project;
   if (document === active.document && project === active.project) {
     return applied;
@@ -140,13 +137,13 @@ const ERROR_PROPERTY_KEYS = ["unevaluatedProperty", "additionalProperty", "missi
  * Format ajv errors the way the agent loop consumes them (see ai-tools.ts
  * `translateValidationError`).
  *
- * @param {ValidateFn} validate - The validator that just ran
+ * @param {ValidateFunction} validate - The validator that just ran
  * @returns {string[]} One formatted string per error
  */
-function formatErrors(validate: ValidateFn): string[] {
+function formatErrors(validate: ValidateFunction): string[] {
   return (validate.errors || []).map((e) => {
-    const key = ERROR_PROPERTY_KEYS.find((name) => typeof e.params?.[name] === "string");
-    const property = key ? ` (${String(e.params?.[key])})` : "";
+    const key = ERROR_PROPERTY_KEYS.find((name) => isString(e.params[name]));
+    const property = key ? ` (${String(e.params[key])})` : "";
     return `${e.instancePath || "(root)"}: ${e.message}${property}`;
   });
 }
@@ -154,10 +151,10 @@ function formatErrors(validate: ValidateFn): string[] {
 /**
  * Validate a Jx document against the active document schema.
  *
- * @param {unknown} doc - Parsed document
+ * @param {CandidateDocument} doc - Parsed document
  * @returns {Promise<string[]>} Formatted error strings; empty when valid or validation unavailable
  */
-export async function validateDoc(doc: unknown): Promise<string[]> {
+export async function validateDoc(doc: CandidateDocument): Promise<string[]> {
   const validate = await getValidator("document");
   if (!validate || validate(doc)) {
     return [];
@@ -176,7 +173,7 @@ export async function validateDoc(doc: unknown): Promise<string[]> {
  * @param doc - Parsed document
  * @returns The errors, `[]` when valid, or `null` when no validator could be compiled
  */
-export async function validateDocOrNull(doc: unknown): Promise<string[] | null> {
+export async function validateDocOrNull(doc: CandidateDocument): Promise<string[] | null> {
   const validate = await getValidator("document");
   if (!validate) {
     return null;
@@ -190,10 +187,10 @@ export async function validateDocOrNull(doc: unknown): Promise<string[] | null>
  * extension's fragment), so this is the only gate that catches a typo'd section key or a misshapen
  * extension section before the write lands.
  *
- * @param {unknown} config - Parsed project.json
+ * @param {ProjectConfig | JsonValue} config - Parsed project.json
  * @returns {Promise<string[]>} Formatted error strings; empty when valid or validation unavailable
  */
-export async function validateProjectConfig(config: unknown): Promise<string[]> {
+export async function validateProjectConfig(config: ProjectConfig | JsonValue): Promise<string[]> {
   const validate = await getValidator("project");
   if (!validate || validate(config)) {
     return [];

package/src/services/live-surfaces.ts

@@ -173,12 +173,15 @@ export interface LiveSurfaceDeps {
   redefineOnCanvases: (doc: JxDocument, base: string) => number;
 }
 
-/** The sentence a result is said in. Exported so the wording is tested, not only the branch. */
-export function liveSaveNotice(result: LiveSurfaceResult): {
+/** How a save's result is announced: the toast key it replaces, its level and its sentence. */
+export interface LiveSaveNotice {
   key: string;
   level: "info" | "warn";
   message: string;
-} {
+}
+
+/** The sentence a result is said in. Exported so the wording is tested, not only the branch. */
+export function liveSaveNotice(result: LiveSurfaceResult): LiveSaveNotice {
   const what =
     result.target.kind === "surface" ? `surface ${result.target.name}` : result.target.tag;
   const key = `live-chrome:${what}`;