lumiverse-spindle-types 0.4.42 → 0.4.44

package/package.json

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

package/src/api.ts

@@ -579,6 +579,71 @@ export interface WorldBookEntryCreateDTO {
 
 export type WorldBookEntryUpdateDTO = WorldBookEntryCreateDTO;
 
+// ─── Databank DTOs ───────────────────────────────────────────────────────
+
+export type DatabankScopeDTO = "global" | "character" | "chat";
+export type DatabankDocumentStatusDTO = "pending" | "processing" | "ready" | "error";
+
+/** Safe representation of a databank exposed to extensions. */
+export interface DatabankDTO {
+  id: string;
+  name: string;
+  description: string;
+  scope: DatabankScopeDTO;
+  scope_id: string | null;
+  enabled: boolean;
+  metadata: Record<string, unknown>;
+  document_count?: number;
+  created_at: number;
+  updated_at: number;
+}
+
+export interface DatabankCreateDTO {
+  name: string;
+  description?: string;
+  scope: DatabankScopeDTO;
+  scope_id?: string | null;
+}
+
+export interface DatabankUpdateDTO {
+  name?: string;
+  description?: string;
+  enabled?: boolean;
+}
+
+/** Safe representation of a databank document exposed to extensions. */
+export interface DatabankDocumentDTO {
+  id: string;
+  databank_id: string;
+  name: string;
+  slug: string;
+  mime_type: string;
+  file_size: number;
+  content_hash: string;
+  total_chunks: number;
+  status: DatabankDocumentStatusDTO;
+  error_message: string | null;
+  metadata: Record<string, unknown>;
+  created_at: number;
+  updated_at: number;
+}
+
+export interface DatabankDocumentCreateDTO {
+  /** Raw file bytes. */
+  data: Uint8Array;
+  /** Original filename including extension. */
+  filename: string;
+  /** Optional MIME type recorded on the document. */
+  mime_type?: string;
+  /** Optional display name override. Defaults to the filename without extension. */
+  name?: string;
+}
+
+export interface DatabankDocumentUpdateDTO {
+  /** Renames the document display name (and derived slug). */
+  name: string;
+}
+
 // ─── Persona DTOs ──────────────────────────────────────────────────────
 
 /**
@@ -943,7 +1008,8 @@ export interface ThemeVariablesConfigDTO {
  * This is the safe, presentation-owned path for live extension theming.
  * Extensions provide palette intent only; Lumiverse preserves the user's
  * radius, glass, font, and UI-scale settings and generates the final
- * mode-aware variable maps itself.
+ * mode-aware variable maps itself. Pass `null` to clear a previously applied
+ * palette override when no valid color data is available.
  */
 export interface ThemePaletteConfigDTO {
   /** Primary accent color in HSL. */
@@ -1016,6 +1082,93 @@ export interface SpindleCommandContextDTO {
   isGroupChat?: boolean;
 }
 
+// ─── Frontend Process Lifecycle DTOs ────────────────────────────────────
+
+/** High-level lifecycle state for a frontend process tracked by the backend host. */
+export type FrontendProcessStateDTO =
+  | "starting"
+  | "running"
+  | "stopping"
+  | "stopped"
+  | "completed"
+  | "failed"
+  | "timed_out";
+
+/** Terminal reason attached to lifecycle events and snapshots when available. */
+export type FrontendProcessExitReasonDTO =
+  | "completed"
+  | "failed"
+  | "stopped"
+  | "timed_out"
+  | "frontend_unloaded"
+  | "backend_unloaded"
+  | "replaced";
+
+/** Options used when spawning a tracked frontend process from the backend worker. */
+export interface FrontendProcessSpawnOptionsDTO {
+  /** Frontend handler key registered via `ctx.processes.register(kind, ...)`. */
+  kind: string;
+  /** Optional extension-defined stable key used for dedupe / replacement semantics. */
+  key?: string;
+  /** Optional process-scoped startup payload delivered to the frontend handler. */
+  payload?: unknown;
+  /** Arbitrary metadata stored alongside the process snapshot for backend bookkeeping. */
+  metadata?: Record<string, unknown>;
+  /** For operator-scoped extensions only. */
+  userId?: string;
+  /** Reject spawn if the frontend does not call `process.ready()` within this window. */
+  startupTimeoutMs?: number;
+  /** Mark the process timed out if the frontend stops heartbeating for this long after ready. */
+  heartbeatTimeoutMs?: number;
+  /** Replace any existing process with the same `key` for the target user. */
+  replaceExisting?: boolean;
+}
+
+/** Filter used for controller list queries. */
+export interface FrontendProcessListOptionsDTO {
+  userId?: string;
+  kind?: string;
+  key?: string;
+  state?: FrontendProcessStateDTO;
+}
+
+/** Current host-tracked snapshot of a frontend process. */
+export interface FrontendProcessInfoDTO {
+  processId: string;
+  kind: string;
+  key?: string;
+  state: FrontendProcessStateDTO;
+  userId?: string;
+  metadata?: Record<string, unknown>;
+  startedAt: string;
+  readyAt?: string;
+  lastHeartbeatAt?: string;
+  endedAt?: string;
+  exitReason?: FrontendProcessExitReasonDTO;
+  error?: string;
+}
+
+/** Lifecycle event emitted to backend workers for tracked frontend processes. */
+export interface FrontendProcessLifecycleEventDTO {
+  processId: string;
+  kind: string;
+  key?: string;
+  userId?: string;
+  state: FrontendProcessStateDTO;
+  previousState?: FrontendProcessStateDTO;
+  at: string;
+  exitReason?: FrontendProcessExitReasonDTO;
+  error?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/** Options for graceful process termination. */
+export interface FrontendProcessStopOptionsDTO {
+  userId?: string;
+  /** Optional reason surfaced to the frontend process' stop handler. */
+  reason?: string;
+}
+
 // ─── Generation Event Payload DTOs ──────────────────────────────────────
 
 /** Payload for `GENERATION_STARTED` events. */
@@ -1528,6 +1681,20 @@ export type WorkerToHost =
   | { type: "world_book_entries_create"; requestId: string; worldBookId: string; input: WorldBookEntryCreateDTO; userId?: string }
   | { type: "world_book_entries_update"; requestId: string; entryId: string; input: WorldBookEntryUpdateDTO; userId?: string }
   | { type: "world_book_entries_delete"; requestId: string; entryId: string; userId?: string }
+  // ─── Databanks (gated: "databanks") ───────────────────────────────────
+  | { type: "databanks_list"; requestId: string; limit?: number; offset?: number; scope?: DatabankScopeDTO; scopeId?: string | null; userId?: string }
+  | { type: "databanks_get"; requestId: string; databankId: string; userId?: string }
+  | { type: "databanks_create"; requestId: string; input: DatabankCreateDTO; userId?: string }
+  | { type: "databanks_update"; requestId: string; databankId: string; input: DatabankUpdateDTO; userId?: string }
+  | { type: "databanks_delete"; requestId: string; databankId: string; userId?: string }
+  // ─── Databank Documents (gated: "databanks") ─────────────────────────
+  | { type: "databank_documents_list"; requestId: string; databankId: string; limit?: number; offset?: number; userId?: string }
+  | { type: "databank_documents_get"; requestId: string; documentId: string; userId?: string }
+  | { type: "databank_documents_create"; requestId: string; databankId: string; input: DatabankDocumentCreateDTO; userId?: string }
+  | { type: "databank_documents_update"; requestId: string; documentId: string; input: DatabankDocumentUpdateDTO; userId?: string }
+  | { type: "databank_documents_delete"; requestId: string; documentId: string; userId?: string }
+  | { type: "databank_documents_get_content"; requestId: string; documentId: string; userId?: string }
+  | { type: "databank_documents_reprocess"; requestId: string; documentId: string; userId?: string }
   // ─── Personas (gated: "personas") ────────────────────────────────────
   | { type: "personas_list"; requestId: string; limit?: number; offset?: number; userId?: string }
   | { type: "personas_get"; requestId: string; personaId: string; userId?: string }
@@ -1562,6 +1729,12 @@ export type WorkerToHost =
   | { type: "modal_close"; requestId: string; openRequestId: string; userId?: string }
   | { type: "confirm_open"; requestId: string; title: string; message: string; variant?: "info" | "warning" | "danger" | "success"; confirmLabel?: string; cancelLabel?: string; userId?: string }
   | { type: "input_prompt_open"; requestId: string; title: string; message?: string; placeholder?: string; defaultValue?: string; submitLabel?: string; cancelLabel?: string; multiline?: boolean; userId?: string }
+  // ─── Frontend Process Lifecycle (free tier) ───────────────────────────
+  | { type: "frontend_process_spawn"; requestId: string; options: FrontendProcessSpawnOptionsDTO }
+  | { type: "frontend_process_list"; requestId: string; filter?: FrontendProcessListOptionsDTO }
+  | { type: "frontend_process_get"; requestId: string; processId: string }
+  | { type: "frontend_process_stop"; requestId: string; processId: string; options?: FrontendProcessStopOptionsDTO }
+  | { type: "frontend_process_send"; processId: string; payload: unknown; userId?: string }
   // ─── Macro Resolution (free tier) ──────────────────────────────────
   | { type: "macros_resolve"; requestId: string; template: string; chatId?: string; characterId?: string; userId?: string; commit?: boolean }
   // ─── Image Generation (gated: "image_gen") ──────────────────────────
@@ -1572,7 +1745,7 @@ export type WorkerToHost =
   | { type: "image_gen_models"; requestId: string; connectionId: string; userId?: string }
   // ─── Theme (gated: "app_manipulation") ──────────────────────────────────
   | { type: "theme_apply"; requestId: string; overrides: ThemeOverrideDTO; userId?: string }
-  | { type: "theme_apply_palette"; requestId: string; palette: ThemePaletteConfigDTO; userId?: string }
+  | { type: "theme_apply_palette"; requestId: string; palette: ThemePaletteConfigDTO | null; userId?: string }
   | { type: "theme_clear"; requestId: string; userId?: string }
   | { type: "theme_get_current"; requestId: string; userId?: string }
   // ─── Color Extraction (gated: "app_manipulation") ─────────────────────
@@ -1678,6 +1851,8 @@ export type HostToWorker =
     }
   | { type: "shutdown" }
   | { type: "frontend_message"; payload: unknown; userId: string }
+  | { type: "frontend_process_lifecycle"; event: FrontendProcessLifecycleEventDTO }
+  | { type: "frontend_process_message"; processId: string; payload: unknown; userId: string }
   | {
       type: "oauth_callback";
       requestId: string;

package/src/dom.ts

@@ -326,6 +326,53 @@ export interface SpindleConfirmResult {
   confirmed: boolean;
 }
 
+// ── Frontend Process Lifecycle ──
+
+/** Controller passed to a frontend process instance spawned by the backend runtime. */
+export interface SpindleFrontendProcessContext {
+  /** Host-assigned ID unique within the extension runtime. */
+  processId: string;
+  /** Frontend handler key used when the backend called `spindle.frontendProcesses.spawn()`. */
+  kind: string;
+  /** Optional extension-defined stable key passed at spawn time. */
+  key?: string;
+  /** Arbitrary spawn payload provided by the backend. */
+  payload: unknown;
+  /** Optional backend-side bookkeeping metadata snapshot. */
+  metadata?: Record<string, unknown>;
+  /** Signal that startup completed successfully. Required for startup watchdogs. */
+  ready(): void;
+  /** Refresh the host-side heartbeat timer for long-lived loops. */
+  heartbeat(): void;
+  /** Send a process-scoped message back to the backend runtime. */
+  send(payload: unknown): void;
+  /** Subscribe to process-scoped messages from the backend runtime. */
+  onMessage(handler: (payload: unknown) => void): () => void;
+  /** Mark the process as completed and release host tracking. */
+  complete(result?: unknown): void;
+  /** Mark the process as failed. */
+  fail(error: string): void;
+  /** Called when the backend requests graceful termination. */
+  onStop(handler: (detail: { reason?: string }) => void): () => void;
+}
+
+/** Registry exposed to frontend modules for backend-spawned frontend processes. */
+export interface SpindleFrontendProcessRegistry {
+  /**
+   * Register a process handler for the given `kind`.
+   *
+   * The returned cleanup function unregisters the handler. If the handler
+   * itself returns a cleanup function, the host should call it when the
+   * process is stopped, replaced, or the extension is unloaded.
+   */
+  register(
+    kind: string,
+    handler: (
+      process: SpindleFrontendProcessContext,
+    ) => void | (() => void) | Promise<void | (() => void)>,
+  ): () => void;
+}
+
 /** Context object provided to frontend extension modules */
 export interface SpindleFrontendContext {
   dom: SpindleDOMHelper;
@@ -416,6 +463,8 @@ export interface SpindleFrontendContext {
   getActiveChat(): { chatId: string | null; characterId: string | null };
   sendToBackend(payload: unknown): void;
   onBackendMessage(handler: (payload: unknown) => void): () => void;
+  /** Structured lifecycle hooks for backend-spawned frontend processes. */
+  processes: SpindleFrontendProcessRegistry;
   messages: {
     registerTagInterceptor(
       options: SpindleMessageTagInterceptorOptions,

package/src/index.ts

@@ -41,6 +41,14 @@ export type {
   WorldBookEntryDTO,
   WorldBookEntryCreateDTO,
   WorldBookEntryUpdateDTO,
+  DatabankScopeDTO,
+  DatabankDocumentStatusDTO,
+  DatabankDTO,
+  DatabankCreateDTO,
+  DatabankUpdateDTO,
+  DatabankDocumentDTO,
+  DatabankDocumentCreateDTO,
+  DatabankDocumentUpdateDTO,
   PersonaDTO,
   LumiaItemDTO,
   PersonaCreateDTO,
@@ -67,9 +75,16 @@ export type {
   ColorRGB,
   ColorHSL,
   SpindleModalItemDTO,
-  SpindleCommandDTO,
-  SpindleCommandContextDTO,
-  GenerationStartedPayloadDTO,
+   SpindleCommandDTO,
+   SpindleCommandContextDTO,
+   FrontendProcessStateDTO,
+   FrontendProcessExitReasonDTO,
+   FrontendProcessSpawnOptionsDTO,
+   FrontendProcessListOptionsDTO,
+   FrontendProcessInfoDTO,
+   FrontendProcessLifecycleEventDTO,
+   FrontendProcessStopOptionsDTO,
+   GenerationStartedPayloadDTO,
   StreamTokenPayloadDTO,
   GenerationEndedPayloadDTO,
   GenerationStoppedPayloadDTO,
@@ -121,14 +136,16 @@ export type {
   SpindleContextMenuResult,
   SpindleModalOptions,
   SpindleModalHandle,
-  SpindleConfirmVariant,
-  SpindleConfirmOptions,
-  SpindleConfirmResult,
+   SpindleConfirmVariant,
+   SpindleConfirmOptions,
+   SpindleConfirmResult,
+   SpindleFrontendProcessContext,
+   SpindleFrontendProcessRegistry,
 } from "./dom";
 
 export type { ExtensionInfo } from "./extension-info";
 
-export type { SpindleAPI } from "./spindle-api";
+export type { SpindleAPI, FrontendProcessHandle } from "./spindle-api";
 
 export type {
   CouncilMember,

package/src/permissions.ts

@@ -13,6 +13,7 @@
  * - "characters"           — CRUD on character cards
  * - "chats"                — CRUD on chat sessions
  * - "personas"             — CRUD on personas
+ * - "databanks"            — CRUD on databanks and their documents
  * - "macro_interceptor"    — transform raw templates before macro parsing/dispatch
  */
 export type SpindlePermission =
@@ -30,6 +31,7 @@ export type SpindlePermission =
   | "characters"
   | "chats"
   | "world_books"
+  | "databanks"
   | "personas"
   | "push_notification"
   | "image_gen"
@@ -51,6 +53,7 @@ export const ALL_PERMISSIONS: readonly SpindlePermission[] = [
   "characters",
   "chats",
   "world_books",
+  "databanks",
   "personas",
   "push_notification",
   "image_gen",

package/src/spindle-api.ts

@@ -27,6 +27,12 @@ import type {
   WorldBookEntryDTO,
   WorldBookEntryCreateDTO,
   WorldBookEntryUpdateDTO,
+  DatabankDTO,
+  DatabankCreateDTO,
+  DatabankUpdateDTO,
+  DatabankDocumentDTO,
+  DatabankDocumentCreateDTO,
+  DatabankDocumentUpdateDTO,
   PersonaDTO,
   LumiaItemDTO,
   PersonaCreateDTO,
@@ -47,6 +53,11 @@ import type {
   SpindleModalItemDTO,
   SpindleCommandDTO,
   SpindleCommandContextDTO,
+  FrontendProcessSpawnOptionsDTO,
+  FrontendProcessListOptionsDTO,
+  FrontendProcessInfoDTO,
+  FrontendProcessLifecycleEventDTO,
+  FrontendProcessStopOptionsDTO,
   GenerationStartedPayloadDTO,
   StreamTokenPayloadDTO,
   GenerationEndedPayloadDTO,
@@ -64,6 +75,23 @@ import type {
   MessageContentProcessorResultDTO,
 } from "./api";
 
+export interface FrontendProcessHandle {
+  /** Host-assigned process ID unique within the extension runtime. */
+  readonly processId: string;
+  /** Frontend handler key the process was spawned against. */
+  readonly kind: string;
+  /** Optional extension-defined stable key. */
+  readonly key?: string;
+  /** Current known snapshot at the time the handle was created or last refreshed. */
+  readonly info: FrontendProcessInfoDTO;
+  /** Send a process-scoped message to the frontend instance. */
+  send(payload: unknown): void;
+  /** Request graceful termination. */
+  stop(options?: FrontendProcessStopOptionsDTO): Promise<void>;
+  /** Fetch the latest authoritative snapshot from the host. */
+  refresh(): Promise<FrontendProcessInfoDTO | null>;
+}
+
 /** 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. */
@@ -630,6 +658,27 @@ export interface SpindleAPI {
     getActivated(chatId: string, userId?: string): Promise<ActivatedWorldInfoEntryDTO[]>;
   };
 
+  /**
+   * Databank CRUD (permission: "databanks").
+   * Manage databanks plus the documents they contain.
+   */
+  databanks: {
+    list(options?: { limit?: number; offset?: number; scope?: "global" | "character" | "chat"; scopeId?: string | null; userId?: string }): Promise<{ data: DatabankDTO[]; total: number }>;
+    get(databankId: string, userId?: string): Promise<DatabankDTO | null>;
+    create(input: DatabankCreateDTO, userId?: string): Promise<DatabankDTO>;
+    update(databankId: string, input: DatabankUpdateDTO, userId?: string): Promise<DatabankDTO>;
+    delete(databankId: string, userId?: string): Promise<boolean>;
+    documents: {
+      list(databankId: string, options?: { limit?: number; offset?: number; userId?: string }): Promise<{ data: DatabankDocumentDTO[]; total: number }>;
+      get(documentId: string, userId?: string): Promise<DatabankDocumentDTO | null>;
+      create(databankId: string, input: DatabankDocumentCreateDTO, userId?: string): Promise<DatabankDocumentDTO>;
+      update(documentId: string, input: DatabankDocumentUpdateDTO, userId?: string): Promise<DatabankDocumentDTO>;
+      delete(documentId: string, userId?: string): Promise<boolean>;
+      getContent(documentId: string, userId?: string): Promise<{ content: string } | null>;
+      reprocess(documentId: string, userId?: string): Promise<{ success: true; status: "processing" }>;
+    };
+  };
+
   /**
    * Personas CRUD (permission: "personas").
    * Manage user personas (identity profiles).
@@ -788,6 +837,39 @@ export interface SpindleAPI {
   /** Receive messages from the frontend module (userId is the sender) */
   onFrontendMessage(handler: (payload: unknown, userId: string) => void): () => void;
 
+  /**
+   * Backend-owned lifecycle controller for tracked frontend processes.
+   *
+   * Use this when the frontend needs to run one or more long-lived loops,
+   * workers, or UI-adjacent controllers whose liveness must be observable from
+   * the backend runtime. The frontend side registers handlers by `kind` via
+   * `ctx.processes.register(kind, handler)`.
+   *
+   * This is layered on top of the existing backend/frontend messaging model,
+   * but adds startup acknowledgement, heartbeat timeouts, process-scoped
+   * messaging, and structured lifecycle events.
+   */
+  frontendProcesses: {
+    /**
+     * Spawn a frontend process and wait for the frontend handler to call
+     * `process.ready()`. If `startupTimeoutMs` elapses first, the promise
+     * rejects and the process transitions to `timed_out`.
+     */
+    spawn(options: FrontendProcessSpawnOptionsDTO): Promise<FrontendProcessHandle>;
+    /** List tracked frontend processes visible to this extension runtime. */
+    list(filter?: FrontendProcessListOptionsDTO): Promise<FrontendProcessInfoDTO[]>;
+    /** Get a single tracked process by ID. Returns `null` if it no longer exists. */
+    get(processId: string): Promise<FrontendProcessInfoDTO | null>;
+    /** Request graceful termination of a tracked process. */
+    stop(processId: string, options?: FrontendProcessStopOptionsDTO): Promise<void>;
+    /** Subscribe to lifecycle transitions (`starting`, `running`, `timed_out`, etc.). */
+    onLifecycle(handler: (event: FrontendProcessLifecycleEventDTO) => void): () => void;
+    /** Receive process-scoped messages sent from the frontend side. */
+    onMessage(
+      handler: (event: { processId: string; payload: unknown; userId: string }) => void,
+    ): () => void;
+  };
+
   /** Logging */
   log: {
     info(msg: string): void;
@@ -978,14 +1060,15 @@ export interface SpindleAPI {
      * Unlike `apply()`, this method does not let extensions push raw CSS
      * variables. Lumiverse derives the full light/dark variable maps from the
      * provided accent and preserves the user's glass, radius, font, and UI
-     * scale settings.
+     * scale settings. Pass `null` to clear the extension's active palette
+     * override when no valid color data is available.
      */
-    applyPalette(palette: ThemePaletteConfigDTO, userId?: string): Promise<void>;
+    applyPalette(palette: ThemePaletteConfigDTO | null, userId?: string): Promise<void>;
     /**
      * Remove all CSS variable overrides previously applied by this extension.
      * The UI reverts to the user's base theme.
      */
-    clear(): Promise<void>;
+    clear(userId?: string): Promise<void>;
     /**
      * Get a read-only snapshot of the user's current theme configuration.
      * Returns the base theme info (not including any extension overrides).