lumiverse-spindle-types 0.4.43 → 0.4.45

package/package.json

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

package/src/api.ts

@@ -1008,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. */
@@ -1081,6 +1082,183 @@ 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;
+}
+
+// ─── Backend Process Lifecycle DTOs ─────────────────────────────────────
+
+/** High-level lifecycle state for an isolated backend subprocess tracked by the host. */
+export type BackendProcessStateDTO =
+  | "starting"
+  | "running"
+  | "stopping"
+  | "stopped"
+  | "completed"
+  | "failed"
+  | "timed_out";
+
+/** Terminal reason attached to backend-process lifecycle events and snapshots when available. */
+export type BackendProcessExitReasonDTO =
+  | "completed"
+  | "failed"
+  | "stopped"
+  | "timed_out"
+  | "backend_unloaded"
+  | "replaced";
+
+/** Options used when spawning an isolated backend subprocess from the backend worker. */
+export interface BackendProcessSpawnOptionsDTO {
+  /** Built JS entry file under the extension repo, typically in `dist/`. */
+  entry: string;
+  /** Optional logical label used for lifecycle filtering and dedupe semantics. Defaults to `entry`. */
+  kind?: string;
+  /** Optional extension-defined stable key used for dedupe / replacement semantics. */
+  key?: string;
+  /** Optional process-scoped startup payload delivered to the subprocess entry. */
+  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 subprocess does not call `process.ready()` within this window. */
+  startupTimeoutMs?: number;
+  /** Mark the subprocess timed out if it 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 backend subprocess list queries. */
+export interface BackendProcessListOptionsDTO {
+  userId?: string;
+  kind?: string;
+  key?: string;
+  state?: BackendProcessStateDTO;
+}
+
+/** Current host-tracked snapshot of an isolated backend subprocess. */
+export interface BackendProcessInfoDTO {
+  processId: string;
+  entry: string;
+  kind: string;
+  key?: string;
+  state: BackendProcessStateDTO;
+  userId?: string;
+  metadata?: Record<string, unknown>;
+  startedAt: string;
+  readyAt?: string;
+  lastHeartbeatAt?: string;
+  endedAt?: string;
+  exitReason?: BackendProcessExitReasonDTO;
+  error?: string;
+}
+
+/** Lifecycle event emitted to backend workers for isolated backend subprocesses. */
+export interface BackendProcessLifecycleEventDTO {
+  processId: string;
+  entry: string;
+  kind: string;
+  key?: string;
+  userId?: string;
+  state: BackendProcessStateDTO;
+  previousState?: BackendProcessStateDTO;
+  at: string;
+  exitReason?: BackendProcessExitReasonDTO;
+  error?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/** Options for graceful isolated-backend-process termination. */
+export interface BackendProcessStopOptionsDTO {
+  userId?: string;
+  /** Optional reason surfaced to the subprocess stop handler. */
+  reason?: string;
+}
+
 // ─── Generation Event Payload DTOs ──────────────────────────────────────
 
 /** Payload for `GENERATION_STARTED` events. */
@@ -1641,6 +1819,18 @@ 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 }
+  // ─── Backend Process Lifecycle (free tier) ────────────────────────────
+  | { type: "backend_process_spawn"; requestId: string; options: BackendProcessSpawnOptionsDTO }
+  | { type: "backend_process_list"; requestId: string; filter?: BackendProcessListOptionsDTO }
+  | { type: "backend_process_get"; requestId: string; processId: string }
+  | { type: "backend_process_stop"; requestId: string; processId: string; options?: BackendProcessStopOptionsDTO }
+  | { type: "backend_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") ──────────────────────────
@@ -1651,7 +1841,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") ─────────────────────
@@ -1757,6 +1947,10 @@ 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: "backend_process_lifecycle"; event: BackendProcessLifecycleEventDTO }
+  | { type: "backend_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

@@ -75,9 +75,23 @@ export type {
   ColorRGB,
   ColorHSL,
   SpindleModalItemDTO,
-  SpindleCommandDTO,
-  SpindleCommandContextDTO,
-  GenerationStartedPayloadDTO,
+   SpindleCommandDTO,
+   SpindleCommandContextDTO,
+   FrontendProcessStateDTO,
+   FrontendProcessExitReasonDTO,
+   FrontendProcessSpawnOptionsDTO,
+   FrontendProcessListOptionsDTO,
+   FrontendProcessInfoDTO,
+   FrontendProcessLifecycleEventDTO,
+   FrontendProcessStopOptionsDTO,
+   BackendProcessStateDTO,
+   BackendProcessExitReasonDTO,
+   BackendProcessSpawnOptionsDTO,
+   BackendProcessListOptionsDTO,
+   BackendProcessInfoDTO,
+   BackendProcessLifecycleEventDTO,
+   BackendProcessStopOptionsDTO,
+    GenerationStartedPayloadDTO,
   StreamTokenPayloadDTO,
   GenerationEndedPayloadDTO,
   GenerationStoppedPayloadDTO,
@@ -129,14 +143,22 @@ 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,
+  BackendProcessHandle,
+  SpindleBackendProcessContext,
+  SpindleBackendProcessModule,
+} from "./spindle-api";
 
 export type {
   CouncilMember,

package/src/spindle-api.ts

@@ -53,6 +53,16 @@ import type {
   SpindleModalItemDTO,
   SpindleCommandDTO,
   SpindleCommandContextDTO,
+  FrontendProcessSpawnOptionsDTO,
+  FrontendProcessListOptionsDTO,
+  FrontendProcessInfoDTO,
+  FrontendProcessLifecycleEventDTO,
+  FrontendProcessStopOptionsDTO,
+  BackendProcessSpawnOptionsDTO,
+  BackendProcessListOptionsDTO,
+  BackendProcessInfoDTO,
+  BackendProcessLifecycleEventDTO,
+  BackendProcessStopOptionsDTO,
   GenerationStartedPayloadDTO,
   StreamTokenPayloadDTO,
   GenerationEndedPayloadDTO,
@@ -70,6 +80,79 @@ 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>;
+}
+
+export interface BackendProcessHandle {
+  /** Host-assigned process ID unique within the extension runtime. */
+  readonly processId: string;
+  /** Built subprocess entry file spawned by the host. */
+  readonly entry: string;
+  /** Logical process kind used for filtering and dedupe semantics. */
+  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: BackendProcessInfoDTO;
+  /** Send a process-scoped message to the isolated subprocess. */
+  send(payload: unknown): void;
+  /** Request graceful termination. */
+  stop(options?: BackendProcessStopOptionsDTO): Promise<void>;
+  /** Fetch the latest authoritative snapshot from the host. */
+  refresh(): Promise<BackendProcessInfoDTO | null>;
+}
+
+/** Controller passed to a backend subprocess entry exported by the extension. */
+export interface SpindleBackendProcessContext {
+  /** Host-assigned ID unique within the extension runtime. */
+  processId: string;
+  /** Built entry file the host spawned. */
+  entry: string;
+  /** Logical process kind supplied during spawn. */
+  kind: string;
+  /** Optional extension-defined stable key passed at spawn time. */
+  key?: string;
+  /** Arbitrary spawn payload provided by the parent backend runtime. */
+  payload: unknown;
+  /** Optional backend-side bookkeeping metadata snapshot. */
+  metadata?: Record<string, unknown>;
+  /** Target user for operator-scoped spawns. */
+  userId?: string;
+  /** 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 parent backend runtime. */
+  send(payload: unknown): void;
+  /** Subscribe to process-scoped messages from the parent backend runtime. */
+  onMessage(handler: (payload: unknown) => void): () => void;
+  /** Mark the subprocess as completed and release host tracking. */
+  complete(result?: unknown): void;
+  /** Mark the subprocess as failed. */
+  fail(error: string): void;
+  /** Called when the parent backend runtime requests graceful termination. */
+  onStop(handler: (detail: { reason?: string }) => void): () => void;
+}
+
+export type SpindleBackendProcessModule = {
+  default?: (process: SpindleBackendProcessContext) => void | (() => void) | Promise<void | (() => void)>;
+  run?: (process: SpindleBackendProcessContext) => void | (() => void) | Promise<void | (() => 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. */
@@ -815,6 +898,69 @@ 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;
+  };
+
+  /**
+   * Host-owned lifecycle controller for isolated backend subprocesses.
+   *
+   * Use this when one slice of backend extension logic may block or hang and
+   * you need the host to retain kill authority via startup and heartbeat
+   * watchdogs. The spawned entry receives a
+   * {@link SpindleBackendProcessContext} and communicates only with its parent
+   * backend runtime through process-scoped messages.
+   */
+  backendProcesses: {
+    /**
+     * Spawn an isolated backend subprocess and wait for the entry to call
+     * `process.ready()`. If `startupTimeoutMs` elapses first, the promise
+     * rejects and the process transitions to `timed_out`.
+     */
+    spawn(options: BackendProcessSpawnOptionsDTO): Promise<BackendProcessHandle>;
+    /** List tracked backend subprocesses visible to this extension runtime. */
+    list(filter?: BackendProcessListOptionsDTO): Promise<BackendProcessInfoDTO[]>;
+    /** Get a single tracked subprocess by ID. Returns `null` if it no longer exists. */
+    get(processId: string): Promise<BackendProcessInfoDTO | null>;
+    /** Request graceful termination of a tracked subprocess. */
+    stop(processId: string, options?: BackendProcessStopOptionsDTO): Promise<void>;
+    /** Subscribe to lifecycle transitions (`starting`, `running`, `timed_out`, etc.). */
+    onLifecycle(handler: (event: BackendProcessLifecycleEventDTO) => void): () => void;
+    /** Receive process-scoped messages sent from the subprocess entry. */
+    onMessage(
+      handler: (event: { processId: string; payload: unknown; userId: string }) => void,
+    ): () => void;
+  };
+
   /** Logging */
   log: {
     info(msg: string): void;
@@ -1005,14 +1151,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).