lumiverse-spindle-types 0.5.18 → 0.5.20

package/package.json

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

package/src/api.ts

@@ -36,6 +36,14 @@ export interface LlmMessageDTO {
    * only on `role: 'assistant'` messages.
    */
   reasoning_content?: string;
+  /**
+   * True when this message is a chat-history turn (as opposed to a depth-injected 
+   * world-info/preset/author's-note block that was spliced into the chat-history 
+   * range). Set by the host only on the messages passed to the interceptor pipeline, 
+   * so an extension applying prompt-target regex inline can reproduce the host's depth 
+   * frame exactly.
+   */
+  __isChatHistory?: boolean;
 }
 
 export type SpindleUserRoleDTO = "operator" | "admin" | "user";
@@ -159,12 +167,25 @@ export interface MacroInterceptorCtxDTO {
   readonly userId?: string;
 }
 
+/**
+ * Lets an interceptor that resolves the template report its real cache 
+ * dependencies so the host's display-regex cache can store the result 
+ * and invalidate it precisely.
+ */
+export interface MacroInterceptorRichResultDTO {
+  text: string;
+  touchedVars?: readonly string[];
+  volatile?: boolean;
+}
+
 /**
  * Return value of a macro interceptor handler.
  *  - `string` replaces the template for subsequent interceptors + parsing.
+ *    (forces a non-cacheable resolution when it changes the template).
+ *  - {@link MacroInterceptorRichResultDTO}
  *  - `void` / `undefined` passes the template through unchanged.
  */
-export type MacroInterceptorResultDTO = string | void;
+export type MacroInterceptorResultDTO = string | MacroInterceptorRichResultDTO | void;
 
 // ─── Message Content Processor (permission: "chat_mutation") ───────────
 

package/src/dom.ts

@@ -630,6 +630,71 @@ export interface SpindleFrontendProcessRegistry {
   ): () => void;
 }
 
+export interface SpindleDisplayContext {
+  chatId?: string;
+  characterId?: string;
+  personaId?: string;
+  isUser: boolean;
+  depth: number;
+  messageId?: string;
+  messageIndex?: number;
+  role?: string;
+  dynamicMacros?: Record<string, string>;
+}
+
+export interface SpindleDisplayResolveResult {
+  content: string;
+  touchedVars?: string[];
+  cacheable?: boolean;
+}
+
+export interface SpindleDisplayTemplatesResult {
+  resolved: Record<string, string>;
+  touchedVars?: Record<string, string[]>;
+  cacheable?: Record<string, boolean>;
+}
+
+export interface SpindleDisplayBodyArgs {
+  content: string;
+  context: SpindleDisplayContext;
+}
+
+export interface SpindleDisplayTemplatesArgs {
+  templates: Record<string, string>;
+  context: SpindleDisplayContext;
+}
+
+export interface SpindleDisplayScriptsArgs {
+  content: string;
+  scripts: unknown[];
+  context: SpindleDisplayContext;
+  resolvedFindPatterns?: Record<string, string>;
+  resolvedReplacements?: Record<string, string>;
+}
+
+/**
+ * A frontend display resolver lets an extension take over display-time content
+ * resolution in the browser instead of round-tripping to the host backend. The
+ * host consults the registered resolver while rendering messages and falls back
+ * to its own backend resolution whenever the resolver is absent, reports it is
+ * not ready for the chat, throws, or returns `null`.
+ */
+export interface SpindleDisplayResolver {
+  ready(chatId: string): boolean;
+  resolveBody(args: SpindleDisplayBodyArgs): Promise<SpindleDisplayResolveResult | null>;
+  resolveTemplates(args: SpindleDisplayTemplatesArgs): Promise<SpindleDisplayTemplatesResult | null>;
+  applyScripts(args: SpindleDisplayScriptsArgs): Promise<SpindleDisplayResolveResult | null>;
+}
+
+export interface SpindleDisplayResolverRegistry {
+  /** Register this extension's frontend display resolver. */
+  registerResolver(resolver: SpindleDisplayResolver): () => void;
+  /** Ask the host to invalidate cached display resolutions whose dependencies (a `<scope>:<name>` set) changed. */
+  invalidate(touchedVars: string[]): void;
+  /** Publish the set of character IDs whose display this extension owns. The host uses it to decide synchronously, at render time, whether a chat is owned by this resolver. */
+  setOwnedCharacters(characterIds: string[]): void;
+}
+
 /** Context object provided to frontend extension modules */
 export interface SpindleFrontendContext {
   dom: SpindleDOMHelper;
@@ -784,6 +849,8 @@ export interface SpindleFrontendContext {
     /** Update a message through the host app's authenticated API. */
     updateMessage(chatId: string, messageId: string, input: { content?: string }): Promise<unknown>;
   };
+  /** Take over display-time content resolution in the browser. */
+  display?: SpindleDisplayResolverRegistry;
   manifest: import("./manifest").SpindleManifest;
 }
 

package/src/index.ts

@@ -162,6 +162,7 @@ export type {
   MacroInterceptorEnvDTO,
   MacroInterceptorCtxDTO,
   MacroInterceptorResultDTO,
+  MacroInterceptorRichResultDTO,
   MessageContentProcessorOrigin,
   MessageContentProcessorCtxDTO,
   MessageContentProcessorResultDTO,
@@ -222,6 +223,14 @@ export type {
     SpindleUIEventsHelper,
     SpindleFrontendProcessContext,
     SpindleFrontendProcessRegistry,
+    SpindleDisplayResolver,
+    SpindleDisplayResolverRegistry,
+    SpindleDisplayContext,
+    SpindleDisplayBodyArgs,
+    SpindleDisplayTemplatesArgs,
+    SpindleDisplayScriptsArgs,
+    SpindleDisplayResolveResult,
+    SpindleDisplayTemplatesResult,
  } from "./dom";
 
 export type {
@@ -325,6 +334,7 @@ export type {
 
 export type {
   SpindleAPI,
+  SpindlePromptRegex,
   FrontendProcessHandle,
   BackendProcessHandle,
   SpindleBackendProcessContext,

package/src/spindle-api.ts

@@ -209,6 +209,19 @@ export type SpindleBackendProcessModule = {
   run?: (process: SpindleBackendProcessContext) => void | (() => void) | Promise<void | (() => void)>;
 };
 
+/**
+ * Lets an extension tell the host that it will apply `target:prompt` regex
+ * itself for a set of chats, so the host skips its own per-message prompt-regex
+ * pass for those chats.
+ */
+export interface SpindlePromptRegex {
+  /**
+   * Declare the chats this extension applies `target:prompt` regex for. Replaces
+   * the previously-declared set. Empty array clears ownership (host resumes its pass).
+   */
+  setOwnedChats(chatIds: string[]): void;
+}
+
 /** The global `spindle` object available in backend extension workers */
 export interface SpindleAPI {
   /** Subscribe to generation-started events (requires `generation` permission). The optional `userId` identifies which user triggered the event. */
@@ -289,6 +302,12 @@ export interface SpindleAPI {
     priority?: number
   ): void;
 
+  /**
+   * Declare the chats whose `target:prompt` regex this extension applies itself; the 
+   * host skips its own pass for them.
+   */
+  promptRegex: SpindlePromptRegex;
+
   /** Register an LLM tool */
   registerTool(tool: ToolRegistrationDTO): void;
   /** Unregister an LLM tool */