lumiverse-spindle-types 0.6.9 → 0.6.11

package/package.json

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

package/src/api.ts

@@ -252,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>;
@@ -337,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. */
@@ -1442,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;
@@ -1478,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;
@@ -1587,6 +1607,7 @@ export interface WorldInfoInterceptorEntryDTO {
   readonly keysecondary: readonly string[];
   readonly position: number;
   readonly depth: number;
+  readonly role: string | null;
   readonly priority: number;
   readonly probability: number;
   readonly use_probability: boolean;
@@ -1594,14 +1615,24 @@ export interface WorldInfoInterceptorEntryDTO {
   readonly automation_id: string | null;
   readonly selective: boolean;
   readonly selective_logic: number;
+  readonly group_name: string;
+  readonly group_override: boolean;
+  readonly group_weight: number;
   readonly match_whole_words: boolean;
   readonly case_sensitive: boolean;
   readonly use_regex: boolean;
   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;
+  readonly sticky: number;
+  readonly cooldown: number;
+  readonly delay: number;
+  /** Latest prompt-local chat placement supplied by an earlier handler. */
+  readonly placement?: WorldInfoInterceptorPlacementDTO;
   /** Attachment scope that contributed the entry's book to this chat. */
   readonly book_source?: WorldBookSourceDTO;
 }
@@ -1622,6 +1653,40 @@ 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;
+}
+
+export type WorldInfoInterceptorRoleDTO = "system" | "user" | "assistant";
+
+/**
+ * Prompt-local placement relative to the selected chat history, including its
+ * greeting when present.
+ *
+ * Selected placements use the host's world-info insertion order. Each inserted
+ * entry becomes part of the history sequence used to place the next entry. The
+ * host does not persist these values to the world book.
+ */
+export interface WorldInfoInterceptorPlacementDTO {
+  readonly type: "chat_depth";
+  readonly role: WorldInfoInterceptorRoleDTO;
+  /** Non-negative integer passed to the selected direction's depth rule. */
+  readonly depth: number;
+  readonly direction: "from_start" | "from_end";
+}
+
 /**
  * Context passed to a `registerWorldInfoInterceptor` handler. Fires inside
  * `assemblePrompt` immediately before `activateWorldInfo` runs, so any
@@ -1636,15 +1701,28 @@ 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;
+  /**
+   * Overrides this entry's chat-history placement for the current prompt.
+   * Omit it to retain the stored native position, depth, and role.
+   */
+  readonly placement?: WorldInfoInterceptorPlacementDTO;
 }
 
 /**
@@ -1658,6 +1736,7 @@ export interface WorldInfoInterceptorResultDTO {
   readonly forced?: readonly string[];
   readonly mutated?: readonly WorldInfoInterceptorMutationDTO[];
   readonly captured?: readonly string[];
+  readonly activationOverrides?: WorldInfoActivationOverridesDTO;
 }
 
 // ─── Databank DTOs ───────────────────────────────────────────────────────

package/src/dom.ts

@@ -858,6 +858,13 @@ export interface SpindleDisplayResolverRegistry {
   registerResolver(resolver: SpindleDisplayResolver): () => void;
   /** Ask the host to invalidate cached display resolutions whose dependencies (a `<scope>:<name>` set) changed. */
   invalidate(touchedVars: string[]): void;
+  /** Update the active chat's transient expression display without a backend round trip. */
+  setExpression(expression: {
+    chatId: string;
+    characterId: string;
+    label: string;
+    imageId: string;
+  }): void;
 }
 
 /** Context object provided to frontend extension modules */

package/src/index.ts

@@ -113,6 +113,10 @@ export type {
   RegexScriptActiveOptionsDTO,
   WorldInfoInterceptorEntryDTO,
   WorldInfoInterceptorMessageDTO,
+  WorldInfoActivationSettingsDTO,
+  WorldInfoActivationOverridesDTO,
+  WorldInfoInterceptorRoleDTO,
+  WorldInfoInterceptorPlacementDTO,
   WorldInfoInterceptorCtxDTO,
   WorldInfoInterceptorMutationDTO,
   WorldInfoInterceptorResultDTO,
@@ -229,6 +233,8 @@ export type {
   SharedRpcRequestContextDTO,
   SharedRpcEndpointPolicyDTO,
   MacroInterceptorPhase,
+  MacroInterceptorCharacterEnvDTO,
+  MacroInterceptorChatEnvDTO,
   MacroInterceptorEnvDTO,
   MacroInterceptorCtxDTO,
   MacroInterceptorResultDTO,

package/src/spindle-api.ts

@@ -1358,6 +1358,8 @@ export interface SpindleAPI {
    * `preAssemblyGenerationContext >= 1`: generation contexts carry
    * `dryRun`/`userId` and `cancelGeneration` is honored.
    * `worldInfoActivationCapture >= 1`: world info activation capture is supported.
+   * `worldInfoRuntimePlacement >= 1`: world info mutations accept prompt-local
+   * chat-depth placement.
    */
   contracts?: Readonly<Record<string, number>>;
 
@@ -1402,7 +1404,11 @@ 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.
@@ -1413,7 +1419,7 @@ export interface SpindleAPI {
    * 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 / captured lists, or `void`.
+   * @param handler  Returns entry changes, capture requests, activation overrides, or `void`.
    * @param priority Lower values run first. Default `100`.
    *
    * @example

package/test/interceptor-consumer.ts

@@ -127,6 +127,39 @@ 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;
+  const role: string | null | undefined = worldInfoContext.entries[0]?.role;
+  const priorPlacement = worldInfoContext.entries[0]?.placement;
+  void globalScanDepth;
+  void role;
+  void priorPlacement;
+  return {
+    mutated: [{
+      id: "entry-id",
+      placement: {
+        type: "chat_depth",
+        role: "system",
+        depth: 2,
+        direction: "from_start",
+      },
+    }],
+  };
+});
+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);