lumiverse-spindle-types 0.6.13 → 0.6.15

package/package.json

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

package/src/api.ts

@@ -1536,6 +1536,8 @@ export type RegexMacroModeDTO = "none" | "find" | "raw" | "escaped" | "after";
 
 export interface RegexScriptDTO {
   id: string;
+  /** True when the calling extension may update or delete this script. */
+  readonly can_mutate: boolean;
   name: string;
   script_id: string;
   find_regex: string;

package/src/dom.ts

@@ -120,6 +120,23 @@ export type SpindleMountPoint =
 
 // ── Drawer Tab ──
 
+/**
+ * Contextual documentation displayed by Lumiverse using its native
+ * guide viewer.
+ *
+ * Guide Markdown is rendered and sanitized by the host application.
+ */
+export interface SpindleGuideDefinition {
+  /** Markdown content for the guide. */
+  markdown: string;
+
+  /**
+   * Optional title shown by the guide viewer.
+   * Falls back to the title of the owning tab.
+   */
+  title?: string;
+}
+
 export interface SpindleDrawerTabOptions {
   /** Unique tab identifier. Used internally for routing and state. */
   id: string;
@@ -133,6 +150,8 @@ export interface SpindleDrawerTabOptions {
   keywords?: string[];
   /** Title shown in the panel header navbar. Falls back to `title` if omitted. Useful when the header needs a shorter label than the command palette entry. */
   headerTitle?: string;
+  /** Optional contextual documentation for this tab. */
+  guide?: SpindleGuideDefinition;
   /** URL to a 16x16 or 24x24 icon image. Mutually exclusive with `iconSvg`. */
   iconUrl?: string;
   /** Inline SVG string for the tab icon. Mutually exclusive with `iconUrl`. */
@@ -159,6 +178,8 @@ export interface SpindleCharacterEditorTabOptions {
   id: string;
   /** Label shown in the character editor tab bar. */
   title: string;
+  /** Optional contextual documentation for this tab. */
+  guide?: SpindleGuideDefinition;
 }
 
 export interface SpindleCharacterEditorTabHandle {
@@ -210,6 +231,8 @@ export interface SpindlePresetEditorTabOptions {
   id: string;
   /** Label shown in the Loom preset editor tab bar. */
   title: string;
+  /** Optional contextual documentation for this tab. */
+  guide?: SpindleGuideDefinition;
 }
 
 export interface SpindlePresetEditorTabHandle {

package/src/index.ts

@@ -269,6 +269,7 @@ export type {
   SpindleFrontendContext,
   SpindleFrontendModule,
   SpindleFrontendTeardown,
+  SpindleGuideDefinition,
   SpindleDrawerTabOptions,
   SpindleDrawerTabHandle,
   SpindleCharacterEditorTabOptions,

package/src/spindle-api.ts

@@ -312,9 +312,14 @@ export interface SpindleAPI {
   /** Subscribe to a Lumiverse event. Multi-user extensions should use the optional `userId` to keep per-user state and notifications isolated. */
   on(event: string, handler: (payload: unknown, userId?: string) => void): () => void;
 
-  /** Register a macro. Handler contexts expose `commit === false` during dry resolves. */
+  /**
+   * Register a macro owned by this extension. Registrations cannot replace
+   * system macros or macros owned by another extension. Preset/request dynamic
+   * macros take precedence over extension macros with the same name.
+   * Handler contexts expose `commit === false` during dry resolves.
+   */
   registerMacro(def: MacroDefinitionDTO): void;
-  /** Unregister a macro */
+  /** Unregister a macro owned by this extension. */
   unregisterMacro(name: string): void;
   /**
    * Push the latest value for a registered macro.
@@ -1012,10 +1017,14 @@ export interface SpindleAPI {
   };
 
   /**
-   * Regex Scripts CRUD (permission: "regex_scripts").
-   * Full access to regex scripts attached to the user's account, including
-   * global, character-scoped, and chat-scoped rules. Same shape Lumiverse uses
-   * internally during prompt assembly, response baking, and display rendering.
+   * Regex Scripts API (permission: "regex_scripts").
+   * Read access to regex scripts attached to the user's account and write
+   * access to unbound scripts created by the calling extension. Legacy or
+   * unattributed scripts, preset-bound scripts, and scripts owned by another
+   * extension remain readable and executable but cannot be updated or deleted.
+   * Check `RegexScriptDTO.can_mutate` before presenting mutation controls.
+   * Uses the same shape Lumiverse applies internally during prompt assembly,
+   * response baking, and display rendering.
    * For user-scoped extensions, userId is inferred from the extension owner.
    * For operator-scoped extensions, pass userId to scope to a specific user.
    */