lumiverse-spindle-types 0.6.8 → 0.6.10

package/package.json

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

package/src/api.ts

@@ -65,6 +65,7 @@ export interface LlmMessageDTO {
    * Source message's `index_in_chat`, paired with `sourceMessageId`. 
    */
   sourceIndexInChat?: number;
+  sourceMessageMetadata?: Readonly<Record<string, unknown>>;
 }
 
 export type SpindleUserRoleDTO = "operator" | "admin" | "user";
@@ -120,6 +121,8 @@ export interface InterceptorContextDTO {
   readonly characterId: string | null;
   readonly personaAddonStates: Readonly<Record<string, boolean>>;
   readonly excludeMessageId?: string;
+  readonly activatedWorldInfo?: readonly ActivatedWorldInfoEntryDTO[];
+  readonly capturedWorldInfo?: readonly ActivatedWorldInfoEntryDTO[];
   readonly rejectedSwipe?: string;
   readonly regenFeedback?: string;
   readonly regenFeedbackPosition?: "system" | "user";
@@ -136,8 +139,17 @@ export interface InterceptorContextDTO {
   readonly signal: AbortSignal;
 }
 
+/**
+ * Deferred system guidance retained by the host terminal lease.
+ *
+ * A result may contain at most 128 entries. IDs must be unique canonical UUIDs
+ * (versions 1-5). Content must be non-empty, at most 1 MiB per entry when
+ * UTF-8 encoded, and at most 2 MiB across the result.
+ */
 export interface DeferredGuidanceDTO {
+  /** Unique canonical UUID (versions 1-5) within this interceptor result. */
   id: string;
+  /** Non-empty system guidance bounded by the limits above. */
   content: string;
   role: "system";
 }
@@ -240,11 +252,25 @@ export type MacroInterceptorPhase =
  * them has no effect on the real environment. Persist state via
  * `spindle.variables.*` helpers instead.
  */
+export type MacroInterceptorCharacterEnvDTO =
+  Readonly<Record<string, unknown>> & {
+    /** Selected greeting stored in the current chat, including edits. */
+    readonly firstMessage: string;
+    /** Card-defined alternatives, excluding the default greeting. */
+    readonly alternateGreetings: readonly string[];
+  };
+
+export type MacroInterceptorChatEnvDTO =
+  Readonly<Record<string, unknown>> & {
+    /** Selected index in [default greeting, ...alternate greetings]. */
+    readonly greetingIndex: number;
+  };
+
 export interface MacroInterceptorEnvDTO {
   readonly commit: boolean;
   readonly names: Record<string, string>;
-  readonly character: Record<string, unknown>;
-  readonly chat: Record<string, unknown>;
+  readonly character: MacroInterceptorCharacterEnvDTO;
+  readonly chat: MacroInterceptorChatEnvDTO;
   readonly system: Record<string, unknown>;
   readonly variables: {
     readonly local: Record<string, string>;
@@ -325,6 +351,8 @@ export interface MessageContentProcessorCtxDTO {
   /** Undefined for `"create"` origins (the row doesn't exist yet). */
   messageId?: string;
   content: string;
+  /** True when the message was authored by the user. */
+  isUser: boolean;
   extra?: Record<string, unknown>;
   origin: MessageContentProcessorOrigin;
   /** Set for `"swipe_update"` only — the zero-based index of the swipe being rewritten. */
@@ -1268,7 +1296,20 @@ export type PromptBlockRoleDTO = "system" | "user" | "assistant" | "user_append"
 export type PromptBlockPositionDTO = "pre_history" | "post_history" | "in_history";
 export type PromptBlockCategoryModeDTO = "radio" | "checkbox" | null;
 
-export interface PromptBlockDTO {
+/** A native Loom placement profile selected for a prompt block. */
+export interface PromptBlockPlacementDTO {
+  role: PromptBlockRoleDTO;
+  position: PromptBlockPositionDTO;
+  depth: number;
+}
+
+/** A select variable's mapping from option ids to native Loom placement profiles. */
+export interface PromptBlockPlacementBindingDTO {
+  variableId: string;
+  options: Record<string, PromptBlockPlacementDTO>;
+}
+
+interface PromptBlockCoreDTO {
   id: string;
   name: string;
   content: string;
@@ -1289,11 +1330,45 @@ export interface PromptBlockDTO {
   variables?: PromptVariableDefDTO[];
 }
 
+/**
+ * Editable/public prompt-block value.
+ *
+ * Host placement and sealed/provenance fields are snapshot-only and therefore
+ * cannot be supplied through mutable block or editor inputs.
+ */
+export interface PromptBlockDTO extends PromptBlockCoreDTO {
+  placementBinding?: never;
+  sealed?: never;
+  sealedKey?: never;
+  sealedSource?: never;
+  sealedOriginPresetId?: never;
+  sealedOriginVersion?: never;
+  sealedSha256?: never;
+}
+
+/**
+ * Host-returned snapshot of a prompt block.
+ *
+ * The placement binding and sealed/provenance fields are native host snapshot
+ * semantics. They are intentionally absent from the editable/public
+ * `PromptBlockDTO` and must not be supplied through mutable block or editor
+ * inputs.
+ */
+export interface PromptBlockSnapshotDTO extends PromptBlockCoreDTO {
+  placementBinding?: PromptBlockPlacementBindingDTO;
+  sealed?: boolean;
+  sealedKey?: string;
+  sealedSource?: "lumihub" | string;
+  sealedOriginPresetId?: string;
+  sealedOriginVersion?: string | null;
+  sealedSha256?: string;
+}
+
 export interface PromptBlockCategoryGroupDTO {
   /** The category header block, or null for uncategorized leading blocks. */
-  categoryBlock: PromptBlockDTO | null;
+  categoryBlock: PromptBlockSnapshotDTO | null;
   /** Non-category blocks after the header until the next category header. */
-  children: PromptBlockDTO[];
+  children: PromptBlockSnapshotDTO[];
 }
 
 export interface HostResponseErrorDTO {
@@ -1310,7 +1385,7 @@ export interface UserPresetDTO {
   provider: string;
   engine: string;
   parameters: Record<string, unknown>;
-  prompt_order: PromptBlockDTO[];
+  prompt_order: PromptBlockSnapshotDTO[];
   prompts: Record<string, unknown>;
   metadata: Record<string, unknown>;
   cache_revision: number;
@@ -1383,6 +1458,8 @@ export interface WorldBookEntryDTO {
   group_weight: number;
   probability: number;
   scan_depth: number | null;
+  /** Exclude the synthetic character greeting from lexical activation scans. */
+  exclude_greeting: boolean;
   case_sensitive: boolean;
   match_whole_words: boolean;
   automation_id: string | null;
@@ -1419,6 +1496,8 @@ export interface WorldBookEntryCreateDTO {
   group_weight?: number;
   probability?: number;
   scan_depth?: number;
+  /** Exclude the synthetic character greeting from lexical activation scans. */
+  exclude_greeting?: boolean;
   case_sensitive?: boolean;
   match_whole_words?: boolean;
   automation_id?: string;
@@ -1541,6 +1620,8 @@ export interface WorldInfoInterceptorEntryDTO {
   readonly prevent_recursion: boolean;
   readonly exclude_recursion: boolean;
   readonly delay_until_recursion: boolean;
+  /** Exclude the synthetic character greeting from lexical activation scans. */
+  readonly exclude_greeting: boolean;
   readonly scan_depth: number | null;
   readonly order_value: number;
   /** Attachment scope that contributed the entry's book to this chat. */
@@ -1563,6 +1644,22 @@ export interface WorldInfoInterceptorMessageDTO {
   readonly index_in_chat: number;
 }
 
+/** Effective host settings for world-info activation. */
+export interface WorldInfoActivationSettingsDTO {
+  /** Default entry scan depth, or null to scan all available messages. */
+  readonly globalScanDepth: number | null;
+  readonly maxRecursionPasses: number;
+}
+
+/**
+ * Restrictive, prompt-local changes to world info activation. Overrides from
+ * multiple interceptors compose monotonically: `true` always wins.
+ */
+export interface WorldInfoActivationOverridesDTO {
+  /** Set the effective recursion-pass limit to zero for this prompt. */
+  readonly disableRecursion?: true;
+}
+
 /**
  * Context passed to a `registerWorldInfoInterceptor` handler. Fires inside
  * `assemblePrompt` immediately before `activateWorldInfo` runs, so any
@@ -1577,15 +1674,23 @@ export interface WorldInfoInterceptorCtxDTO {
   readonly messages: readonly WorldInfoInterceptorMessageDTO[];
   readonly chatTurn: number;
   readonly chatMetadata: Readonly<Record<string, unknown>>;
+  readonly activationSettings: WorldInfoActivationSettingsDTO;
 }
 
 /**
- * Per-entry content override emitted by a `registerWorldInfoInterceptor`
- * handler. `content` replaces the entry's `content` for this prompt only.
+ * Per-entry content overrides emitted by a `registerWorldInfoInterceptor`
+ * handler. Both values are prompt-local and never persist to the world book.
  */
 export interface WorldInfoInterceptorMutationDTO {
   readonly id: string;
+  /** Replaces the entry content used for final prompt insertion. */
   readonly content?: string;
+  /**
+   * Alternate content used only for empty filtering, content deduplication,
+   * token accounting, and activation caps. Final insertion still uses
+   * `content` (or the stored entry content when `content` is omitted).
+   */
+  readonly selectionContent?: string;
 }
 
 /**
@@ -1598,6 +1703,8 @@ export interface WorldInfoInterceptorResultDTO {
   readonly enabled?: readonly string[];
   readonly forced?: readonly string[];
   readonly mutated?: readonly WorldInfoInterceptorMutationDTO[];
+  readonly captured?: readonly string[];
+  readonly activationOverrides?: WorldInfoActivationOverridesDTO;
 }
 
 // ─── Databank DTOs ───────────────────────────────────────────────────────
@@ -1959,7 +2066,7 @@ export interface BoundPrefillAttachmentDTO {
 }
 
 export interface BoundAssembleRequestDTO {
-  blocks: PromptBlockDTO[];
+  blocks: PromptBlockSnapshotDTO[];
   promptVariableValues?: PromptVariableValuesDTO;
   dispatch: GenerationDispatchSourceDTO;
   deadlineAt: number;
@@ -3408,7 +3515,8 @@ export type WorkerToHost =
   | { type: "user_is_visible"; requestId: string; userId?: string }
   | { type: "user_get_role"; requestId: string; userId?: string }
   // ─── Text Editor (free tier) ───────────────────────────────────────
-  | { type: "text_editor_open"; requestId: string; title?: string; value?: string; placeholder?: string; userId?: string }
+  | { type: "text_editor_open"; requestId: string; editorRequestId?: string; title?: string; value?: string; placeholder?: string; userId?: string }
+  | { type: "text_editor_close"; requestId: string; editorRequestId: string; userId?: string }
   // ─── Modal (free tier) ────────────────────────────────────────────
   | { type: "modal_open"; requestId: string; modalRequestId?: string; title: string; items: SpindleModalItemDTO[]; width?: number; maxHeight?: number; persistent?: boolean; userId?: string }
   | { type: "modal_close"; requestId: string; openRequestId: string; userId?: string }

package/src/components.ts

@@ -38,6 +38,8 @@ export interface SpindleLoomBlockEditorValue {
 export interface SpindleLoomBlockEditorOptions {
   value: SpindleLoomBlockEditorValue;
   onChange?: (value: SpindleLoomBlockEditorValue) => void;
+  /** Reports validated in-progress edits, or `null` when the native draft is discarded. */
+  onDraftChange?: (value: SpindleLoomBlockEditorValue | null) => void;
   readOnly?: boolean;
   compact?: boolean;
 }

package/src/dom.ts

@@ -547,8 +547,10 @@ export interface SpindleTextEditorOptions {
   value?: string;
   /** Placeholder text. Default: "" */
   placeholder?: string;
-  /** Enable macro syntax highlighting and insertion panel. Default: true */
-  macros?: boolean;
+  /** Optional caller-owned 1–128 character ASCII token used with `textEditor.close()`. */
+  editorRequestId?: string;
+  /** For operator-scoped extensions only. */
+  userId?: string;
 }
 
 export interface SpindleTextEditorResult {

package/src/host.ts

@@ -2,9 +2,12 @@ export const SPINDLE_HOST_CAPABILITIES = Object.freeze({
   "preset-extension-data-v1": 1,
   "preset-editor-v1": 1,
   "loom-block-editor-v1": 1,
+  "loom-block-management-v1": 1,
   "generation-assembly-v1": 1,
   "interceptor-context-v1": 1,
   "interceptor-final-response-v1": 1,
+  "connection-dispatch-resolution-v1": 1,
+  "text-editor-close-v1": 1,
 }) as Readonly<Record<string, number>>;
 /** Structured error code returned when host compatibility validation fails. */
 export const SPINDLE_COMPATIBILITY_ERROR_CODE = "SPINDLE_COMPATIBILITY_ERROR" as const;

package/src/index.ts

@@ -27,6 +27,7 @@ export { ALL_CAPABILITIES, isValidCapability } from "./capabilities";
 export { SpindleEvent, CoreEventType } from "./events";
 
 export type {
+  LlmMessagePartDTO,
   LlmMessageDTO,
   LlmThinkingBlockDTO,
   SpindleUserRoleDTO,
@@ -84,7 +85,10 @@ export type {
     PromptBlockRoleDTO,
     PromptBlockPositionDTO,
     PromptBlockCategoryModeDTO,
+    PromptBlockPlacementDTO,
+    PromptBlockPlacementBindingDTO,
     PromptBlockDTO,
+    PromptBlockSnapshotDTO,
     PromptBlockCreateDTO,
     PromptBlockUpdateDTO,
     PromptBlockCategoryGroupDTO,
@@ -109,6 +113,8 @@ export type {
   RegexScriptActiveOptionsDTO,
   WorldInfoInterceptorEntryDTO,
   WorldInfoInterceptorMessageDTO,
+  WorldInfoActivationSettingsDTO,
+  WorldInfoActivationOverridesDTO,
   WorldInfoInterceptorCtxDTO,
   WorldInfoInterceptorMutationDTO,
   WorldInfoInterceptorResultDTO,
@@ -225,6 +231,8 @@ export type {
   SharedRpcRequestContextDTO,
   SharedRpcEndpointPolicyDTO,
   MacroInterceptorPhase,
+  MacroInterceptorCharacterEnvDTO,
+  MacroInterceptorChatEnvDTO,
   MacroInterceptorEnvDTO,
   MacroInterceptorCtxDTO,
   MacroInterceptorResultDTO,
@@ -246,13 +254,16 @@ export { PERMISSION_DENIED_PREFIX } from "./api";
 export type { ToolRegistration, JSONSchema } from "./tools";
 
 export type {
+  SpindleMessageElement,
+  SpindleTextEditorOptions,
+  SpindleTextEditorResult,
   SpindleDOMHelper,
   SpindleMountPoint,
   SpindleUploadFile,
-    SpindleMessageTagIntercept,
-    SpindleMessageTagInterceptorOptions,
-    SpindleMessageWidgetOptions,
-    PermissionRequestOptions,
+  SpindleMessageTagIntercept,
+  SpindleMessageTagInterceptorOptions,
+  SpindleMessageWidgetOptions,
+  PermissionRequestOptions,
   SpindleFrontendContext,
   SpindleFrontendModule,
   SpindleFrontendTeardown,

package/src/spindle-api.ts

@@ -1,5 +1,6 @@
 import type { SpindleManifest } from "./manifest";
 import type { SpindleHostDescriptorV1 } from "./host";
+import type { SpindleTextEditorOptions, SpindleTextEditorResult } from "./dom";
 import type {
   CouncilMemberContext,
   CouncilSettings,
@@ -30,7 +31,7 @@ import type {
   UserPresetDTO,
   UserPresetCreateDTO,
   UserPresetUpdateDTO,
-  PromptBlockDTO,
+  PromptBlockSnapshotDTO,
   PromptBlockCreateDTO,
   PromptBlockUpdateDTO,
   PromptBlockCategoryGroupDTO,
@@ -953,10 +954,10 @@ export interface SpindleAPI {
     update(presetId: string, input: UserPresetUpdateDTO, userId?: string): Promise<UserPresetDTO>;
     delete(presetId: string, userId?: string): Promise<boolean>;
     blocks: {
-      list(presetId: string, userId?: string): Promise<PromptBlockDTO[]>;
-      get(presetId: string, blockId: string, userId?: string): Promise<PromptBlockDTO | null>;
-      create(presetId: string, input: PromptBlockCreateDTO, options?: { index?: number; userId?: string }): Promise<PromptBlockDTO>;
-      update(presetId: string, blockId: string, input: PromptBlockUpdateDTO, userId?: string): Promise<PromptBlockDTO>;
+      list(presetId: string, userId?: string): Promise<PromptBlockSnapshotDTO[]>;
+      get(presetId: string, blockId: string, userId?: string): Promise<PromptBlockSnapshotDTO | null>;
+      create(presetId: string, input: PromptBlockCreateDTO, options?: { index?: number; userId?: string }): Promise<PromptBlockSnapshotDTO>;
+      update(presetId: string, blockId: string, input: PromptBlockUpdateDTO, userId?: string): Promise<PromptBlockSnapshotDTO>;
       delete(presetId: string, blockId: string, userId?: string): Promise<boolean>;
     };
     categories: {
@@ -1356,6 +1357,7 @@ export interface SpindleAPI {
    * Host contract versions for feature detection, keyed by contract name.
    * `preAssemblyGenerationContext >= 1`: generation contexts carry
    * `dryRun`/`userId` and `cancelGeneration` is honored.
+   * `worldInfoActivationCapture >= 1`: world info activation capture is supported.
    */
   contracts?: Readonly<Record<string, number>>;
 
@@ -1400,15 +1402,22 @@ export interface SpindleAPI {
    *
    * Fires inside `assemblePrompt` immediately before `activateWorldInfo`
    * runs. Handlers can disable, force-enable, or content-override world info
-   * entries based on chat state, message history, or external rules.
+   * entries based on chat state, message history, or external rules. A
+   * separate selection-only content view can influence empty filtering,
+   * deduplication, and host budget selection without changing final inserted
+   * content. Handlers can also narrow the prompt-local activation scope by
+   * disabling recursive keyword chaining.
    * Multiple handlers chain in priority order and a later handler sees the
    * prior handlers' votes applied — useful for cross-entry injection
    * patterns where one entry merges into another and then disables itself.
+   * Captured IDs are activated against the pre-vote entry view and delivered
+   * only to the requesting extension as `capturedWorldInfo`; `[]` is an
+   * authoritative empty result and `undefined` means no capture was requested.
    *
    * Returning `void` passes the activation set through unchanged. Per-handler
    * 10s timeout; errors are logged and the chain continues.
    *
-   * @param handler  Returns the disabled / enabled / forced / mutated lists, or `void`.
+   * @param handler  Returns entry changes, capture requests, activation overrides, or `void`.
    * @param priority Lower values run first. Default `100`.
    *
    * @example
@@ -1683,16 +1692,13 @@ export interface SpindleAPI {
      * }
      * ```
      */
-    open(options?: {
-      title?: string;
-      value?: string;
-      placeholder?: string;
-      /** For operator-scoped extensions only. */
-      userId?: string;
-    }): Promise<{
-      text: string;
-      cancelled: boolean;
-    }>;
+    open(options?: SpindleTextEditorOptions): Promise<SpindleTextEditorResult>;
+    /**
+     * Cancel an editor opened with the matching `editorRequestId`.
+     *
+     * Unknown or already-settled identities are accepted as no-ops.
+     */
+    close(editorRequestId: string, userId?: string): Promise<void>;
   };
 
   /**

package/test/bound-generation-consumer.ts

@@ -1,5 +1,6 @@
 import type {
   BoundAssembleRequestDTO,
+  PromptBlockSnapshotDTO,
   BoundAssemblyFailureDTO,
   BoundAssemblyOutcomeDTO,
   BoundAssemblySuccessDTO,
@@ -50,7 +51,37 @@ const messages: LlmMessageDTO[] = [
   },
 ];
 
-const promptBlocks = [] as BoundAssembleRequestDTO["blocks"];
+const boundPromptSnapshot: PromptBlockSnapshotDTO = {
+  id: "bound-block",
+  name: "Bound dialogue",
+  content: "{{dialogue}}",
+  role: "system",
+  enabled: true,
+  position: "pre_history",
+  depth: 0,
+  marker: null,
+  isLocked: false,
+  color: null,
+  injectionTrigger: [],
+  group: null,
+  placementBinding: {
+    variableId: "layout",
+    options: {
+      standard: {
+        role: "assistant_append",
+        position: "in_history",
+        depth: 2,
+      },
+    },
+  },
+  sealed: true,
+  sealedKey: "dialogue.frame",
+  sealedSource: "lumihub",
+  sealedOriginPresetId: "lumihub-preset",
+  sealedOriginVersion: "v3",
+  sealedSha256: "sha256:dialogue-frame",
+};
+const promptBlocks: BoundAssembleRequestDTO["blocks"] = [boundPromptSnapshot];
 const boundRequest: BoundAssembleRequestDTO = {
   blocks: promptBlocks,
   promptVariableValues: {},

package/test/final-response-and-host-compatibility.test.ts

@@ -16,9 +16,12 @@ test("host compatibility constants are canonical and immutable", () => {
     "preset-extension-data-v1": 1,
     "preset-editor-v1": 1,
     "loom-block-editor-v1": 1,
+    "loom-block-management-v1": 1,
     "generation-assembly-v1": 1,
     "interceptor-context-v1": 1,
     "interceptor-final-response-v1": 1,
+    "connection-dispatch-resolution-v1": 1,
+    "text-editor-close-v1": 1,
   });
   expect(Object.isFrozen(SPINDLE_HOST_CAPABILITIES)).toBe(true);
 });

package/test/host-runtime-contract-consumer.ts

@@ -107,6 +107,24 @@ spindle.host.capabilities["interceptor-final-response-v1"] = 2;
 // @ts-expect-error descriptor scalar fields are readonly
 spindle.host.lumiverseVersion = "2.0.0";
 void backendHost;
+const editorRequestId = "550e8400-e29b-41d4-a716-446655440001";
+const editorResult = spindle.textEditor.open({ editorRequestId, value: "Review me" });
+const editorClose = spindle.textEditor.close(editorRequestId);
+const editorOpenMessage: WorkerToHost = {
+  type: "text_editor_open",
+  requestId: "transport-open",
+  editorRequestId,
+  value: "Review me",
+};
+const editorCloseMessage: WorkerToHost = {
+  type: "text_editor_close",
+  requestId: "transport-close",
+  editorRequestId,
+};
+void editorResult;
+void editorClose;
+void editorOpenMessage;
+void editorCloseMessage;
 
 declare const ctx: SpindleFrontendContext;
 const frontendHost: SpindleHostDescriptorV1 = ctx.host;

package/test/interceptor-consumer.ts

@@ -127,6 +127,24 @@ const legacyArrayCallback: InterceptorHandler = async (input) => input;
 const legacyResultCallback: InterceptorHandler = async (input) => ({ messages: input });
 
 declare const spindle: SpindleAPI;
+spindle.registerWorldInfoInterceptor(async (worldInfoContext) => {
+  const globalScanDepth: number | null =
+    worldInfoContext.activationSettings.globalScanDepth;
+  void globalScanDepth;
+});
+spindle.registerMessageContentProcessor(async (messageContext) => {
+  const isUser: boolean = messageContext.isUser;
+  void isUser;
+});
+spindle.registerMacroInterceptor(async (macroContext) => {
+  const firstMessage: string = macroContext.env.character.firstMessage;
+  const alternateGreetings: readonly string[] =
+    macroContext.env.character.alternateGreetings;
+  const greetingIndex: number = macroContext.env.chat.greetingIndex;
+  void firstMessage;
+  void alternateGreetings;
+  void greetingIndex;
+});
 const priorityDisposer: InterceptorDisposer = spindle.registerInterceptor(callback, 900, matchOptions);
 const optionsDisposer: InterceptorDisposer = spindle.registerInterceptor(callback, options);
 const handlerOnlyDisposer: InterceptorDisposer = spindle.registerInterceptor(legacyArrayCallback);

package/test/loom-block-editor-consumer.ts

@@ -1,4 +1,10 @@
 import type {
+  PromptBlockDTO,
+  PromptBlockPlacementBindingDTO,
+  PromptBlockPlacementDTO,
+  PromptBlockSnapshotDTO,
+  PromptBlockCreateDTO,
+  SpindleAPI,
   SpindleComponentTarget,
   SpindleComponentsHelper,
   SpindleLoomBlockEditorHandle,
@@ -37,3 +43,189 @@ export function compileLoomBlockEditorContract(
   void updated;
   return refreshed;
 }
+
+/** Package-root consumer fixture for host-returned preset block snapshots. */
+export async function compilePresetSnapshotContract(api: SpindleAPI): Promise<void> {
+  const editableBlock: PromptBlockDTO = {
+    id: "block-1",
+    name: "Dialogue",
+    content: "{{dialogue}}",
+    role: "system",
+    enabled: true,
+    position: "pre_history",
+    depth: 0,
+    marker: null,
+    isLocked: false,
+    color: null,
+    injectionTrigger: [],
+    group: null,
+  };
+  const placement: PromptBlockPlacementDTO = {
+    role: "assistant_append",
+    position: "in_history",
+    depth: 2,
+  };
+  const placementBinding: PromptBlockPlacementBindingDTO = {
+    variableId: "layout",
+    options: {
+      standard: placement,
+    },
+  };
+  const snapshot: PromptBlockSnapshotDTO = {
+    ...editableBlock,
+    placementBinding,
+    sealed: true,
+    sealedKey: "dialogue.frame",
+    sealedSource: "lumihub",
+    sealedOriginPresetId: "lumihub-preset",
+    sealedOriginVersion: "v3",
+    sealedSha256: "sha256:dialogue-frame",
+  };
+
+  const preset = await api.presets.get("preset-1");
+  if (preset) {
+    const fromPreset = preset.prompt_order[0];
+    if (fromPreset) {
+      if (fromPreset.placementBinding) {
+        void fromPreset.placementBinding.variableId;
+      }
+      if (fromPreset.sealedSource) {
+        void fromPreset.sealedSource.toUpperCase();
+      }
+    }
+  }
+  const fromList = await api.presets.blocks.list("preset-1");
+  const fromListBlock = fromList[0];
+  if (fromListBlock) {
+    if (fromListBlock.placementBinding) {
+      void fromListBlock.placementBinding.variableId;
+    }
+    if (fromListBlock.sealedSource) {
+      void fromListBlock.sealedSource.toUpperCase();
+    }
+  }
+  const fromGet = await api.presets.blocks.get("preset-1", "block-1");
+  if (fromGet) {
+    if (fromGet.placementBinding) {
+      void fromGet.placementBinding.variableId;
+    }
+    if (fromGet.sealedSource) {
+      void fromGet.sealedSource.toUpperCase();
+    }
+  }
+  const fromCreate = await api.presets.blocks.create("preset-1", editableBlock);
+  if (fromCreate.placementBinding) {
+    void fromCreate.placementBinding.variableId;
+  }
+  if (fromCreate.sealedSource) {
+    void fromCreate.sealedSource.toUpperCase();
+  }
+  const fromUpdate = await api.presets.blocks.update("preset-1", "block-1", {
+    name: "Updated dialogue",
+  });
+  if (fromUpdate.placementBinding) {
+    void fromUpdate.placementBinding.variableId;
+  }
+  if (fromUpdate.sealedSource) {
+    void fromUpdate.sealedSource.toUpperCase();
+  }
+  const groups = await api.presets.categories.list("preset-1");
+  const category = groups[0]?.categoryBlock;
+  if (category) {
+    if (category.placementBinding) {
+      void category.placementBinding.variableId;
+    }
+    if (category.sealedSource) {
+      void category.sealedSource.toUpperCase();
+    }
+  }
+  const child = groups[0]?.children[0];
+  if (child) {
+    if (child.placementBinding) {
+      void child.placementBinding.variableId;
+    }
+    if (child.sealedSource) {
+      void child.sealedSource.toUpperCase();
+    }
+  }
+
+  const forbiddenBlockPlacement: PromptBlockDTO = {
+    ...editableBlock,
+    // @ts-expect-error Host placement is snapshot-only.
+    placementBinding,
+  };
+  const forbiddenBlockProvenance: PromptBlockDTO = {
+    ...editableBlock,
+    // @ts-expect-error Host seal state is snapshot-only.
+    sealed: true,
+  };
+  const forbiddenCreatePlacement: PromptBlockCreateDTO = {
+    name: "forbidden create",
+    // @ts-expect-error Host placement is snapshot-only.
+    placementBinding,
+  };
+  const forbiddenCreateProvenance: PromptBlockCreateDTO = {
+    name: "forbidden create",
+    // @ts-expect-error Host seal state is snapshot-only.
+    sealed: true,
+  };
+  const forbiddenEditorPlacement: SpindleLoomBlockEditorValue = {
+    blocks: [{
+      ...editableBlock,
+      // @ts-expect-error Host placement is snapshot-only.
+      placementBinding,
+    }],
+    promptVariableValues: {},
+  };
+  const forbiddenEditorProvenance: SpindleLoomBlockEditorValue = {
+    blocks: [{
+      ...editableBlock,
+      // @ts-expect-error Host seal state is snapshot-only.
+      sealed: true,
+    }],
+    promptVariableValues: {},
+  };
+
+  // @ts-expect-error Read snapshots cannot cross the editable PromptBlockDTO boundary.
+  const mutableBlockFromSnapshot: PromptBlockDTO = fromCreate;
+  // @ts-expect-error Read snapshots cannot be supplied to block creation.
+  await api.presets.blocks.create("preset-1", fromCreate);
+  // @ts-expect-error Read snapshots cannot be supplied to block updates.
+  await api.presets.blocks.update("preset-1", "block-1", fromCreate);
+  const presetCreateFromSnapshot = {
+    name: "forbidden preset",
+    provider: "test",
+    prompt_order: [fromCreate],
+  };
+  // @ts-expect-error Read snapshots cannot be supplied to preset creation.
+  await api.presets.create(presetCreateFromSnapshot);
+  const presetUpdateFromSnapshot = {
+    expected_cache_revision: 0,
+    prompt_order: [fromCreate],
+  };
+  // @ts-expect-error Read snapshots cannot be supplied to preset updates.
+  await api.presets.update("preset-1", presetUpdateFromSnapshot);
+  const editorValueFromSnapshot: SpindleLoomBlockEditorValue = {
+    // @ts-expect-error Read snapshots cannot cross the Loom editor boundary.
+    blocks: [fromCreate],
+    promptVariableValues: {},
+  };
+
+  void snapshot;
+  void fromList;
+  void fromGet;
+  void fromCreate;
+  void fromUpdate;
+  void category;
+  void child;
+  void forbiddenBlockPlacement;
+  void forbiddenBlockProvenance;
+  void forbiddenCreatePlacement;
+  void forbiddenCreateProvenance;
+  void forbiddenEditorPlacement;
+  void forbiddenEditorProvenance;
+  void mutableBlockFromSnapshot;
+  void presetCreateFromSnapshot;
+  void presetUpdateFromSnapshot;
+  void editorValueFromSnapshot;
+}