lumiverse-spindle-types 0.5.17 → 0.5.19

package/package.json

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

package/src/api.ts

@@ -159,12 +159,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") ───────────
 
@@ -774,6 +787,26 @@ export interface ChatChangedPayloadDTO {
   changedFields?: string[];
 }
 
+/**
+ * Payload for `CHAT_FORKED` events. Emitted when a chat is forked (branched)
+ * from a specific message — the messages up to and including the fork point are
+ * copied into a brand-new chat that shares the source chat's character.
+ */
+export interface ChatForkedPayloadDTO {
+  /** Id of the source chat that was forked. */
+  sourceChatId: string;
+  /** Id of the newly created forked chat. Equal to `chat.id`. */
+  forkedChatId: string;
+  /** The new forked chat row, including its `metadata` (carries `branched_from` and `branch_at_message`). */
+  chat: { id: string; [key: string]: unknown };
+  /** The `branch_id` assigned to every message copied into the forked chat. */
+  branchId: string;
+  /** Id of the message in the source chat the fork was taken at. Messages up to and including this one were copied into the forked chat. */
+  forkedAtMessageId: string;
+  /** Zero-based index of the fork-point message within the source chat. */
+  forkedAtMessageIndex: number;
+}
+
 // ─── User Preset DTOs ───────────────────────────────────────────────────
 
 /** Option entry for `select` and `multiselect` prompt variables. */

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/events.ts

@@ -14,6 +14,7 @@ export enum CoreEventType {
   CONNECTED = "CONNECTED",
   CHAT_CHANGED = "CHAT_CHANGED",
   CHAT_SWITCHED = "CHAT_SWITCHED",
+  CHAT_FORKED = "CHAT_FORKED",
   MESSAGE_SENT = "MESSAGE_SENT",
   MESSAGE_EDITED = "MESSAGE_EDITED",
   MESSAGE_DELETED = "MESSAGE_DELETED",

package/src/index.ts

@@ -49,6 +49,7 @@ export type {
     ChatUpdateDTO,
     ChatSwitchedPayloadDTO,
     ChatChangedPayloadDTO,
+    ChatForkedPayloadDTO,
     PromptVariableOptionDTO,
     PromptVariableDefDTO,
     PromptVariableTypeDTO,
@@ -161,6 +162,7 @@ export type {
   MacroInterceptorEnvDTO,
   MacroInterceptorCtxDTO,
   MacroInterceptorResultDTO,
+  MacroInterceptorRichResultDTO,
   MessageContentProcessorOrigin,
   MessageContentProcessorCtxDTO,
   MessageContentProcessorResultDTO,
@@ -221,6 +223,14 @@ export type {
     SpindleUIEventsHelper,
     SpindleFrontendProcessContext,
     SpindleFrontendProcessRegistry,
+    SpindleDisplayResolver,
+    SpindleDisplayResolverRegistry,
+    SpindleDisplayContext,
+    SpindleDisplayBodyArgs,
+    SpindleDisplayTemplatesArgs,
+    SpindleDisplayScriptsArgs,
+    SpindleDisplayResolveResult,
+    SpindleDisplayTemplatesResult,
  } from "./dom";
 
 export type {

package/src/spindle-api.ts

@@ -85,6 +85,7 @@ import type {
   BackendProcessLifecycleEventDTO,
   BackendProcessStopOptionsDTO,
   ChatChangedPayloadDTO,
+  ChatForkedPayloadDTO,
   ChatMessageDTO,
   GenerationStartedPayloadDTO,
   StreamTokenPayloadDTO,
@@ -220,6 +221,8 @@ export interface SpindleAPI {
   on(event: "GENERATION_STOPPED", handler: (payload: GenerationStoppedPayloadDTO, userId?: string) => void): () => void;
   /** Subscribe to `CHAT_CHANGED` events. `changedFields` lists the dot-paths that differed when emitted by the standard `updateChat` path; absent on emits from other sources. */
   on(event: "CHAT_CHANGED", handler: (payload: ChatChangedPayloadDTO, userId?: string) => void): () => void;
+  /** Subscribe to `CHAT_FORKED` events. Emitted when a chat is forked (branched) from a message into a new chat. The payload carries the source/forked chat ids, the full forked chat row, and the fork point. */
+  on(event: "CHAT_FORKED", handler: (payload: ChatForkedPayloadDTO, userId?: string) => void): () => void;
   /**
    * Subscribe to swipe lifecycle events. The payload's `action` discriminator
    * tells you whether a swipe was added, updated, deleted, or navigated, and