@jxsuite/studio 6.1.1 → 8.0.0

package/src/surfaces/add-new.ts

@@ -0,0 +1,325 @@
+/// <reference lib="dom" />
+/**
+ * Add new as a mounted document.
+ *
+ * `create/add-new-flow.ts` is the flow — it holds the kind, the name and the options, reads the
+ * project into a `CreationContext`, lists the directories the result would write into, asks
+ * `deriveCreation` what that is and `creationProblem` whether it may, and performs the write — and
+ * this is the surface it draws into: the reactive scope the document reads, the few flags it
+ * branches on, and the mount that lives in the dialog layer until the flow takes it down.
+ *
+ * **The flow states facts; the surface derives the flags.** Whether the name field is drawn,
+ * whether the field is refused and whether the primary button can answer are each one comparison
+ * over the view, so they are made here rather than handed in beside the facts they restate.
+ *
+ * **Await the ELEMENT, not just the mount.** `mountSurface` resolving means the DOCUMENT rendered;
+ * a `jx-dialog`'s own template is one `connectedCallback` later, and `showModal` in between finds
+ * no `<dialog>` to open. `whenReady` is shared with `surfaces/dialog.ts` rather than
+ * reimplemented.
+ *
+ * @docs studio/projects/pages-layouts-components
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import { overlayRegion, REGION_ATTR } from "../ui/regions";
+import { close, showModal } from "@jxsuite/ui/behaviors/dialog";
+import { selectValue } from "@jxsuite/ui/behaviors/textfield";
+import { whenReady } from "./dialog";
+import addNewDoc from "./add-new.json";
+import type { CreationKind } from "../create/add-new";
+import type { SurfaceHandle, SurfaceOption } from "../ui/surface";
+
+registerSurface("add-new", addNewDoc);
+
+/** One kind in the left-hand list. */
+export interface AddNewKindRow {
+  id: CreationKind;
+  label: string;
+  hint: string;
+  icon: string;
+  /** `"true"` for the chosen kind: the row is one radio of a radiogroup. */
+  checked: "true" | "false";
+}
+
+/** One card in a Start from / Wrap it in radiogroup. */
+export interface AddNewChoiceRow {
+  value: string;
+  label: string;
+  /** The muted second line: "header + footer", "mostly writing", "2 elements". */
+  note: string;
+  checked: "true" | "false";
+  /** A choice that cannot be made now stays in the group, disabled, with `reason` as its tip. */
+  disabled: boolean;
+  reason: string;
+}
+
+/** One field preset chip. */
+export interface AddNewPresetRow {
+  id: string;
+  label: string;
+  selected: boolean;
+  icon: string;
+}
+
+/** What the flow knows. Every one of these may change while the dialog is up. */
+export interface AddNewView {
+  kind: CreationKind;
+  kinds: AddNewKindRow[];
+  /** The chosen kind's label, which names the detail region. */
+  kindLabel: string;
+  /** The sentence that introduces the chosen kind. */
+  kindHint: string;
+  /** Where the dialog can be opened from, said once at the foot of the list. */
+  chordNote: string;
+  nameLabel: string;
+  name: string;
+  placeholder: string;
+  /** The refusal under the name field; `""` until the reader has typed, and when there is none. */
+  error: string;
+  /** The derived result: "Saved as pages/pricing.json · opens at /pricing". */
+  saved: string;
+  /** The primary button's words. */
+  cta: string;
+  /** Whether the primary button can answer now. */
+  canConfirm: boolean;
+
+  // ── language (page, entry, collection) ────────────────────────────────────
+  /** Whether the Language picker is drawn: a page, or an entry of a localized collection. */
+  localeShown: boolean;
+  localeOptions: SurfaceOption[];
+  /** The chosen language, a declared tag. */
+  locale: string;
+  /** Whether the project declares languages, which is when a collection can be localized. */
+  localizable: boolean;
+  /** Collection: one folder per language. */
+  localized: boolean;
+  /** The declared tags, said on the collection's checkbox: "en, fr-CA, ar". */
+  localeSummary: string;
+
+  // ── page ──────────────────────────────────────────────────────────────────
+  route: string;
+  editingUrl: boolean;
+  url: string;
+  startChoices: AddNewChoiceRow[];
+
+  // ── collection ────────────────────────────────────────────────────────────
+  itemNoun: string;
+  presets: AddNewPresetRow[];
+  ownPage: boolean;
+  pattern: string;
+  templateOptions: SurfaceOption[];
+  pageTemplate: string;
+
+  // ── template ──────────────────────────────────────────────────────────────
+  wrapChoices: AddNewChoiceRow[];
+
+  // ── component ─────────────────────────────────────────────────────────────
+  componentChoices: AddNewChoiceRow[];
+  copying: boolean;
+  copyOptions: SurfaceOption[];
+  copyOf: string;
+
+  // ── entry ─────────────────────────────────────────────────────────────────
+  collectionOptions: SurfaceOption[];
+  collection: string;
+
+  // ── media ─────────────────────────────────────────────────────────────────
+  dropActive: "true" | "false";
+  uploadAccept: string;
+  fileSummary: string;
+}
+
+/** What the document can tell the flow. */
+export interface AddNewActions {
+  pickKind: (kind: CreationKind) => void;
+  setName: (value: string) => void;
+  /** The primary button, or Enter in a field. The flow decides whether that creates anything. */
+  confirm: () => void;
+  toggleUrl: () => void;
+  setUrl: (value: string) => void;
+  pickStart: (value: string) => void;
+  togglePreset: (id: string) => void;
+  setOwnPage: (checked: boolean) => void;
+  pickPageTemplate: (value: string) => void;
+  pickWrap: (value: string) => void;
+  pickComponentStart: (value: string) => void;
+  pickCopy: (value: string) => void;
+  pickCollection: (value: string) => void;
+  pickLocale: (value: string) => void;
+  setLocalized: (checked: boolean) => void;
+  /**
+   * The file picker settled. The ELEMENT rather than its list, because a file input that is not
+   * cleared refuses the same file twice, and the input is this document's own control.
+   */
+  choose: (input: HTMLInputElement) => void;
+  drop: (files: FileList | null) => void;
+  dragOver: () => void;
+  dragOut: () => void;
+  /** The dialog closed, for any reason the platform owns as well as the flow's own `close`. */
+  closed: () => void;
+}
+
+export interface AddNewSurfaceOptions {
+  /** Where the dialog is mounted — the dialog layer, handed in so this module never reaches back. */
+  layer: HTMLElement;
+  view: AddNewView;
+  actions: AddNewActions;
+}
+
+export interface AddNewSurfaceHandle {
+  host: HTMLElement;
+  /** Resolves with the `jx-dialog` element once it has rendered and been opened. */
+  ready: Promise<HTMLElement>;
+  /** Redraw from the flow's current view. */
+  update: (view: AddNewView) => void;
+  /** Close the dialog (the platform restores focus) and dispose the document. Idempotent. */
+  close: () => void;
+}
+
+/** What the document branches on. Derived, never handed in. */
+interface AddNewFlags {
+  /** Every kind but Media has a name. */
+  named: boolean;
+  invalid: boolean;
+  blocked: boolean;
+}
+
+type AddNewScope = AddNewView &
+  AddNewFlags &
+  Omit<AddNewActions, "setName" | "closed"> & {
+    setName: (value: string) => void;
+    closed: () => void;
+  };
+
+/** The view plus the flags the document renders from. */
+function derive(view: AddNewView): AddNewView & AddNewFlags {
+  return {
+    ...view,
+    blocked: !view.canConfirm,
+    invalid: view.error !== "",
+    named: view.kind !== "media",
+  };
+}
+
+/** Open the dialog. The handle's `ready` resolves once it is showing. */
+export function openAddNewSurface(options: AddNewSurfaceOptions): AddNewSurfaceHandle {
+  const slot = document.createElement("div");
+  /* The layer is `pointer-events: none` so a click passes through it when nothing is up, and every
+     slot in it turns them back on for its own content. `pointer-events` INHERITS, and the top layer
+     changes paint order rather than inheritance, so a modal `<dialog>` in a slot that skipped this
+     is painted above everything and hit-tests to nothing. */
+  slot.style.pointerEvents = "auto";
+  slot.setAttribute(REGION_ATTR, overlayRegion("dialog", "add-new"));
+  options.layer.append(slot);
+
+  let closed = false;
+  /** Say it is over, once: the platform's own `close` and `close()` may each be first. */
+  const finish = (): void => {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    options.actions.closed();
+  };
+  const isClosed = (): boolean => closed;
+
+  const { actions } = options;
+  const scope: AddNewScope = reactive<AddNewScope>({
+    ...derive(options.view),
+    choose: actions.choose,
+    closed: finish,
+    confirm: actions.confirm,
+    dragOut: actions.dragOut,
+    dragOver: actions.dragOver,
+    drop: actions.drop,
+    pickCollection: actions.pickCollection,
+    pickComponentStart: actions.pickComponentStart,
+    pickCopy: actions.pickCopy,
+    pickKind: actions.pickKind,
+    pickLocale: actions.pickLocale,
+    pickPageTemplate: actions.pickPageTemplate,
+    pickStart: actions.pickStart,
+    pickWrap: actions.pickWrap,
+    setName: (value: string) => {
+      /* What the control holds, first and unconditionally. A binding only writes when the scope
+         CHANGES, so a surface that did not echo the raw value would leave the field showing text
+         the scope does not have (`studio-ui-guidelines.md` §9.3). */
+      scope.name = value;
+      actions.setName(value);
+    },
+    setLocalized: actions.setLocalized,
+    setOwnPage: actions.setOwnPage,
+    setUrl: (value: string) => {
+      scope.url = value;
+      actions.setUrl(value);
+    },
+    toggleUrl: actions.toggleUrl,
+    togglePreset: actions.togglePreset,
+  });
+
+  let mounted: SurfaceHandle | null = null;
+
+  /**
+   * Put the caret in the name field, selected.
+   *
+   * On open only: the name is the only thing the dialog requires, so it is where the reader is
+   * about to type. A focus move is the one thing a surface may reach into its document for (`ui.md`
+   * §2 rule 5).
+   */
+  const focusName = (): void => {
+    setTimeout(() => {
+      const root = mounted?.root;
+      if (closed || !(root instanceof HTMLElement)) {
+        return;
+      }
+      const control = root.querySelector<HTMLElement>('jx-textfield[part="name"]');
+      if (control) {
+        selectValue(control, "all");
+      }
+    }, 0);
+  };
+
+  const ready = mountSurface("add-new", scope, slot).then(async (surface) => {
+    mounted = surface;
+    /* SAFETY: `add-new.json`'s root definition is a `jx-dialog` element, so the runtime mounts an
+       HTMLElement; a `Text` root only comes from a document whose root is a bare string. */
+    const element = surface.root as HTMLElement;
+    if (isClosed()) {
+      surface.dispose();
+      return element;
+    }
+    await whenReady(element);
+    if (isClosed()) {
+      return element;
+    }
+    showModal(element);
+    if (scope.named) {
+      focusName();
+    }
+    return element;
+  });
+
+  return {
+    close() {
+      /* Idempotent line by line rather than guarded on `closed`: the platform's own `close` runs
+         `finish()` first, and a guard would leave this slot behind in the layer. */
+      const element = mounted?.root;
+      if (element instanceof HTMLElement) {
+        close(element);
+      }
+      mounted?.dispose();
+      mounted = null;
+      slot.remove();
+      finish();
+    },
+    host: slot,
+    ready,
+    update(view) {
+      /* Never a focus move here. A kind switch from the keyboard is an arrow key inside the kinds
+         radiogroup, and pulling the caret into the name field would end the walk after one step;
+         the name keeps its value across kinds and Tab reaches it next. */
+      Object.assign(scope, derive(view));
+    },
+  };
+}

package/src/surfaces/add-repo.ts

@@ -31,14 +31,13 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import { overlayRegion, REGION_ATTR } from "../ui/regions";
-import { close as closeDialog, showModal } from "@jxsuite/ui/behaviors/dialog";
+import { close, showModal } from "@jxsuite/ui/behaviors/dialog";
 import { focusField } from "@jxsuite/ui/behaviors/textfield";
 import { whenReady } from "./dialog";
 import addRepoDoc from "./add-repo.json";
-import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle, SurfaceOption } from "../ui/surface";
 
-registerSurface("add-repo", addRepoDoc as unknown as JxDocument);
+registerSurface("add-repo", addRepoDoc);
 
 /** One repository, as the list draws it. Every field is already a string or a flag. */
 export interface AddRepoRow {
@@ -68,12 +67,6 @@ export interface AddRepoAccessLink {
   title: string;
 }
 
-/** One entry of the account filter. `""` is every account. */
-export interface AddRepoOwner {
-  value: string;
-  label: string;
-}
-
 /**
  * Why the repository list is empty, when it is.
  *
@@ -105,7 +98,7 @@ export interface AddRepoView {
   /** The account the list is narrowed to; `""` is every account. */
   owner: string;
   /** The account filter's entries, "All accounts" first; empty hides it (one account, or none). */
-  owners: AddRepoOwner[];
+  owners: SurfaceOption[];
   /** The listing is in flight. Its own state, because "not yet asked" is not "reaches nothing". */
   loading: boolean;
   /** The repositories to draw, already filtered and ordered. */
@@ -226,8 +219,7 @@ interface AddRepoFlags {
   confirmDisabled: boolean;
 }
 
-interface AddRepoScope
-  extends Record<string, unknown>, Omit<AddRepoView, "rows" | "locations">, AddRepoFlags {
+interface AddRepoScope extends Omit<AddRepoView, "rows" | "locations">, AddRepoFlags {
   setFilter: (value: string) => void;
   setOwner: (value: string) => void;
   select: (fullName: string) => void;
@@ -277,7 +269,7 @@ function derive(view: AddRepoView): Omit<AddRepoView, "rows" | "locations"> & Ad
       ? "loading"
       : rows.length > 0
         ? "listed"
-        : (`empty-${view.emptyState}` as AddRepoFlags["listState"]),
+        : (`empty-${view.emptyState}` as const),
     locations,
     refreshDisabled: view.loading || view.busy,
     rows,
@@ -309,8 +301,12 @@ export function openAddRepoSurface(options: AddRepoSurfaceOptions): AddRepoSurfa
     closed = true;
     options.onClosed();
   };
+  /* Read through a call, not the bare binding: `close()` can run while the mount is awaiting the
+     element, and a direct `closed` test after that `await` would be narrowed to the value the test
+     before it saw. */
+  const isClosed = (): boolean => closed;
 
-  const scope = reactive({
+  const scope: AddRepoScope = reactive<AddRepoScope>({
     ...derive(options.view),
     closed: finish,
     confirm: () => {
@@ -350,18 +346,20 @@ export function openAddRepoSurface(options: AddRepoSurfaceOptions): AddRepoSurfa
       scope.owner = value;
       options.onOwner(value);
     },
-  }) as AddRepoScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
   const ready = mountSurface("add-repo", scope, slot).then(async (surface) => {
     mounted = surface;
+    // SAFETY: `add-repo.json`'s root definition carries `tagName: "jx-dialog"`, so the runtime mounts an
+    // HTMLElement; a `Text` root only comes from a document whose root is a bare string.
     const element = surface.root as HTMLElement;
-    if (closed) {
+    if (isClosed()) {
       surface.dispose();
       return element;
     }
     await whenReady(element);
-    if (closed) {
+    if (isClosed()) {
       return element;
     }
     showModal(element);
@@ -384,7 +382,7 @@ export function openAddRepoSurface(options: AddRepoSurfaceOptions): AddRepoSurfa
       const element = mounted?.root;
       if (element instanceof HTMLElement) {
         // The platform's close first, so focus goes back where it came from; then the document.
-        closeDialog(element);
+        close(element);
       }
       // A mount that has not landed yet is disposed by `ready` when it does — `finish` tells it so.
       mounted?.dispose();

package/src/surfaces/ai-chat.ts

@@ -27,15 +27,16 @@
  * @docs studio/ai/chat
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { trustedHtml } from "../services/trusted-types";
 import { mountSurface, registerSurface } from "../ui/surface";
 import aiChatDoc from "./ai-chat.json";
-import type { JxElement, JxDocument } from "@jxsuite/schema/types";
+import type { JsonObject, JxElement } from "@jxsuite/schema/types";
 import type { JxScope } from "@jxsuite/runtime/types";
-import type { SurfaceHandle } from "../ui/surface";
+import type { KeyedLabel, SurfaceHandle } from "../ui/surface";
 
-registerSurface("ai-chat", aiChatDoc as unknown as JxDocument);
+registerSurface("ai-chat", aiChatDoc);
 
 /** How close (px) to the bottom of a scroller still counts as "following along". */
 const STICK_THRESHOLD = 48;
@@ -51,7 +52,7 @@ const LOG_STICK_THRESHOLD = 24;
  * rendering of the registry rather than a second place its capabilities are decided
  * (`studio-ui-guidelines.md` §12.5).
  */
-export interface ChatCommandView extends Record<string, unknown> {
+export interface ChatCommandView {
   /** The reconcile key. The command id, because a button is drawn once per bar. */
   key: string;
   /** What `run` is given. */
@@ -68,14 +69,8 @@ export interface ChatCommandView extends Record<string, unknown> {
   disabled: boolean;
 }
 
-/** One answer an `ask_user` card offers as a shortcut. */
-export interface ChatAskOption extends Record<string, unknown> {
-  key: string;
-  label: string;
-}
-
 /** One line an import run has reported. */
-export interface ChatLogLine extends Record<string, unknown> {
+export interface ChatLogLine {
   key: string;
   phase: string;
   message: string;
@@ -88,7 +83,7 @@ export interface ChatLogLine extends Record<string, unknown> {
  * `$switch` chooses on one: a chip that omitted `options` would leave the question case reading an
  * absent path.
  */
-export interface ChatChipView extends Record<string, unknown> {
+export interface ChatChipView {
   /** The tool-call id — the reconcile key. */
   key: string;
   /** The tool's name, for a test and for the `data-tool` attribute. */
@@ -114,7 +109,8 @@ export interface ChatChipView extends Record<string, unknown> {
   hasContext: boolean;
   /** `pending`, `unanswered`, `answered`, `failed` or `none` — which half of the card to draw. */
   askState: string;
-  options: ChatAskOption[];
+  /** The answers an `ask_user` card offers as shortcuts. */
+  options: KeyedLabel[];
   /** What the reader replied, once they have. */
   answer: string;
   /** `run` when this call has an import to report, `none` otherwise. */
@@ -133,7 +129,7 @@ export interface ChatChipView extends Record<string, unknown> {
 }
 
 /** One file a turn changed. */
-export interface ChatChangeView extends Record<string, unknown> {
+export interface ChatChangeView {
   key: string;
   path: string;
   /** The tool that wrote it, or the sentence saying why it did not. */
@@ -143,14 +139,8 @@ export interface ChatChangeView extends Record<string, unknown> {
   disk: boolean;
 }
 
-/** One attached-context chip on a user turn. */
-export interface ChatContextChip extends Record<string, unknown> {
-  key: string;
-  label: string;
-}
-
 /** One line of the transcript. */
-export interface ChatRowView extends Record<string, unknown> {
+export interface ChatRowView {
   /** The message id. The `$map` key, and what `restore` is given. */
   key: string;
   /** `user`, `assistant`, `streaming`, `typing` or `tool-error`. */
@@ -159,7 +149,8 @@ export interface ChatRowView extends Record<string, unknown> {
   body: string;
   /** Sanitized model output for an `assistant` row. Filled into the island, never bound. */
   markdown: string;
-  contextChips: ChatContextChip[];
+  /** The attached-context chips on a user turn. */
+  contextChips: KeyedLabel[];
   hasContextChips: boolean;
   chips: ChatChipView[];
   hasChips: boolean;
@@ -172,7 +163,7 @@ export interface ChatRowView extends Record<string, unknown> {
 }
 
 /** One row of the chat history. */
-export interface ChatSessionView extends Record<string, unknown> {
+export interface ChatSessionView {
   /** The session id — the key, and what a row opens or deletes. */
   key: string;
   title: string;
@@ -181,7 +172,7 @@ export interface ChatSessionView extends Record<string, unknown> {
 }
 
 /** One chip the composer is carrying. */
-export interface ChatComposerChip extends Record<string, unknown> {
+export interface ChatComposerChip {
   /** The chip's kind — one chip per kind, so the kind IS the identity. */
   key: string;
   label: string;
@@ -277,7 +268,7 @@ export interface AiChatSurface {
 }
 
 /** The scope the document reads: the view, the flow's actions, and the scroller's own handler. */
-interface AiChatScope extends Record<string, unknown>, AiChatView, AiChatActions {
+interface AiChatScope extends AiChatView, AiChatActions {
   scrolled: () => void;
 }
 
@@ -353,21 +344,21 @@ export function emptyAiChatView(): AiChatView {
 
 /** The `part` a node's definition carries, or "" for a text node or an unmarked element. */
 function partOf(def: JxElement | string): string {
-  const part = typeof def === "string" ? undefined : def.attributes?.["part"];
-  return typeof part === "string" ? part : "";
+  const part = isString(def) ? undefined : def.attributes?.["part"];
+  return isString(part) ? part : "";
 }
 
 /** The `$map` item a node was rendered inside, if it was rendered inside one. */
-function mapItem(state: JxScope | undefined): Record<string, unknown> | null {
-  const map = state?.["$map"] as { item?: unknown } | undefined;
-  const item = map?.item;
-  return item !== null && typeof item === "object" ? (item as Record<string, unknown>) : null;
+function mapItem(state: JxScope | undefined): JsonObject | null {
+  const map = state?.["$map"];
+  const item = isJsonObject(map) ? map["item"] : undefined;
+  return isJsonObject(item) ? item : null;
 }
 
 /** A string field off a `$map` item, or "". */
-function itemString(item: Record<string, unknown> | null, field: string): string {
+function itemString(item: JsonObject | null, field: string): string {
   const value = item?.[field];
-  return typeof value === "string" ? value : "";
+  return isString(value) ? value : "";
 }
 
 /** Keep a scroller pinned to its newest line, unless the reader has scrolled away from it. */
@@ -406,7 +397,7 @@ export function mountAiChatSurface(
   /** The import logs, by chip key. */
   const logs = new Map<string, HTMLElement>();
 
-  const scope = reactive<AiChatScope>({
+  const scope: AiChatScope = reactive<AiChatScope>({
     ...emptyAiChatView(),
     ...actions,
     scrolled: () => {
@@ -416,7 +407,7 @@ export function mountAiChatSurface(
           STICK_THRESHOLD;
       }
     },
-  }) as AiChatScope;
+  });
   project(scope, view);
 
   /**
@@ -451,7 +442,11 @@ export function mountAiChatSurface(
    * value assigned here is a `TrustedHTML`; without one the same assertion has still run.
    */
   function fillIsland(node: HTMLElement, html: string): void {
-    (node as unknown as { innerHTML: unknown }).innerHTML = trustedHtml(html);
+    /* SAFETY: lib.dom declares `innerHTML` as `string`, but the setter's IDL type is
+       `(TrustedHTML or DOMString)`, and `trustedHtml` returns one of exactly those two: the policy's
+       `TrustedHTML`, or the asserted string where the API is absent. Widening the property to what
+       the sink accepts is an upcast of this HTMLElement, so the write reaches the same setter. */
+    (node as { innerHTML: unknown }).innerHTML = trustedHtml(html);
   }
 
   let mounted: SurfaceHandle | null = null;
@@ -519,8 +514,8 @@ export function mountAiChatSurface(
     }
   }
 
-  /* There is no `connected()` here, where `doc-header.ts` and `panel-stylebook-layers.ts` both
-     have one. Those two mount into a node LIT repaints, so "is my root still where I put it" is a
+  /* There is no `connected()` here, where `panel-stylebook-layers.ts` has one. That one mounts
+     into a node LIT repaints, so "is my root still where I put it" is a
      live question. The assistant's container is built once for the life of the window
      (`right-panel.ts`'s `_ensureContainers`) and nothing else ever writes into it, so the answer
      would be a constant — and a constant nobody reads is a second thing to keep in step. */

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

@@ -29,18 +29,9 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import credentialsDoc from "./ai-credentials-form.json";
-import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle, SurfaceOption } from "../ui/surface";
 
-registerSurface("ai-credentials-form", credentialsDoc as unknown as JxDocument);
-
-/** One row of the listed catalogue, as the combobox draws it. */
-export interface CredentialsModelRow {
-  /** The model id — the row's key, and what a pick writes into the model draft. */
-  value: string;
-  /** What the row reads. */
-  label: string;
-}
+registerSurface("ai-credentials-form", credentialsDoc);
 
 /** What the form says right now. Every field is the flow's, never a state it derives. */
 export interface AiCredentialsView {
@@ -51,7 +42,7 @@ export interface AiCredentialsView {
   modelDraft: string;
   baseUrlDraft: string;
   /** The catalogue the last successful listing returned; empty draws no chevron on the field. */
-  models: CredentialsModelRow[];
+  models: SurfaceOption[];
   /** A listing is in flight: the button says so and refuses a second one. */
   modelsLoading: boolean;
   /** What the fetch button reads — including while it is working, and once a list has landed. */
@@ -88,11 +79,10 @@ interface AiCredentialsFlags {
   /** Whether there is a refusal to draw beside the fetch button. */
   hasError: boolean;
   /** The catalogue as the kit's combobox draws it — the list, never a corpus it matches against. */
-  modelOptions: CredentialsModelRow[];
+  modelOptions: SurfaceOption[];
 }
 
-interface AiCredentialsScope
-  extends Record<string, unknown>, AiCredentialsView, AiCredentialsActions, AiCredentialsFlags {}
+interface AiCredentialsScope extends AiCredentialsView, AiCredentialsActions, AiCredentialsFlags {}
 
 /** The view plus the flags the document renders from. */
 function derive(view: AiCredentialsView): AiCredentialsView & AiCredentialsFlags {
@@ -119,7 +109,7 @@ export function createAiCredentialsSurface(
 ): AiCredentialsSurface {
   const host = document.createElement("div");
   host.style.display = "contents";
-  const scope = reactive({ ...derive(view), ...actions }) as AiCredentialsScope;
+  const scope: AiCredentialsScope = reactive<AiCredentialsScope>({ ...derive(view), ...actions });
 
   /** `null` while a mount is in flight — which is a standing surface, not a missing one. */
   let handle: SurfaceHandle | null = null;