@jxsuite/studio 6.1.1 → 8.0.0

package/src/services/cem-export.ts

@@ -1,21 +1,91 @@
 /// <reference lib="dom" />
-import type { CemParameter, JxMutableNode, JxStateObject } from "@jxsuite/schema/types";
+import type {
+  CemParameter,
+  JxElementTagName,
+  JxMutableNode,
+  JxStateDefinition,
+  JxStateObject,
+  JsonValue,
+} from "@jxsuite/schema/types";
 import {
   displayTagName,
   isFunctionDef,
   isJsonObject,
   isPrivateStateKey,
+  isString,
 } from "@jxsuite/schema/guards";
 
+/** A CEM `{ text }` type reference. */
+interface CemTypeText {
+  text: string;
+}
+
+/** A CEM class member: a `method` (function entry) or a `field` (signal / type def). */
+interface CemMember {
+  kind: "method" | "field";
+  name: string;
+  type?: CemTypeText;
+  default?: string;
+  description?: string;
+  parameters?: CemParameter[];
+  attribute?: string;
+  reflects?: true;
+  deprecated?: string | true;
+}
+
+/** A CEM attribute linked to a field. */
+interface CemAttribute {
+  name: string;
+  type?: CemTypeText;
+  fieldName: string;
+}
+
+/** A CEM event a method dispatches. */
+interface CemManifestEvent {
+  name: string;
+  type?: JsonValue;
+  description?: string;
+}
+
+/** A CEM slot; the default slot has an empty name. */
+interface CemSlot {
+  name: string;
+  description?: string;
+}
+
+/** A CEM CSS custom property. */
+interface CemCssProperty {
+  default: string;
+  name: string;
+}
+
+/** A CEM CSS part. */
+interface CemCssPart {
+  name: string;
+}
+
+/** The single custom-element class declaration the manifest exports. */
+interface CemClassDeclaration {
+  kind: "class";
+  members: CemMember[];
+  name: JxElementTagName;
+  tagName: JxElementTagName;
+  attributes?: CemAttribute[];
+  events?: CemManifestEvent[];
+  slots?: CemSlot[];
+  cssProperties?: CemCssProperty[];
+  cssParts?: CemCssPart[];
+}
+
 /** Collect slot elements from the document tree. Whitespace-only names count as unnamed. */
 export function collectSlots(node?: JxMutableNode | null, slots: string[] = []) {
   if (node?.tagName === "slot") {
     const name = node.attributes?.name;
-    slots.push(typeof name === "string" ? name.trim() : "");
+    slots.push(isString(name) ? name.trim() : "");
   }
   if (Array.isArray(node?.children)) {
     for (const c of node.children) {
-      collectSlots(typeof c === "string" ? undefined : c, slots);
+      collectSlots(isString(c) ? undefined : c, slots);
     }
   }
   return slots;
@@ -47,7 +117,7 @@ export function validateComponentSlots(doc: JxMutableNode): string | null {
  *
  * @param {{ document: JxMutableNode }} S - Studio state
  * @param {{
- *   defCategory: (d: unknown) => string;
+ *   defCategory: (d: JxStateDefinition) => string;
  *   normParam: (p: string | CemParameter) => CemParameter;
  *   collectCssParts: (node: JxMutableNode) => { name: string }[];
  * }} helpers
@@ -55,7 +125,7 @@ export function validateComponentSlots(doc: JxMutableNode): string | null {
 export function exportCemManifest(
   S: { document: JxMutableNode },
   helpers: {
-    defCategory: (d: unknown) => string;
+    defCategory: (d: JxStateDefinition) => string;
     normParam: (p: string | CemParameter) => CemParameter;
     collectCssParts: (node: JxMutableNode) => { name: string }[];
   },
@@ -68,9 +138,9 @@ export function exportCemManifest(
   }
 
   const state = doc.state || {};
-  const members: Record<string, unknown>[] = [];
-  const attributes: Record<string, unknown>[] = [];
-  const events: Record<string, unknown>[] = [];
+  const members: CemMember[] = [];
+  const attributes: CemAttribute[] = [];
+  const events: CemManifestEvent[] = [];
   const seenEvents = new Set<string>();
 
   for (const [key, d] of Object.entries(state)) {
@@ -82,56 +152,72 @@ export function exportCemManifest(
 
     if (cat === "function") {
       if (isFunctionDef(d)) {
-        members.push({
-          kind: "method",
-          name: key,
-          ...(d.description ? { description: d.description } : {}),
-          ...(d.parameters ? { parameters: d.parameters.map(normParam) } : {}),
-          ...(d.deprecated
-            ? { deprecated: typeof d.deprecated === "string" ? d.deprecated : true }
-            : {}),
-        });
+        const method: CemMember = { kind: "method", name: key };
+        if (d.description) {
+          method.description = d.description;
+        }
+        if (d.parameters) {
+          method.parameters = d.parameters.map(normParam);
+        }
+        if (d.deprecated) {
+          method.deprecated = isString(d.deprecated) ? d.deprecated : true;
+        }
+        members.push(method);
         // Collect emits
         for (const ev of d.emits ?? []) {
           if (ev.name && !seenEvents.has(ev.name)) {
             seenEvents.add(ev.name);
-            events.push({
-              name: ev.name,
-              ...(ev.type !== undefined ? { type: ev.type } : {}),
-              ...(ev.description ? { description: ev.description } : {}),
-            });
+            const event: CemManifestEvent = { name: ev.name };
+            if (ev.type !== undefined) {
+              event.type = ev.type;
+            }
+            if (ev.description) {
+              event.description = ev.description;
+            }
+            events.push(event);
           }
         }
       } else if (isJsonObject(d)) {
         // Legacy $handler entry — emit a bare method member
         const { description } = d;
-        members.push({
-          kind: "method",
-          name: key,
-          ...(typeof description === "string" ? { description } : {}),
-        });
+        const method: CemMember = { kind: "method", name: key };
+        if (isString(description)) {
+          method.description = description;
+        }
+        members.push(method);
       }
     } else if (cat === "state") {
       // Naked primitive values carry no metadata; object defs are signals/type defs.
+      /* SAFETY: defCategory classified this entry as "state", which it only does when the entry
+         Carries no $expression, $prototype, $handler or $compute, so an object entry here is an
+         Expanded signal or schema type def: the JxStateObject shape. */
       const def: JxStateObject | null = isJsonObject(d) ? (d as JxStateObject) : null;
-      members.push({
-        kind: "field",
-        name: key,
-        ...(def?.type ? { type: { text: def.type } } : {}),
-        ...(def && def.default !== undefined ? { default: String(def.default) } : {}),
-        ...(def?.description ? { description: def.description } : {}),
-        ...(def?.attribute ? { attribute: def.attribute } : {}),
-        ...(def?.reflects ? { reflects: true } : {}),
-        ...(def?.deprecated
-          ? { deprecated: typeof def.deprecated === "string" ? def.deprecated : true }
-          : {}),
-      });
+      const field: CemMember = { kind: "field", name: key };
+      if (def?.type) {
+        field.type = { text: def.type };
+      }
+      if (def && def.default !== undefined) {
+        field.default = String(def.default);
+      }
+      if (def?.description) {
+        field.description = def.description;
+      }
+      if (def?.attribute) {
+        field.attribute = def.attribute;
+      }
+      if (def?.reflects) {
+        field.reflects = true;
+      }
+      if (def?.deprecated) {
+        field.deprecated = isString(def.deprecated) ? def.deprecated : true;
+      }
+      members.push(field);
       if (def?.attribute) {
-        attributes.push({
-          name: def.attribute,
-          ...(def.type ? { type: { text: def.type } } : {}),
-          fieldName: key,
-        });
+        attributes.push(
+          def.type
+            ? { name: def.attribute, type: { text: def.type }, fieldName: key }
+            : { name: def.attribute, fieldName: key },
+        );
       }
     }
   }
@@ -139,7 +225,7 @@ export function exportCemManifest(
   // Slots
   const slotNames = collectSlots(doc);
   const slots = slotNames.map((name: string) => {
-    const slot: { name: string; description?: string } = { name: name || "" };
+    const slot: CemSlot = { name: name || "" };
     if (!name) {
       slot.description = "Default slot";
     }
@@ -155,22 +241,27 @@ export function exportCemManifest(
   // CSS parts
   const cssParts = collectCssParts(doc).map((p) => ({ name: p.name }));
 
+  const declaration: CemClassDeclaration = { kind: "class", members, name: tagName, tagName };
+  if (attributes.length > 0) {
+    declaration.attributes = attributes;
+  }
+  if (events.length > 0) {
+    declaration.events = events;
+  }
+  if (slots.length > 0) {
+    declaration.slots = slots;
+  }
+  if (cssProperties.length > 0) {
+    declaration.cssProperties = cssProperties;
+  }
+  if (cssParts.length > 0) {
+    declaration.cssParts = cssParts;
+  }
+
   const manifest = {
     modules: [
       {
-        declarations: [
-          {
-            kind: "class",
-            members,
-            name: tagName,
-            tagName,
-            ...(attributes.length > 0 ? { attributes } : {}),
-            ...(events.length > 0 ? { events } : {}),
-            ...(slots.length > 0 ? { slots } : {}),
-            ...(cssProperties.length > 0 ? { cssProperties } : {}),
-            ...(cssParts.length > 0 ? { cssParts } : {}),
-          },
-        ],
+        declarations: [declaration],
         kind: "javascript-module",
         path: "",
       },

package/src/services/cf-settings.ts

@@ -1,12 +1,12 @@
 /// <reference lib="dom" />
 /**
  * Cf-settings — the Cloudflare publish connection on platforms without a hosted OAuth broker (dev
- * server, desktop). The API token is stored like the AI key, over `settings/kernel.ts`. It only ever
- * leaves the machine to the same-origin `/__studio/cf/proxy`, which forwards it as a bearer to
+ * server, desktop). The API token is stored like the AI key, over `settings/kernel.ts`. It only
+ * ever leaves the machine to the same-origin `/__studio/cf/proxy`, which forwards it as a bearer to
  * api.cloudflare.com (not CORS-enabled, hence the proxy).
  *
- * As with the AI provider, a blank value is a VALUE: {@link clearCfConnection} is the deletion path,
- * so nothing can revoke a connection by rendering an empty field into a setter.
+ * As with the AI provider, a blank value is a VALUE: {@link clearCfConnection} is the deletion
+ * path, so nothing can revoke a connection by rendering an empty field into a setter.
  *
  * @license MIT
  */

package/src/services/clock.ts

@@ -19,6 +19,11 @@
  * value the formatter reads back.
  */
 
+import { isNumber } from "@jxsuite/schema/guards";
+
+/** One minute in milliseconds: the unit the relative-time formatters count up from. */
+export const MINUTE = 60_000;
+
 /** Epoch milliseconds the clock is pinned to, or `null` while it follows the real clock. */
 let _pinned: number | null = null;
 
@@ -43,7 +48,7 @@ export function now(): number {
  *   photograph the wall clock and the capture would be accepted.
  */
 export function pinClock(at: number | string | Date): number {
-  const ms = at instanceof Date ? at.getTime() : typeof at === "number" ? at : Date.parse(at);
+  const ms = at instanceof Date ? at.getTime() : isNumber(at) ? at : Date.parse(at);
   if (!Number.isFinite(ms)) {
     throw new TypeError(`clock: cannot pin to ${JSON.stringify(at)}`);
   }

package/src/services/code-services.ts

@@ -6,7 +6,13 @@ import { projectState } from "../state";
 import { getNodeAtPath } from "../store";
 import { loadedMonaco } from "./monaco-lazy";
 import type { JxPath } from "../state";
-import type { JxFunctionDef, JxMutableNode } from "@jxsuite/schema/types";
+import type {
+  JsonObject,
+  JsonValue,
+  JxDocumentValue,
+  JxFunctionDef,
+  JxMutableNode,
+} from "@jxsuite/schema/types";
 import type { editor } from "monaco-editor";
 
 export interface OxLintDiagnostic {
@@ -19,15 +25,13 @@ export interface OxLintDiagnostic {
 }
 
 /**
+ * Run one code-service action. The payload travels to the backend as a JSON body.
+ *
  * @param {string} action
- * @param {unknown} payload
+ * @param {JsonValue} payload
  */
-export async function codeService(action: string, payload: unknown) {
-  const platform = getPlatform();
-  if (!platform.codeService) {
-    return null;
-  }
-  return platform.codeService(action, payload);
+export async function codeService(action: string, payload: JsonValue) {
+  return getPlatform().codeService(action, payload);
 }
 
 /**
@@ -36,21 +40,17 @@ export async function codeService(action: string, payload: unknown) {
  * @param {string} name
  */
 export async function locateDocument(name: string) {
-  const platform = getPlatform();
-  if (!platform.locateFile) {
-    return null;
-  }
-  return platform.locateFile(name);
+  return getPlatform().locateFile(name);
 }
 
 /** Schema returned by a plugin's `$prototype` module (loose superset used across panels). */
 export interface PluginSchema {
   type?: string;
   description?: string;
-  properties?: Record<string, unknown>;
+  properties?: JsonObject;
   required?: string[];
   returns?: { type?: string };
-  [key: string]: unknown;
+  [key: string]: JsonValue | undefined;
 }
 
 /** Cache of plugin schemas keyed by "$src::$prototype". */
@@ -81,12 +81,12 @@ export async function fetchPluginSchema(
 
   try {
     const platform = getPlatform();
-    if (!platform.fetchPluginSchema) {
-      pluginSchemaCache.set(cacheKey, null);
-      return null;
-    }
     const base =
       !importedPath && state.documentPath ? `${location.origin}/${state.documentPath}` : undefined;
+    /* SAFETY: every platform answers with the plugin module's JSON Schema export, parsed from JSON,
+       Or null when it has none; PluginSchema is the all-optional, JSON-open view of that object. A
+       Platform without the method throws here, and the catch below caches null exactly as for a
+       Failed fetch. */
     const schema = (await platform.fetchPluginSchema(
       src,
       def.$prototype,
@@ -117,14 +117,14 @@ export function setLintMarkers(
   if (!monaco) {
     return;
   }
-  const markers = diagnostics
-    .map((d) => {
-      const label = d.labels?.[0];
-      if (!label) {
-        return null;
-      }
-      const { line, column, length } = label.span;
-      return {
+  const markers = diagnostics.flatMap((d) => {
+    const label = d.labels?.[0];
+    if (!label) {
+      return [];
+    }
+    const { line, column, length } = label.span;
+    return [
+      {
         code: d.url ? { target: monaco.Uri.parse(d.url), value: d.code } : d.code,
         endColumn: column + (length || 1),
         endLineNumber: line,
@@ -134,9 +134,12 @@ export function setLintMarkers(
         source: "oxlint",
         startColumn: column,
         startLineNumber: line,
-      };
-    })
-    .filter(Boolean);
+      },
+    ];
+  });
+  /* SAFETY: each marker is an IMarkerData except that `code` (and the object form's `value`) may be
+     Undefined when oxlint reports a diagnostic without a rule code; Monaco treats an undefined code
+     Exactly like an absent one. */
   monaco.editor.setModelMarkers(model, "oxlint", markers as editor.IMarkerData[]);
 }
 
@@ -149,7 +152,7 @@ export function getFunctionArgs(
   document: JxMutableNode | null | undefined,
 ): string[] {
   // Read parameters off any object-shaped def (covers legacy entries without $prototype).
-  const fromDef = (def: unknown): string[] | null => {
+  const fromDef = (def: JxDocumentValue | undefined): string[] | null => {
     if (!isJsonObject(def)) {
       return null;
     }
@@ -157,6 +160,9 @@ export function getFunctionArgs(
     if (!Array.isArray(params) || params.length === 0) {
       return null;
     }
+    /* SAFETY: a def's `parameters` array holds bare names or CEM parameter objects — the form the
+       Schema admits for Function, prototype and legacy handler entries alike — which is the
+       Element type paramNames reads. */
     return paramNames(params as JxFunctionDef["parameters"]);
   };
   if (editing.type === "def") {

package/src/services/connection.ts

@@ -14,8 +14,8 @@
  * does not stay on the Problems list (§16.1's second and third rules: a record is retired when what
  * it names is fixed, and a repeat is not a new row).
  *
- * A platform without `subscribeConnection` — the dev server, electrobun — installs nothing. There
- * is no connection to lose there, and a notice about one would be a lie.
+ * A platform without `subscribeConnection` — the dev server — installs nothing. There is no
+ * connection to lose there, and a notice about one would be a lie.
  *
  * @docs studio/interface/problems-and-progress
  */

package/src/services/context-manager.ts

@@ -12,14 +12,23 @@
  */
 
 import type { createChatState } from "@jxsuite/ai/chat-state";
+import { CHARS_PER_TOKEN } from "@jxsuite/ai/harness";
 import {
   SEAL_RELOADED,
   repairToolPairs,
   toChatMessages,
   toLiveMessages,
 } from "@jxsuite/ai/messages";
+import { isString } from "@jxsuite/schema/guards";
 import { modelContextWindow } from "./ai-models";
 
+/** How many tool messages {@link pruneOrphanToolMessages} dropped, moved and sealed. */
+export interface OrphanToolRepair {
+  dropped: number;
+  moved: number;
+  sealed: number;
+}
+
 /** Shape of a single entry returned by `chatState.toMessagesArray()`. */
 interface MessageArrayEntry {
   role: string;
@@ -31,9 +40,6 @@ interface MessageArrayEntry {
 
 // ─── Constants ──────────────────────────────────────────────────────────────
 
-/** Rough heuristic: average 4 characters per token. */
-const CHARS_PER_TOKEN = 4;
-
 /**
  * Approximate context windows (in tokens) per model id, longest-prefix matched. Used to derive a
  * model-aware budget instead of a flat cap (specs/ai.md §2.1). Conservative fallback for unknown
@@ -109,7 +115,7 @@ const MIN_USER_TURNS = 3;
  * @returns {number}
  */
 function estimateTokens(input: string | MessageArrayEntry[]): number {
-  if (typeof input === "string") {
+  if (isString(input)) {
     return Math.ceil(input.length / CHARS_PER_TOKEN);
   }
   let total = 0;
@@ -174,7 +180,7 @@ function contextTokens(
       return reused;
     }
   }
-  return systemTokens + estimateTokens(chatState.toMessagesArray() as MessageArrayEntry[]);
+  return systemTokens + estimateTokens(chatState.toMessagesArray());
 }
 
 /**
@@ -316,11 +322,9 @@ export const UNANSWERED_TOOL_RESULT = JSON.stringify({ success: false, error: SE
  * @param {ReturnType<typeof createChatState>} chatState
  * @returns {{ dropped: number; moved: number; sealed: number }}
  */
-export function pruneOrphanToolMessages(chatState: ReturnType<typeof createChatState>): {
-  dropped: number;
-  moved: number;
-  sealed: number;
-} {
+export function pruneOrphanToolMessages(
+  chatState: ReturnType<typeof createChatState>,
+): OrphanToolRepair {
   const live = chatState.messages;
   const neutral = toChatMessages(live);
   const { messages, sealed, dropped, moved } = repairToolPairs(neutral);

package/src/services/context-resolver.ts

@@ -7,12 +7,15 @@
  * resolves to the registered format names instead of a project.json key.
  */
 
+import { isNonNullObject, isNumber, isString } from "@jxsuite/schema/guards";
+import type { JsonObject, JsonValue, ProjectConfig } from "@jxsuite/schema/types";
+
 /** Options for {@link resolveContextPointer}. */
 export interface ResolveContextOptions {
   /** The project configuration object the pointer walks over. */
-  projectConfig: Record<string, unknown>;
+  projectConfig: ProjectConfig;
   /** Scope record supplying `{@param}` substitutions (e.g. the enclosing form value). */
-  scope?: Record<string, unknown> | undefined;
+  scope?: JsonObject | undefined;
   /** Registered formats backing the `$formats` virtual root. */
   formats?: { name: string }[] | undefined;
 }
@@ -30,9 +33,13 @@ const PARAM_SEGMENT = /^\{@(\w+)\}$/;
  *
  * @param {string} pointer
  * @param {ResolveContextOptions} opts
- * @returns {unknown} The resolved value, or `undefined` when the pointer does not resolve.
+ * @returns {JsonValue | undefined} The resolved value, or `undefined` when the pointer does not
+ *   resolve.
  */
-export function resolveContextPointer(pointer: string, opts: ResolveContextOptions): unknown {
+export function resolveContextPointer(
+  pointer: string,
+  opts: ResolveContextOptions,
+): JsonValue | undefined {
   if (!pointer.startsWith("#/$context/")) {
     return undefined;
   }
@@ -42,7 +49,7 @@ export function resolveContextPointer(pointer: string, opts: ResolveContextOptio
     const match = raw.match(PARAM_SEGMENT);
     if (match) {
       const value = opts.scope?.[match[1]!];
-      if (typeof value !== "string" && typeof value !== "number") {
+      if (!isString(value) && !isNumber(value)) {
         return undefined;
       }
       const substituted = String(value);
@@ -62,12 +69,17 @@ export function resolveContextPointer(pointer: string, opts: ResolveContextOptio
     return (opts.formats ?? []).map((format) => format.name);
   }
 
-  let node: unknown = opts.projectConfig;
+  /* SAFETY: the project config is parsed project.json, so every value under it is JSON;
+     ProjectConfig is the typed reading of that same object. */
+  let node: JsonValue | undefined = opts.projectConfig as JsonObject;
   for (const segment of segments) {
-    if (node === null || typeof node !== "object") {
+    if (!isNonNullObject(node)) {
       return undefined;
     }
-    node = (node as Record<string, unknown>)[segment];
+    /* SAFETY: node is a JSON object or array, and a pointer segment reads an array by its own
+       Index (and `length`) keys exactly as it reads an object's members, so the object view of
+       an array addresses the same values. */
+    node = (node as JsonObject)[segment];
   }
   return node;
 }