lumiverse-spindle-types 0.6.1 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "types": "./src/index.ts",
   "keywords": [
     "lumiverse",

package/src/api.ts

@@ -1101,6 +1101,14 @@ export interface PromptBlockCategoryGroupDTO {
   children: PromptBlockDTO[];
 }
 
+export interface HostResponseErrorDTO {
+  code: string;
+  message: string;
+  presetId?: string;
+  expectedCacheRevision?: number;
+  actualCacheRevision?: number;
+}
+
 export interface UserPresetDTO {
   id: string;
   name: string;
@@ -1110,6 +1118,7 @@ export interface UserPresetDTO {
   prompt_order: PromptBlockDTO[];
   prompts: Record<string, unknown>;
   metadata: Record<string, unknown>;
+  cache_revision: number;
   created_at: number;
   updated_at: number;
 }
@@ -1124,7 +1133,9 @@ export interface UserPresetCreateDTO {
   metadata?: Record<string, unknown>;
 }
 
-export type UserPresetUpdateDTO = Partial<UserPresetCreateDTO>;
+export type UserPresetUpdateDTO = Partial<UserPresetCreateDTO> & {
+  expected_cache_revision: number;
+};
 export type PromptBlockCreateDTO = Partial<PromptBlockDTO>;
 export type PromptBlockUpdateDTO = Partial<Omit<PromptBlockDTO, "id">>;
 
@@ -2824,7 +2835,7 @@ export type WorkerToHost =
       keys: string[];
     }
   | { type: "cors_request"; requestId: string; url: string; options: RequestInitDTO }
-  | { type: "register_context_handler"; priority?: number }
+  | { type: "register_context_handler"; priority?: number; timeoutMs?: number }
   | {
       type: "context_handler_result";
       requestId: string;
@@ -3234,7 +3245,7 @@ export type HostToWorker =
       type: "response";
       requestId: string;
       result?: unknown;
-      error?: string;
+      error?: string | HostResponseErrorDTO;
     }
   | {
       type: "permission_denied";

package/src/dom.ts

@@ -1,4 +1,4 @@
-import type { PromptBlockDTO, RequestInitDTO } from "./api";
+import type { PromptBlockDTO, PromptVariableValuesDTO, RequestInitDTO } from "./api";
 import type { SpindleComponentsHelper } from "./components";
 
 /** A chat-message DOM element paired with its stable message id. */
@@ -221,6 +221,21 @@ export interface SpindlePresetEditorTabHandle {
   onActivate(handler: () => void): () => void;
 }
 
+/** Extension-owned root placed above Loom's list and editor branches. */
+export interface SpindlePresetEditorToolbarItemOptions {
+  /** Unique toolbar item identifier within the current extension. */
+  id: string;
+  /** Required accessible label for the extension-owned toolbar root. */
+  ariaLabel: string;
+}
+
+export interface SpindlePresetEditorToolbarItemHandle {
+  readonly root: HTMLElement;
+  readonly itemId: string;
+  setVisible(visible: boolean): void;
+  destroy(): void;
+}
+
 /** Mutable, editor-native snapshot of the current Loom preset draft. */
 export interface SpindlePresetEditorDraft {
   id: string;
@@ -259,6 +274,38 @@ export interface SpindlePresetEditorHelper {
   ): void;
   /** Immediately persist and await any pending draft changes. */
   flush(): Promise<void>;
+  /**
+   * Cooperative, extension-identifier-scoped metadata access. This does not
+   * sandbox same-origin extension code; it prevents accidental whole-draft
+   * writes through the supported helper.
+   */
+  readonly extension: SpindlePresetEditorScopedHelper;
+}
+
+export type SpindlePresetEditorBuiltinTabId = "blocks";
+
+export interface SpindlePresetEditorExtensionState {
+  readonly open: boolean;
+  readonly presetId: string | null;
+  readonly activeTabId: string | null;
+  /** Detached array cloned from the host draft. */
+  readonly blocks: readonly PromptBlockDTO[];
+  /** Detached prompt-variable values cloned from the host draft. */
+  readonly promptVariableValues: Readonly<PromptVariableValuesDTO>;
+  /** The raw metadata value currently owned by the calling extension. */
+  readonly metadata: unknown;
+}
+
+export interface SpindlePresetEditorScopedHelper {
+  getState(): SpindlePresetEditorExtensionState;
+  onChange(handler: (state: SpindlePresetEditorExtensionState) => void): () => void;
+  setMetadata(value: Record<string, unknown>, options?: SpindlePresetEditorSaveOptions): void;
+  updateMetadata(
+    mutator: (current: unknown) => Record<string, unknown>,
+    options?: SpindlePresetEditorSaveOptions,
+  ): void;
+  activateBuiltinTab(tab: SpindlePresetEditorBuiltinTabId): void;
+  flush(): Promise<void>;
 }
 
 // ── Float Widget ──
@@ -824,6 +871,7 @@ export interface SpindleFrontendContext {
     registerCharacterEditorTab(options: SpindleCharacterEditorTabOptions): SpindleCharacterEditorTabHandle;
     characterEditor: SpindleCharacterEditorHelper;
     registerPresetEditorTab(options: SpindlePresetEditorTabOptions): SpindlePresetEditorTabHandle;
+    registerPresetEditorToolbarItem(options: SpindlePresetEditorToolbarItemOptions): SpindlePresetEditorToolbarItemHandle;
     presetEditor: SpindlePresetEditorHelper;
     createFloatWidget(options?: SpindleFloatWidgetOptions): SpindleFloatWidgetHandle;
     requestDockPanel(options: SpindleDockPanelOptions): SpindleDockPanelHandle;

package/src/index.ts

@@ -62,6 +62,7 @@ export type {
     PromptBlockCreateDTO,
     PromptBlockUpdateDTO,
     PromptBlockCategoryGroupDTO,
+    HostResponseErrorDTO,
     UserPresetDTO,
     UserPresetCreateDTO,
     UserPresetUpdateDTO,
@@ -224,10 +225,15 @@ export type {
   SpindleCharacterEditorHelper,
   SpindlePresetEditorTabOptions,
   SpindlePresetEditorTabHandle,
+  SpindlePresetEditorToolbarItemOptions,
+  SpindlePresetEditorToolbarItemHandle,
   SpindlePresetEditorDraft,
   SpindlePresetEditorState,
   SpindlePresetEditorSaveOptions,
   SpindlePresetEditorHelper,
+  SpindlePresetEditorBuiltinTabId,
+  SpindlePresetEditorExtensionState,
+  SpindlePresetEditorScopedHelper,
   SpindleFloatWidgetOptions,
   SpindleFloatWidgetHandle,
   SpindleDockEdge,

package/src/preset-editor.contract.ts

@@ -0,0 +1,31 @@
+import type { SpindleFrontendContext } from "./dom";
+
+/** Compile-time fixture for the additive preset-editor extension API. */
+export function verifyPresetEditorContract(ctx: SpindleFrontendContext): void {
+  const toolbar = ctx.ui.registerPresetEditorToolbarItem({
+    id: "mode-controls",
+    ariaLabel: "Agent mode controls",
+  });
+  toolbar.setVisible(true);
+  // @ts-expect-error Extension-owned handles do not expose mutable host identity.
+  toolbar.itemId = "replacement";
+  toolbar.destroy();
+
+  const editor = ctx.ui.presetEditor.extension;
+  // @ts-expect-error Scoped helpers are acquired from a read-only getter.
+  ctx.ui.presetEditor.extension = editor;
+  const state = editor.getState();
+  state.blocks.forEach((block) => block.id);
+  // @ts-expect-error Snapshot identity is host-owned.
+  state.open = true;
+  // @ts-expect-error Scoped metadata is a read-only host snapshot.
+  state.metadata = { mode: "replacement" };
+
+  editor.setMetadata({ mode: "parallel" }, { immediate: true });
+  editor.updateMetadata((current) => ({
+    ...(current && typeof current === "object" && !Array.isArray(current) ? current : {}),
+    revision: 1,
+  }));
+  editor.activateBuiltinTab("blocks");
+  void editor.flush();
+}

package/src/spindle-api.ts

@@ -1287,12 +1287,26 @@ export interface SpindleAPI {
   /** Make a CORS-proxied HTTP request */
   cors(url: string, options?: RequestInitDTO): Promise<unknown>;
 
-  /** Register a context handler for enriching generation context */
+  /**
+   * Register a context handler for enriching generation context, awaited
+   * before prompt assembly. The context carries `chatId`, `generationType`,
+   * `dryRun` (tokenize/preview assemblies) and `userId`, returning it with
+   * `cancelGeneration: true` stops the generation, and `opts.timeoutMs`
+   * overrides the default 10s wall-clock budget (clamped to 1s-120s).
+   */
   registerContextHandler(
     handler: (context: unknown) => Promise<unknown>,
-    priority?: number
+    priority?: number,
+    opts?: { timeoutMs?: number }
   ): void;
 
+  /**
+   * Host contract versions for feature detection, keyed by contract name.
+   * `preAssemblyGenerationContext >= 1`: generation contexts carry
+   * `dryRun`/`userId` and `cancelGeneration` is honored.
+   */
+  contracts?: Readonly<Record<string, number>>;
+
   /**
    * Register a macro interceptor (permission: `macro_interceptor`).
    *