lumiverse-spindle-types 0.6.2 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "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">>;
 
@@ -3234,7 +3245,7 @@ export type HostToWorker =
       type: "response";
       requestId: string;
       result?: unknown;
-      error?: string;
+      error?: string | HostResponseErrorDTO;
     }
   | {
       type: "permission_denied";

package/src/components.ts

@@ -22,6 +22,33 @@
  * Components inherit the active Lumiverse theme via CSS variables, so they
  * visually match the rest of the host UI without any additional wiring.
  */
+import type { PromptBlockDTO, PromptVariableValuesDTO } from "./api";
+
+// ──────────────────────────────────────────────────────────────────────────
+// Loom block editor
+// ──────────────────────────────────────────────────────────────────────────
+
+/** Editable public value rendered by the native Loom block editor. */
+export interface SpindleLoomBlockEditorValue {
+  blocks: PromptBlockDTO[];
+  promptVariableValues: PromptVariableValuesDTO;
+}
+
+/** Controlled options for the native Loom block editor. */
+export interface SpindleLoomBlockEditorOptions {
+  value: SpindleLoomBlockEditorValue;
+  onChange?: (value: SpindleLoomBlockEditorValue) => void;
+  readOnly?: boolean;
+  compact?: boolean;
+}
+
+/** Handle returned by `mountLoomBlockEditor`. */
+export interface SpindleLoomBlockEditorHandle
+  extends SpindleMountedComponent<SpindleLoomBlockEditorOptions> {
+  getValue(): SpindleLoomBlockEditorValue;
+  refreshMacros(): Promise<void>;
+}
+
 
 // ──────────────────────────────────────────────────────────────────────────
 // Shared base shapes
@@ -39,10 +66,7 @@ export interface SpindleMountedComponent<TOptions> {
   readonly componentId: string;
   /** The container element the component was mounted into. Same node passed as `target`. */
   readonly element: HTMLElement;
-  /**
-   * Merge a partial set of options into the live component. Pass any subset of
-   * the original mount options — undefined fields are ignored.
-   */
+  /** Merge supplied option fields into the live component. Omitted fields remain unchanged. */
   update(patch: Partial<TOptions>): void;
   /** Unmount the React tree and release host resources. The target element is left in place. */
   destroy(): void;
@@ -655,4 +679,9 @@ export interface SpindleComponentsHelper {
   mountCollapsibleSection(target: SpindleComponentTarget, options: SpindleCollapsibleSectionOptions): SpindleCollapsibleSectionHandle;
   mountPagination(target: SpindleComponentTarget, options: SpindlePaginationOptions): SpindlePaginationHandle;
   mountCloseButton(target: SpindleComponentTarget, options?: SpindleCloseButtonOptions): SpindleCloseButtonHandle;
+  // Loom editor
+  mountLoomBlockEditor(
+    target: SpindleComponentTarget,
+    options: SpindleLoomBlockEditorOptions,
+  ): SpindleLoomBlockEditorHandle;
 }

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,
@@ -313,6 +319,9 @@ export type {
   SpindlePaginationHandle,
   SpindleCloseButtonOptions,
   SpindleCloseButtonHandle,
+  SpindleLoomBlockEditorValue,
+  SpindleLoomBlockEditorOptions,
+  SpindleLoomBlockEditorHandle,
   SpindleComponentsHelper,
 } from "./components";
 

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/test/loom-block-editor-consumer.ts

@@ -0,0 +1,39 @@
+import type {
+  SpindleComponentTarget,
+  SpindleComponentsHelper,
+  SpindleLoomBlockEditorHandle,
+  SpindleLoomBlockEditorOptions,
+  SpindleLoomBlockEditorValue,
+} from "lumiverse-spindle-types";
+
+/**
+ * Package-root consumer fixture: this function is never called at runtime.
+ * Its body intentionally exercises the complete controlled Loom editor API so
+ * a consumer is checked against the package entry point rather than an
+ * internal source module.
+ */
+export function compileLoomBlockEditorContract(
+  helper: SpindleComponentsHelper,
+  target: SpindleComponentTarget,
+  options: SpindleLoomBlockEditorOptions,
+): Promise<void> {
+  const handle: SpindleLoomBlockEditorHandle = helper.mountLoomBlockEditor(target, options);
+  const initial: SpindleLoomBlockEditorValue = handle.getValue();
+
+  handle.update({
+    value: initial,
+    onChange: (next: SpindleLoomBlockEditorValue) => {
+      const checked: SpindleLoomBlockEditorValue = next;
+      void checked;
+    },
+    readOnly: !options.readOnly,
+    compact: !options.compact,
+  });
+
+  const updated: SpindleLoomBlockEditorValue = handle.getValue();
+  const refreshed: Promise<void> = handle.refreshMacros();
+  handle.destroy();
+
+  void updated;
+  return refreshed;
+}

package/tsconfig.consumer.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "./.consumer-dist",
+    "declaration": false
+  },
+  "include": ["test/loom-block-editor-consumer.ts"]
+}

package/tsconfig.json

@@ -6,7 +6,8 @@
     "strict": true,
     "declaration": true,
     "skipLibCheck": true,
-    "outDir": "./dist"
+    "outDir": "./dist",
+    "rootDir": "./src"
   },
   "include": ["src"]
 }