@jxsuite/studio 6.1.1 → 8.0.0

package/src/types.ts

@@ -2,6 +2,7 @@
 import type { CollabHandle } from "@jxsuite/collab/provider";
 import type {
   ContentTypeSchema,
+  JsonObject,
   JxMutableNode,
   JxPath,
   ProjectConfig,
@@ -39,6 +40,7 @@ import type {
   ImportReadyEvent,
   ImportSiteOptions,
   ImportSiteSummary,
+  JsonValue,
   PackageInfo,
   PackageOpResult,
   PackageVersionInfo,
@@ -47,9 +49,8 @@ import type {
   RecentProjectEntry,
   ReferencesResult,
   RenameResult,
-  SecretsSetRequest,
+  KeyValuePatch,
   SecretsSetResponse,
-  SettingsPatch,
   StarterInfo,
   UploadResult,
 } from "@jxsuite/protocol";
@@ -80,7 +81,6 @@ export type {
   DataRowsResult,
   DataRowUpdate,
   DirEntry,
-  ErrorBody,
   ExtensionCatalogEntry,
   ExtensionContributionInfo,
   ExtensionProjectBlock,
@@ -109,9 +109,8 @@ export type {
   ReferencesResult,
   RenameResult,
   SecretsListResponse,
-  SecretsSetRequest,
+  KeyValuePatch,
   SecretsSetResponse,
-  SettingsPatch,
   StarterInfo,
 } from "@jxsuite/protocol";
 
@@ -291,31 +290,30 @@ export interface SitePreviewResult extends SiteBuildResult {
  */
 export type FsResyncReason = "reconnect" | "commit" | "open";
 
+/**
+ * One request to a format class's capability (`POST /__studio/format`, or the desktop RPC of the
+ * same name): `parse` reads `source` into a Jx document, `serialize` writes `doc` back out as text,
+ * and the answer is that document or that text. The backend refuses an action the format does not
+ * declare, so `action` stays an open name.
+ */
+export interface FormatActionRequest {
+  action: string;
+  format: string;
+  source?: string | undefined;
+  /** The document to serialize, merged with its frontmatter. */
+  doc?: JxMutableNode | undefined;
+  options?: { mode?: string | undefined; frontmatter?: boolean | undefined } | undefined;
+}
+
 export interface StudioPlatform {
   id: string;
   projectRoot: string;
   /**
    * URL of the canvas iframe document. Optional: when set (chromium serves it from the project
    * server under the studio namespace), the iframe host uses it; otherwise the host falls back to
-   * the default dev-server path. Not keyed on `id` — chromium and electrobun both report `id:
-   * "desktop"`, but only chromium sets this.
+   * the default dev-server path. Not keyed on `id`.
    */
   canvasUrl?: string;
-  /**
-   * True when this platform resolves {@link canvasUrl} ASYNCHRONOUSLY.
-   *
-   * Electrobun does: the url is this window's loopback port, fetched over RPC inside `activate()`.
-   * Until the canvas fallback was anchored to the bundle it did not matter — the old literal
-   * `/packages/studio/canvas.html` resolved to nothing servable under `views://`, so an early frame
-   * simply failed and the host rebuilt when the real url landed. Now the fallback RESOLVES:
-   * `views://studio/canvas.html` is a document electrobun really stages. An early frame would boot
-   * the whole canvas bundle inside the SHELL's app-privileged origin, in a CEF instance running
-   * `disable-site-isolation-trials` — and the cross-origin loopback canvas exists precisely so that
-   * cannot happen. Declaring it makes the host wait instead.
-   *
-   * Not keyed on `id`: chromium and electrobun both report `"desktop"`, and only electrobun defers.
-   */
-  canvasUrlDeferred?: boolean;
   /**
    * Base URL the canvas fetches PROJECT FILES from — component `$ref`s, `$src` modules, images.
    *
@@ -394,12 +392,11 @@ export interface StudioPlatform {
    * image. So a caller that must DECODE a project file — the image editor — needs this instead.
    *
    * **The `<img>` route is not an alternative, on the one platform that matters most.** A preview
-   * `src` from `files/media-paths.ts` is a cross-origin loopback URL on the electrobun desktop
-   * while the shell sits on `views://`, so drawing it into a canvas taints the canvas and
-   * `toBlob()` throws; and `server.md` §4.2 bans CORS outright, because the whole loopback security
-   * model rests on the browser refusing cross-origin reads. Bytes through the PAL become a
-   * same-origin `Blob`, so tainting stops being a thing that can happen rather than a thing that is
-   * worked around.
+   * `src` from `files/media-paths.ts` can be a cross-origin loopback URL while the shell sits on
+   * another origin, so drawing it into a canvas taints the canvas and `toBlob()` throws; and
+   * `server.md` §4.2 bans CORS outright, because the whole loopback security model rests on the
+   * browser refusing cross-origin reads. Bytes through the PAL become a same-origin `Blob`, so
+   * tainting stops being a thing that can happen rather than a thing that is worked around.
    *
    * Optional, and feature-detected like every optional member: a backend without it simply does not
    * offer the image editor, which is the honest degradation `specs/desktop.md` §3.1 asks for.
@@ -464,8 +461,10 @@ export interface StudioPlatform {
     options?: { onResync?: (reason: FsResyncReason) => void },
   ) => () => void;
   discoverComponents: (dir?: string) => Promise<ComponentMeta[]>;
-  addPackage: (name: string) => Promise<unknown>;
-  removePackage: (name: string) => Promise<unknown>;
+  /* Resolves once the dependency is added (or removed) and rejects when it could not be. No caller
+     reads an answer, and the desktop RPC carries none. */
+  addPackage: (name: string) => Promise<void>;
+  removePackage: (name: string) => Promise<void>;
   listPackages: () => Promise<PackageInfo[]>;
   /**
    * Run `bun install` in the project root. Optional: platforms without a Bun-capable backend omit
@@ -493,7 +492,7 @@ export interface StudioPlatform {
    * section.
    */
   getAppInfo?: () => Promise<AppInfo>;
-  codeService: (action: string, payload: unknown) => Promise<CodeServiceResult | null>;
+  codeService: (action: string, payload: JsonValue) => Promise<CodeServiceResult | null>;
   resolveSiteContext: (filePath: string) => Promise<{
     sitePath: string | null;
     projectConfig?: ProjectConfig;
@@ -535,7 +534,7 @@ export interface StudioPlatform {
    */
   fetchProjectSchemas?: () => Promise<ProjectSchemasResponse>;
   /** Invoke a format capability (parse/serialize) — { format, action, source?, doc?, options? }. */
-  formatAction?: (payload: Record<string, unknown>) => Promise<unknown>;
+  formatAction?: (payload: FormatActionRequest) => Promise<JxMutableNode | string>;
   // ─── Data surface + secrets (owner console; specs/extensions.md §13) ────────
   // Optional as a family: backends without the connector data routes omit them all, and Studio
   // Hides the data grid and connection/push/test actions. Row CRUD is the ADMIN path — it
@@ -548,21 +547,21 @@ export interface StudioPlatform {
   dataPush?: (opts?: { connection?: string; dryRun?: boolean }) => Promise<DataPushResult>;
   /** Page a table's rows with introspected column metadata. */
   dataRows?: (query: DataRowsQuery) => Promise<DataRowsResult>;
-  dataInsertRow?: (req: DataRowInsert) => Promise<{ row: Record<string, unknown> }>;
-  dataUpdateRow?: (req: DataRowUpdate) => Promise<{ row: Record<string, unknown> }>;
+  dataInsertRow?: (req: DataRowInsert) => Promise<{ row: JsonObject }>;
+  dataUpdateRow?: (req: DataRowUpdate) => Promise<{ row: JsonObject }>;
   dataDeleteRow?: (req: DataRowDelete) => Promise<{ ok: boolean }>;
   /** Configured secret env-var NAMES — never values. */
   listSecrets?: () => Promise<string[]>;
   /** Write/remove secrets in the backend store (.dev.vars locally); names-only response. */
-  setSecrets?: (req: SecretsSetRequest) => Promise<SecretsSetResponse>;
-  fetchPluginSchema: (src: string, prototype?: string, base?: string) => Promise<unknown>;
+  setSecrets?: (req: KeyValuePatch) => Promise<SecretsSetResponse>;
+  fetchPluginSchema: (src: string, prototype?: string, base?: string) => Promise<JsonValue>;
   /**
    * Resolve a class-prototype config through the backend's `/__jx_resolve__` pipeline (with the
    * project's content types loaded) and return the parsed result. Used by the tab-bar's dynamic
    * route-param picker to enumerate ContentCollection entries. Optional: platforms without a
    * resolve backend omit it and the picker falls back to a plain fetch.
    */
-  resolveClass?: (body: Record<string, unknown>) => Promise<unknown>;
+  resolveClass?: (body: JsonObject) => Promise<JsonValue>;
   gitStatus: () => Promise<GitStatusResult>;
   gitBranches: () => Promise<GitBranchesResult>;
   gitLog: (limit?: number) => Promise<GitLogEntry[]>;
@@ -579,6 +578,16 @@ export interface StudioPlatform {
   gitDiscard: (files: string[]) => Promise<void>;
   gitClone?: (url: string) => Promise<{ ok: boolean; root: string }>;
   gitInit: () => Promise<void>;
+  /**
+   * True on a host whose git is the remote's: a commit lands on GitHub as it is made, a push is
+   * only a check that it did, and each branch is a session of its own, so a checkout reloads the
+   * window into that branch's session (the cloud). Absent means an ordinary working tree, where a
+   * commit is local until it is pushed and a checkout swaps files in place.
+   *
+   * A declaration rather than a method, because what differs is the meaning of the verbs every host
+   * has: the Publish workspace reads it to say what a verb will do (studio.md §22.8).
+   */
+  gitHosted?: boolean;
   /**
    * Build the site to its output directory, so a reader opens what the author is looking at.
    *
@@ -816,7 +825,7 @@ export interface StudioPlatform {
    * injects credentials — an OAuth token on the cloud platform, the user's pasted API token locally
    * — so no secret ever rides in the request body.
    */
-  cfApi?: (path: string, init?: { method?: string; body?: unknown }) => Promise<unknown>;
+  cfApi?: (path: string, init?: { method?: string; body?: unknown }) => Promise<JsonValue>;
   // ─── User settings (backend-persisted; undefined on dev-server) ─────────────
   /**
    * Read the user-level settings map (e.g. the AI connection parameters) from a backend store
@@ -834,7 +843,7 @@ export interface StudioPlatform {
    * held no settings could, and did, clear the credentials another window had just stored. It also
    * preserves keys this build does not know: one written by a newer version, or by hand.
    */
-  patchSettings?: (patch: SettingsPatch) => Promise<Record<string, string>>;
+  patchSettings?: (patch: KeyValuePatch) => Promise<Record<string, string>>;
   /**
    * Be told when the backend store changes — by another window, or by hand. Returns the
    * unsubscribe.
@@ -848,9 +857,9 @@ export interface StudioPlatform {
    * Watch the backend connection, on platforms whose transport can lose one.
    *
    * Only a socket-based launcher implements this: the dev server talks over `fetch` and has nothing
-   * to lose, and the electrobun launcher's RPC times a request out rather than dropping it. The
-   * chromium launcher holds one long-lived WebSocket, and when it died every call after it hung
-   * with no error anywhere — so the transport reports the state, and the studio says it out loud.
+   * to lose, The chromium launcher holds one long-lived WebSocket, and when it died every call
+   * after it hung with no error anywhere — so the transport reports the state, and the studio says
+   * it out loud.
    *
    * The handler is called on each transition, never repeatedly for one state.
    */
@@ -870,6 +879,8 @@ export interface ContentSectionEntry {
   source?: string;
   format?: string;
   schema?: ContentTypeSchema;
+  /** The field a file-backed collection's records are identified by (the loader's `idField`). */
+  idField?: string;
   $elements?: unknown[];
 }
 
@@ -937,5 +948,4 @@ export interface ProjectState {
   selectedPath: string | null;
   searchQuery: string;
   projectDirs?: string[];
-  [key: string]: unknown;
 }

package/src/ui/ai-credentials-form.ts

@@ -2,14 +2,14 @@
 /**
  * Ai-credentials-form.ts — reusable AI provider credentials form (key / model / endpoint).
  *
- * Embedded by every host that needs a provider configured — **Preferences › Assistant** (⌘,) and the
- * New Project modal's Import/Agent gates. All draft/model-list state lives inside the closure, so
- * multiple instances never share state. Persists via src/services/ai-settings.ts on Save.
+ * Embedded by every host that needs a provider configured — **Preferences › Assistant** (⌘,) and
+ * the New Project modal's Import/Agent gates. All draft/model-list state lives inside the closure,
+ * so multiple instances never share state. Persists via src/services/ai-settings.ts on Save.
  *
  * The interim `Assistant: Settings…` dialog that used to host it is deleted: a provider key is an
  * application setting, and the surface that owns application settings is also the one that can list
- * it and revoke it (§15). Nothing about this form changed for the move, which is the argument
- * for it having been a reusable form rather than a section of a dialog.
+ * it and revoke it (§15). Nothing about this form changed for the move, which is the argument for
+ * it having been a reusable form rather than a section of a dialog.
  *
  * This module is the FLOW; `surfaces/ai-credentials-form.json` is what it draws. It keeps the three
  * drafts, decides which credentials a listing is sent with, what Save persists and re-reads, and
@@ -19,8 +19,8 @@
  * `surfaces/ai-credentials-form.ts` for why that element is the mount point and why re-rendering
  * the gate cannot disturb it.
  *
- * @docs studio/ai
  * @license MIT
+ * @docs studio/ai
  */
 
 import { fetchAvailableModels, proxyModelsErrorMessage } from "../services/ai-models";
@@ -35,11 +35,8 @@ import {
 import { SETTINGS } from "../services/settings/definitions";
 import type { AiProvider } from "../services/ai-settings";
 import { createAiCredentialsSurface } from "../surfaces/ai-credentials-form";
-import type {
-  AiCredentialsSurface,
-  AiCredentialsView,
-  CredentialsModelRow,
-} from "../surfaces/ai-credentials-form";
+import type { AiCredentialsSurface, AiCredentialsView } from "../surfaces/ai-credentials-form";
+import type { SurfaceOption } from "./surface";
 
 /** The blurb a host that says nothing gets. */
 const DEFAULT_INTRO =
@@ -231,7 +228,7 @@ export function createAiCredentialsForm(opts: AiCredentialsFormOptions): AiCrede
         modelsError = `${upstreamMessage} — type the model ID directly instead.`;
       }
     } catch (error: unknown) {
-      modelsError = (error as Error).message || "Failed to fetch models";
+      modelsError = (error instanceof Error && error.message) || "Failed to fetch models";
     } finally {
       modelsLoading = false;
       opts.requestRender();
@@ -242,7 +239,7 @@ export function createAiCredentialsForm(opts: AiCredentialsFormOptions): AiCrede
    * The catalogue as rows — the list the combobox will draw, never a corpus it matches against. A
    * model with no name of its own is called by its id.
    */
-  function rows(): CredentialsModelRow[] {
+  function rows(): SurfaceOption[] {
     return availableModels.map((model) => ({ label: model.name, value: model.id }));
   }
 

package/src/ui/ai-model-picker.ts

@@ -22,8 +22,8 @@
  * A closure factory (precedent: `createComposer`, `createAiCredentialsForm`) so two hosts never
  * share a loading flag or a failed-fetch record.
  *
- * @docs studio/ai
  * @license MIT
+ * @docs studio/ai
  */
 
 import {
@@ -146,8 +146,8 @@ export function createModelPicker(opts: ModelPickerOptions): ModelPicker {
     failure = "";
     attempted = credentials;
     fetchAvailableModels({ credentials, force })
-      .catch((error: unknown) => {
-        failure = (error as Error).message || "Failed to fetch models";
+      .catch((error) => {
+        failure = (error instanceof Error && error.message) || "Failed to fetch models";
       })
       .finally(() => {
         loading = false;

package/src/ui/cf-account-picker.ts

@@ -19,12 +19,15 @@
  * The dialog itself is `src/surfaces/cf-account-picker.json`, a `jx-dialog`; this module is the
  * flow around it. It used to be a lit template rendered through `showDialog`, with its own
  * `repaint()` re-rendering the whole body into the slot's parent whenever anything landed — the
- * surface is reactive now, so a listing that arrives late, or a refusal, changes only what it names.
+ * surface is reactive now, so a listing that arrives late, or a refusal, changes only what it
+ * names.
  *
- * @docs studio/ai
  * @license MIT
+ * @docs studio/ai
  */
 
+import { errorMessage } from "@jxsuite/schema/parse";
+
 import { getPlatform, hasPlatform } from "../platform";
 import { notifyCredentialsChanged } from "../settings/preferences-accounts";
 import { openCfAccountPickerSurface } from "../surfaces/cf-account-picker";
@@ -40,11 +43,6 @@ function canPick(): boolean {
   return Boolean(platform.cfAccounts && platform.cfSelectAccount);
 }
 
-/** What a thrown thing says, for a line the reader has to act on. */
-function reasonOf(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
 /**
  * Ask which Cloudflare account this connection should use, and store the answer.
  *
@@ -83,7 +81,7 @@ export function openCfAccountPicker(): Promise<CfAccountSummary | null> {
         accounts = (await getPlatform().cfAccounts?.()) ?? [];
       } catch (error) {
         accounts = [];
-        failure = reasonOf(error);
+        failure = errorMessage(error);
       }
       /* `done` released the slot, so a late listing landing after a dismissal would otherwise be a
          write into a disposed surface. The lit version guarded the same moment by resolving its
@@ -108,7 +106,7 @@ export function openCfAccountPicker(): Promise<CfAccountSummary | null> {
         if (!settled) {
           /* The list survives a refusal, and the reason sits above it: listing again is not what
              would fix an account the broker will not accept, so this state offers no retry. */
-          handle.update({ choosing: "", failure: reasonOf(error) });
+          handle.update({ choosing: "", failure: errorMessage(error) });
         }
         return;
       }

package/src/ui/color-selector.ts

@@ -25,18 +25,22 @@
  * @docs studio/design/style-inspector
  */
 
+import { isNumber, isString } from "@jxsuite/schema/guards";
+
 import { activeTab } from "../workspace/workspace";
 import { getEffectiveStyle } from "../site-context";
 import { resolveTokenValue, tokenRefName } from "../style/token-ref";
 import { kebabToLabel } from "../utils/studio-utils";
 
 /**
- * One colour the project has named, as a swatch reads it.
+ * One colour the project has named, as a swatch reads it — the palette a Style or Content `color`
+ * row offers inside its picker.
  *
- * `Record<string, unknown>` because it is a `$map` item: a repeater's scope is a record, and a
- * shape that is not one cannot be read through `$map/item/...`.
+ * `value` and `color` are two fields because they are two things: choosing a swatch commits
+ * `var(--color-accent)`, while the chip is only how that reads on screen. A swatch is a `$map`
+ * item, read through `$map/item/...` by member name, so every member is a value a scope can hold.
  */
-export interface ColorTokenView extends Record<string, unknown> {
+export interface ColorTokenView {
   /** What choosing this swatch commits — the reference, never the literal behind it. */
   value: string;
   /** The chip's colour: how the token looks, which is not what it means. */
@@ -76,7 +80,7 @@ export function colorTokens(): ColorTokenView[] {
   const style = getEffectiveStyle(activeTab.value?.doc.document?.style);
   const tokens: ColorTokenView[] = [];
   for (const [name, value] of Object.entries(style)) {
-    if (name.startsWith("--color") && (typeof value === "string" || typeof value === "number")) {
+    if (name.startsWith("--color") && (isString(value) || isNumber(value))) {
       tokens.push({ color: String(value), label: varToLabel(name), value: `var(${name})` });
     }
   }

package/src/ui/dynamic-slot.ts

@@ -23,8 +23,10 @@ import { cloneValue } from "../tabs/doc-op-apply";
 import { activeTab } from "../workspace/workspace";
 import { slotMode } from "./value-source";
 
+import type { JxDocumentValue } from "@jxsuite/schema/types";
 import type { JsonValue } from "../types";
 import type { SlotMode } from "./value-source";
+import type { SurfaceOption } from "./surface";
 
 export type { SlotCapsSource, SlotMode, SlotPosition } from "./value-source";
 export { slotCaps, slotMode } from "./value-source";
@@ -96,7 +98,10 @@ function isTextEditRung(mode: SlotMode): boolean {
  * The rung to render this field at: the one it is already being edited at when a text edit could
  * explain the difference, otherwise whatever the document value says. Records its answer.
  */
-export function effectiveSlotMode(fieldKey: string, value: unknown): SlotMode {
+export function effectiveSlotMode(
+  fieldKey: string,
+  value: JxDocumentValue | JsonValue | undefined,
+): SlotMode {
   const key = fieldScopeKey(fieldKey);
   const sniffed = slotMode(value);
   const previous = slotModeRendered.get(key);
@@ -108,18 +113,12 @@ export function effectiveSlotMode(fieldKey: string, value: unknown): SlotMode {
   return mode;
 }
 
-/** One pointer the From data… rung may offer, as a picker option. */
-export interface SignalOption {
-  value: string;
-  label: string;
-}
-
 /** Where a rung's seed value comes from — the subset of a slot's options that decides one. */
 export interface SlotSeedSources {
   /** State keys the position may point at; the first is what a fresh binding lands on. */
   stateDefs: readonly string[];
   /** Extra pointers beyond `#/state/*` — route params, `$map/item`. */
-  extraSignals?: readonly SignalOption[] | null;
+  extraSignals?: readonly SurfaceOption[] | null;
   /** What Fixed value restores to. */
   literalDefault?: JsonValue | undefined;
 }