@jxsuite/studio 6.1.1 → 8.0.0

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 {

package/src/settings/contributed-section.ts

@@ -39,6 +39,7 @@
  *   text. It is one value now, and the field shows it.
  */
 
+import { isFunction, isJsonObject, isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { getPlatform } from "../platform";
 import { commitProjectConfig } from "../tabs/project-config";
@@ -48,12 +49,12 @@ import { resolveContextPointer } from "../services/context-resolver";
 import { deriveSecretEnvName } from "../services/data-service";
 import { validateProjectConfig } from "../services/jx-validate";
 import { notify } from "../services/notify";
-import { paneRegion } from "../ui/regions";
-import { paneOfContainer } from "../canvas/canvas-surface";
+import { SETTINGS_DIALOG_REGION } from "../surfaces/settings-dialog";
 import { mountContributedSurface } from "../surfaces/settings-contributed";
 
 import type { JsonSchema, SchemaFormContext } from "../ui/schema-form";
-import type { ProjectConfig } from "@jxsuite/schema/types";
+import type { JsonObject, JsonValue } from "@jxsuite/schema/types";
+import type { ResolveContextOptions } from "../services/context-resolver";
 import type {
   ContributedActions,
   ContributedSurfaceHandle,
@@ -74,7 +75,13 @@ export interface SettingsContribution {
     entry?:
       | {
           ui?: Record<string, { control?: string; enum?: unknown }> | undefined;
-          newEntry?: Record<string, unknown> | undefined;
+          newEntry?: JsonObject | undefined;
+          /**
+           * What ONE entry of a map section is called, singular and lowercase ("content type",
+           * "table"), so the column offers "New content type" rather than "New Entry", a word that
+           * means a collection's item everywhere else in Studio. Defaults to "entry".
+           */
+          noun?: string | undefined;
         }
       | undefined;
   };
@@ -139,13 +146,8 @@ export function resetContributedSectionState(): void {
  *   such entry, so the caller's refusal can name both sides.
  */
 export function selectContributedEntry(sectionKey: string, entryKey: string): string[] | null {
-  const section = (projectState?.projectConfig as Record<string, unknown> | null | undefined)?.[
-    sectionKey
-  ];
-  const entries =
-    section && typeof section === "object" && !Array.isArray(section)
-      ? (section as Record<string, unknown>)
-      : {};
+  const section = projectState?.projectConfig?.[sectionKey];
+  const entries = isJsonObject(section) ? section : {};
   if (!Object.hasOwn(entries, entryKey)) {
     return Object.keys(entries);
   }
@@ -170,6 +172,14 @@ export function resetContributedDiagnostics(): void {
   diagnostics.clear();
 }
 
+/** {@link routeDiagnostics}' answer: per-field messages, and the ones about the record itself. */
+export interface RoutedDiagnostics {
+  /** The first message for each property one level under the base, keyed by property name. */
+  fields: Record<string, string>;
+  /** Messages whose pointer is the base itself, for the section line. */
+  section: string[];
+}
+
 /**
  * Route `jx-validate` messages ("/search/index: must be string") to the field they are about.
  *
@@ -182,10 +192,7 @@ export function resetContributedDiagnostics(): void {
  * @param {string[]} messages
  * @returns
  */
-export function routeDiagnostics(
-  base: string,
-  messages: string[],
-): { fields: Record<string, string>; section: string[] } {
+export function routeDiagnostics(base: string, messages: string[]): RoutedDiagnostics {
   const fields: Record<string, string> = {};
   const section: string[] = [];
   for (const message of messages) {
@@ -230,7 +237,12 @@ export function routeDiagnostics(
  * @param {() => void} rerender
  */
 async function saveProjectConfig(base: string, rerender: () => void) {
-  const config = (projectState as { projectConfig: ProjectConfig }).projectConfig;
+  /* Every caller reached this through `sectionValue`, which returns null without a config, so a
+     project is open here; the guard only states that to the compiler. */
+  const config = projectState?.projectConfig;
+  if (!config) {
+    return;
+  }
 
   const commit = await commitProjectConfig();
   if (!commit.ok) {
@@ -258,7 +270,7 @@ async function saveProjectConfig(base: string, rerender: () => void) {
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
 /** Apply a schema-form patch onto a record in place; `undefined` values unset the key. */
-function applyPatch(target: Record<string, unknown>, patch: Record<string, unknown>) {
+function applyPatch<V>(target: Record<string, V>, patch: Record<string, V | undefined>) {
   for (const [key, value] of Object.entries(patch)) {
     if (value === undefined) {
       delete target[key];
@@ -277,30 +289,30 @@ function slugify(name: string): string {
 }
 
 /** Instantiate a newEntry template, substituting `${key}` in every string value. */
-function instantiateNewEntry(
-  template: Record<string, unknown> | undefined,
-  key: string,
-): Record<string, unknown> {
+function instantiateNewEntry(template: JsonObject | undefined, key: string): JsonObject {
   if (!template) {
     return {};
   }
-  const substitute = (value: unknown): unknown => {
-    if (typeof value === "string") {
+  const substituteObject = (value: JsonObject): JsonObject => {
+    const out: JsonObject = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = substitute(v);
+    }
+    return out;
+  };
+  const substitute = (value: JsonValue): JsonValue => {
+    if (isString(value)) {
       return value.replaceAll("${key}", key);
     }
     if (Array.isArray(value)) {
       return value.map((item) => substitute(item));
     }
-    if (value && typeof value === "object") {
-      const out: Record<string, unknown> = {};
-      for (const [k, v] of Object.entries(value)) {
-        out[k] = substitute(v);
-      }
-      return out;
+    if (isJsonObject(value)) {
+      return substituteObject(value);
     }
     return value;
   };
-  return substitute(template) as Record<string, unknown>;
+  return substituteObject(template);
 }
 
 /**
@@ -314,53 +326,68 @@ function buildContext(
   entryKey: string | null = null,
 ): SchemaFormContext {
   const platform = getPlatform();
-  return {
+  const context: SchemaFormContext = {
     fieldKeyPrefix: `$settings.${sectionKey}`,
-    resolvePointer: (pointer, scope) =>
-      resolveContextPointer(pointer, {
-        projectConfig: (projectState?.projectConfig ?? {}) as Record<string, unknown>,
-        ...(scope !== undefined && { scope }),
-        ...(opts.formats !== undefined && { formats: opts.formats }),
-      }),
-    ...(typeof platform.setSecrets === "function"
-      ? {
-          commitSecret: async (key: string, value: string) => {
-            const envName = deriveSecretEnvName(sectionKey, entryKey, key);
-            await platform.setSecrets!({ set: { [envName]: value } });
-            return envName;
-          },
-        }
-      : {}),
+    resolvePointer: (pointer, scope) => {
+      const resolveOpts: ResolveContextOptions = {
+        projectConfig: projectState?.projectConfig ?? {},
+      };
+      /* The scope is the form's current value record, which is section JSON; the guard is what
+         lets the compiler see that, and it also stands for the old `!== undefined` test. */
+      if (isJsonObject(scope)) {
+        resolveOpts.scope = scope;
+      }
+      if (opts.formats !== undefined) {
+        resolveOpts.formats = opts.formats;
+      }
+      return resolveContextPointer(pointer, resolveOpts);
+    },
   };
+  if (isFunction(platform.setSecrets)) {
+    context.commitSecret = async (key: string, value: string) => {
+      const envName = deriveSecretEnvName(sectionKey, entryKey, key);
+      await platform.setSecrets!({ set: { [envName]: value } });
+      return envName;
+    };
+  }
+  return context;
 }
 
 /** The section's value object in the project config, created on demand. */
-function sectionValue(key: string): Record<string, unknown> | null {
-  const config = projectState?.projectConfig as Record<string, unknown> | null | undefined;
+function sectionValue(key: string): JsonObject | null {
+  const config = projectState?.projectConfig;
   if (!config) {
     return null;
   }
   const existing = config[key];
-  if (existing && typeof existing === "object" && !Array.isArray(existing)) {
-    return existing as Record<string, unknown>;
+  if (isJsonObject(existing)) {
+    return existing;
   }
-  const fresh: Record<string, unknown> = {};
+  const fresh: JsonObject = {};
   config[key] = fresh;
   return fresh;
 }
 
 // ─── Per-container mount ──────────────────────────────────────────────────────
 
-/* There is no `paneOfContainer` here. It moved to `canvas/canvas-surface.ts`, beside the other
-   "which pane is this about" answers, because it is not a settings idea: any stage content handed
-   only a host needs it, and `settings/general-settings.ts` and `settings/project-sections.ts` are
-   two more that do — both write a canvas mode, and both used to write the FOCUSED pane's. */
+/**
+ * A region under the settings dialog, which is where a contributed section is drawn (§17.1): its
+ * entry rows and its entry editor are named under `overlay.dialog:settings`, so a shot can crop one
+ * without a selector.
+ *
+ * @param {string} part
+ * @returns {string}
+ */
+function sectionRegion(part: string): string {
+  return `${SETTINGS_DIALOG_REGION}/${part}`;
+}
 
 /** One mounted section: its document, its two island hosts, and what it was last asked to draw. */
 interface SectionMount {
   /** The element the registry handed the renderer, and this record's identity. */
   container: HTMLElement;
-  handle: ContributedSurfaceHandle;
+  /** The mounted document, or `null` for the instant between creating this record and mounting. */
+  handle: ContributedSurfaceHandle | null;
   contribution: SettingsContribution;
   opts: ContributedSectionOptions;
   /** Where the schema form goes, once the document has made one. */
@@ -397,14 +424,39 @@ function say(record: SectionMount, value: string): void {
 
 // ─── Projection ───────────────────────────────────────────────────────────────
 
+/** The default name for one entry of a map section, when the contribution names none. */
+const DEFAULT_ENTRY_NOUN = "entry";
+
+/** The map column's words for one entry: the four places a map section names it. */
+export interface EntryWords {
+  newLabel: string;
+  newFieldLabel: string;
+  newPlaceholder: string;
+  emptyText: string;
+}
+
+/** The map column's words, from what the contribution calls one entry. */
+export function entryWords(noun?: string): EntryWords {
+  const word = noun?.trim().toLowerCase() || DEFAULT_ENTRY_NOUN;
+  const capitalised = `${word.charAt(0).toUpperCase()}${word.slice(1)}`;
+  // "an entry", "a table": the article English reads before the word's first sound, by its letter.
+  const article = /^[aeiou]/u.test(word) ? "an" : "a";
+  return {
+    emptyText: `Select ${article} ${word} or create one`,
+    newFieldLabel: `${capitalised} name`,
+    newLabel: `New ${word}`,
+    newPlaceholder: `${slugify(word)}-name`,
+  };
+}
+
 /** What the document draws right now, read from the store and this module's own state. */
 function project(record: SectionMount): ContributedView {
-  const { container, contribution, opts } = record;
+  const { contribution, opts } = record;
   const sectionKey = contribution.key;
   const title = contribution.title ?? sectionKey;
   const actionsState = opts.actions ? "slot" : "none";
-  const paneId = paneOfContainer(container);
-  const editorRegion = paneRegion(paneId, "editor");
+  const editorRegion = sectionRegion("editor");
+  const words = entryWords(contribution.settings.entry?.noun);
 
   if ((contribution.settings.layout ?? "form") !== "map") {
     return {
@@ -417,21 +469,21 @@ function project(record: SectionMount): ContributedView {
       newName: "",
       newState: "closed",
       title,
+      ...words,
     };
   }
 
   const entries = sectionValue(sectionKey) ?? {};
   const selected = selectedEntries.get(sectionKey) ?? null;
   const value = selected === null ? undefined : entries[selected];
-  const editing =
-    selected !== null && value !== undefined && value !== null && typeof value === "object";
+  const editing = selected !== null && isNonNullObject(value);
   return {
     actionsState,
     editorRegion,
     editorState: editing ? "editing" : "empty",
     entries: Object.keys(entries).map((name) => ({
       key: name,
-      region: paneRegion(paneId, `entry:${name}`),
+      region: sectionRegion(`entry:${name}`),
       selected: name === selected,
     })),
     entryName: record.echo ?? (editing ? selected : ""),
@@ -439,6 +491,7 @@ function project(record: SectionMount): ContributedView {
     newName: newEntryNames.get(sectionKey) ?? "",
     newState: newEntryOpen.has(sectionKey) ? "open" : "closed",
     title,
+    ...words,
   };
 }
 
@@ -499,11 +552,14 @@ function paintForm(record: SectionMount): void {
   const entries = sectionValue(sectionKey) ?? {};
   const selected = selectedEntries.get(sectionKey) ?? null;
   const value = selected === null ? undefined : entries[selected];
-  if (selected === null || !value || typeof value !== "object") {
+  if (selected === null || !isNonNullObject(value)) {
     host.replaceChildren();
     return;
   }
-  const entry = value as Record<string, unknown>;
+  /* SAFETY: a map section's entries are objects by the section schema (`additionalProperties`
+     of type object), and the check above admits only objects; an array entry is malformed config
+     the form still treats as the record it should be, reading and writing named members. */
+  const entry = value as JsonObject;
   const base = `/${sectionKey}/${selected}`;
   place(
     mountSchemaForm(`section:${sectionKey}:${selected}`, contribution.entrySchema, entry, {
@@ -619,7 +675,7 @@ function actionsFor(record: SectionMount): ContributedActions {
         return;
       }
       // Rebuild the map to preserve entry order under the new key
-      const next: Record<string, unknown> = {};
+      const next: JsonObject = {};
       for (const [k, v] of Object.entries(target)) {
         next[k === selected ? slug : k] = v;
         delete target[k];
@@ -655,19 +711,20 @@ export function renderContributedSection(
     record.contribution = contribution;
     record.opts = opts;
   }
-  if (!record?.handle.attached()) {
-    record?.handle.dispose();
+  let handle = record?.handle ?? null;
+  if (!record || !handle?.attached()) {
+    handle?.dispose();
     const fresh: SectionMount = {
       actionsHost: null,
       container,
       contribution,
       echo: null,
       formHost: null,
-      handle: undefined as unknown as ContributedSurfaceHandle,
+      handle: null,
       opts,
     };
     mounts.set(container, fresh);
-    fresh.handle = mountContributedSurface(container, actionsFor(fresh), {
+    handle = mountContributedSurface(container, actionsFor(fresh), {
       actionsSlot: (host) => {
         fresh.actionsHost = host;
         paintActions(fresh);
@@ -677,9 +734,10 @@ export function renderContributedSection(
         paintForm(fresh);
       },
     });
+    fresh.handle = handle;
     record = fresh;
   }
-  record.handle.update(project(record));
+  handle.update(project(record));
   paintActions(record);
   paintForm(record);
 }