@rohal12/spindle 0.33.0 → 0.34.0

package/dist/pkg/macro-registry.json

@@ -0,0 +1,282 @@
+[
+  {
+    "name": "set",
+    "block": false,
+    "subMacros": [],
+    "source": "builtin"
+  },
+  {
+    "name": "print",
+    "block": false,
+    "subMacros": [],
+    "interpolate": true,
+    "merged": true,
+    "source": "builtin"
+  },
+  {
+    "name": "computed",
+    "block": false,
+    "subMacros": [],
+    "merged": true,
+    "source": "builtin"
+  },
+  {
+    "name": "meter",
+    "block": false,
+    "subMacros": [],
+    "interpolate": true,
+    "merged": true,
+    "source": "builtin"
+  },
+  {
+    "name": "if",
+    "block": true,
+    "subMacros": [],
+    "interpolate": true,
+    "merged": true,
+    "source": "builtin"
+  },
+  {
+    "name": "for",
+    "block": true,
+    "subMacros": [],
+    "interpolate": true,
+    "merged": true,
+    "source": "builtin"
+  },
+  {
+    "name": "do",
+    "block": true,
+    "subMacros": [],
+    "source": "builtin"
+  },
+  {
+    "name": "button",
+    "block": true,
+    "subMacros": [],
+    "interpolate": true,
+    "source": "builtin"
+  },
+  {
+    "name": "link",
+    "block": true,
+    "subMacros": [],
+    "interpolate": true,
+    "source": "builtin"
+  },
+  {
+    "name": "switch",
+    "block": true,
+    "subMacros": [
+      "case",
+      "default"
+    ],
+    "merged": true,
+    "source": "builtin"
+  },
+  {
+    "name": "timed",
+    "block": true,
+    "subMacros": [
+      "next"
+    ],
+    "interpolate": true,
+    "source": "builtin"
+  },
+  {
+    "name": "repeat",
+    "block": true,
+    "subMacros": [],
+    "interpolate": true,
+    "source": "builtin"
+  },
+  {
+    "name": "stop",
+    "block": false,
+    "subMacros": [],
+    "source": "builtin"
+  },
+  {
+    "name": "type",
+    "block": true,
+    "subMacros": [],
+    "interpolate": true,
+    "source": "builtin"
+  },
+  {
+    "name": "widget",
+    "block": true,
+    "subMacros": [],
+    "source": "builtin"
+  },
+  {
+    "name": "story-title",
+    "block": false,
+    "subMacros": [],
+    "source": "builtin"
+  },
+  {
+    "name": "back",
+    "block": false,
+    "subMacros": [],
+    "source": "builtin"
+  },
+  {
+    "name": "forward",
+    "block": false,
+    "subMacros": [],
+    "source": "builtin"
+  },
+  {
+    "name": "quicksave",
+    "block": false,
+    "subMacros": [],
+    "source": "builtin"
+  },
+  {
+    "name": "quickload",
+    "block": false,
+    "subMacros": [],
+    "source": "builtin"
+  },
+  {
+    "name": "restart",
+    "block": false,
+    "subMacros": [],
+    "source": "builtin"
+  },
+  {
+    "name": "saves",
+    "block": false,
+    "subMacros": [],
+    "source": "builtin"
+  },
+  {
+    "name": "settings",
+    "block": false,
+    "subMacros": [],
+    "source": "builtin"
+  },
+  {
+    "name": "dialog",
+    "block": true,
+    "subMacros": [],
+    "interpolate": true,
+    "source": "builtin"
+  },
+  {
+    "name": "save-manager",
+    "block": false,
+    "subMacros": [],
+    "source": "builtin"
+  },
+  {
+    "name": "settings-controls",
+    "block": false,
+    "subMacros": [],
+    "source": "builtin"
+  },
+  {
+    "name": "include",
+    "block": false,
+    "subMacros": [],
+    "interpolate": true,
+    "merged": true,
+    "source": "builtin"
+  },
+  {
+    "name": "nobr",
+    "block": true,
+    "subMacros": [],
+    "source": "builtin"
+  },
+  {
+    "name": "goto",
+    "block": false,
+    "subMacros": [],
+    "merged": true,
+    "source": "builtin"
+  },
+  {
+    "name": "unset",
+    "block": false,
+    "subMacros": [],
+    "source": "builtin"
+  },
+  {
+    "name": "textbox",
+    "block": false,
+    "subMacros": [],
+    "storeVar": true,
+    "source": "builtin"
+  },
+  {
+    "name": "numberbox",
+    "block": false,
+    "subMacros": [],
+    "storeVar": true,
+    "source": "builtin"
+  },
+  {
+    "name": "textarea",
+    "block": false,
+    "subMacros": [],
+    "storeVar": true,
+    "source": "builtin"
+  },
+  {
+    "name": "checkbox",
+    "block": false,
+    "subMacros": [],
+    "storeVar": true,
+    "source": "builtin"
+  },
+  {
+    "name": "radiobutton",
+    "block": false,
+    "subMacros": [],
+    "storeVar": true,
+    "source": "builtin"
+  },
+  {
+    "name": "listbox",
+    "block": true,
+    "subMacros": [
+      "option"
+    ],
+    "storeVar": true,
+    "source": "builtin"
+  },
+  {
+    "name": "cycle",
+    "block": true,
+    "subMacros": [],
+    "storeVar": true,
+    "source": "builtin"
+  },
+  {
+    "name": "span",
+    "block": true,
+    "subMacros": [],
+    "source": "builtin"
+  },
+  {
+    "name": "passage",
+    "block": false,
+    "subMacros": [],
+    "interpolate": true,
+    "source": "builtin"
+  },
+  {
+    "name": "watch",
+    "block": false,
+    "subMacros": [],
+    "source": "builtin"
+  },
+  {
+    "name": "unwatch",
+    "block": false,
+    "subMacros": [],
+    "source": "builtin"
+  }
+]

package/dist/pkg/tooling.js

@@ -0,0 +1,44 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Load built-in macro metadata generated at build time
+const registryPath = join(__dirname, 'macro-registry.json');
+let builtins = [];
+try {
+  builtins = JSON.parse(readFileSync(registryPath, 'utf-8'));
+} catch {
+  // macro-registry.json not yet built — empty builtins
+}
+
+const metadata = new Map();
+for (const m of builtins) metadata.set(m.name.toLowerCase(), m);
+
+/**
+ * Metadata-only defineMacro for tooling.
+ * Captures macro metadata without creating Preact components.
+ * LSP servers call this to register user-defined macros discovered in story scripts.
+ */
+export function defineMacro(config) {
+  const name = config.name.toLowerCase();
+  metadata.set(name, {
+    name: config.name,
+    block: config.block ?? (config.subMacros?.length > 0 ? true : false),
+    subMacros: config.subMacros ?? [],
+    storeVar: config.storeVar,
+    interpolate: config.interpolate,
+    merged: config.merged,
+    description: config.description,
+    parameters: config.parameters,
+    source: 'user',
+  });
+}
+
+/**
+ * Return metadata for all registered macros (built-in + user-defined).
+ */
+export function getMacroRegistry() {
+  return Array.from(metadata.values());
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",
@@ -25,16 +25,22 @@
     ".": {
       "types": "./types/index.d.ts",
       "import": "./dist/pkg/index.js"
+    },
+    "./tooling": {
+      "types": "./types/tooling.d.ts",
+      "import": "./dist/pkg/tooling.js"
     }
   },
   "files": [
     "dist/pkg/index.js",
     "dist/pkg/format.js",
+    "dist/pkg/tooling.js",
+    "dist/pkg/macro-registry.json",
     "types",
     "src"
   ],
   "scripts": {
-    "build": "vite build && bun run scripts/build-format.ts",
+    "build": "vite build && bun run scripts/build-format.ts && bun run scripts/dump-macro-registry.ts",
     "compile": "bun run scripts/compile-story.ts",
     "preview": "bun run build && bun run compile",
     "test": "vitest run",

package/src/components/macros/Button.tsx

@@ -10,6 +10,7 @@ import {
 
 defineMacro({
   name: 'button',
+  block: true,
   interpolate: true,
   render({ rawArgs, children = [] }, ctx) {
     const label = ctx.resolve?.(rawArgs.replace(/^["']|["']$/g, '')) ?? rawArgs;

package/src/components/macros/Cycle.tsx

@@ -2,6 +2,7 @@ import { defineMacro } from '../../define-macro';
 
 defineMacro({
   name: 'cycle',
+  block: true,
   storeVar: true,
   render({ children = [] }, ctx) {
     const options = ctx.extractOptions(children);

package/src/components/macros/Do.tsx

@@ -2,6 +2,7 @@ import { defineMacro } from '../../define-macro';
 
 defineMacro({
   name: 'do',
+  block: true,
   render({ children = [] }, ctx) {
     const code = ctx.collectText(children);
 

package/src/components/macros/For.tsx

@@ -91,6 +91,7 @@ function ForIteration({
 
 defineMacro({
   name: 'for',
+  block: true,
   interpolate: true,
   merged: true,
   render({ rawArgs, children = [] }, ctx) {

package/src/components/macros/If.tsx

@@ -4,6 +4,7 @@ import type { Branch } from '../../markup/ast';
 
 defineMacro({
   name: 'if',
+  block: true,
   interpolate: true,
   merged: true,
   render({ branches = [] }, ctx) {

package/src/components/macros/MacroLink.tsx

@@ -56,6 +56,7 @@ function renderChildrenDetached(
 
 defineMacro({
   name: 'link',
+  block: true,
   interpolate: true,
   render({ rawArgs, children = [] }, ctx) {
     const { display, passage } = parseArgs(rawArgs);

package/src/components/macros/Nobr.tsx

@@ -3,6 +3,7 @@ import { NobrContext } from '../../markup/render';
 
 defineMacro({
   name: 'nobr',
+  block: true,
   render({ children = [] }, ctx) {
     return ctx.wrap(
       ctx.h(

package/src/components/macros/Repeat.tsx

@@ -8,6 +8,7 @@ export const RepeatContext = createContext<{ stop: () => void }>({
 
 defineMacro({
   name: 'repeat',
+  block: true,
   interpolate: true,
   render({ rawArgs, children = [] }, ctx) {
     const { useState, useEffect, useCallback } = ctx.hooks;

package/src/components/macros/Span.tsx

@@ -2,6 +2,7 @@ import { defineMacro } from '../../define-macro';
 
 defineMacro({
   name: 'span',
+  block: true,
   render({ children = [] }, ctx) {
     return ctx.wrap(ctx.renderNodes(children));
   },

package/src/components/macros/Type.tsx

@@ -3,6 +3,7 @@ import { defineMacro } from '../../define-macro';
 
 defineMacro({
   name: 'type',
+  block: true,
   interpolate: true,
   render({ rawArgs, children = [] }, ctx) {
     const { useState, useEffect, useRef } = ctx.hooks;

package/src/components/macros/Widget.tsx

@@ -10,6 +10,7 @@ function parseWidgetDef(rawArgs: string): { name: string; params: string[] } {
 
 defineMacro({
   name: 'widget',
+  block: true,
   render({ rawArgs, children = [] }, ctx) {
     const { name, params } = parseWidgetDef(rawArgs);
 

package/src/define-macro.ts

@@ -27,8 +27,12 @@ import type { UseActionOptions } from './hooks/use-action';
 import { collectText } from './utils/extract-text';
 import { currentSourceLocation } from './utils/source-location';
 import { parseVarArgs, extractOptions } from './components/macros/option-utils';
-import { registerMacro, registerSubMacro } from './registry';
-import type { MacroProps } from './registry';
+import {
+  registerMacro,
+  registerSubMacro,
+  registerMacroMetadata,
+} from './registry';
+import type { MacroProps, ParameterDef } from './registry';
 import { registerBlockMacro } from './markup/ast';
 
 export function macroClass(type: string, className?: string): string {
@@ -81,6 +85,8 @@ export interface MacroDefinition {
   interpolate?: boolean;
   merged?: boolean;
   storeVar?: boolean;
+  description?: string;
+  parameters?: ParameterDef[];
   render: (props: MacroProps, ctx: MacroContext) => VNode | null;
 }
 
@@ -121,7 +127,10 @@ function setByPath(
   target[segments[segments.length - 1]!] = value;
 }
 
-export function defineMacro(config: MacroDefinition): void {
+export function defineMacro(
+  config: MacroDefinition,
+  source: 'builtin' | 'user' = 'builtin',
+): void {
   function Wrapper(props: MacroProps) {
     // className/id resolved first (interpolate may transform them)
     let className = props.className;
@@ -196,13 +205,27 @@ export function defineMacro(config: MacroDefinition): void {
   }
 
   registerMacro(config.name, Wrapper);
+
+  // Store metadata for tooling API
+  const isBlock =
+    config.block === true ||
+    (config.block !== false && (config.subMacros?.length ?? 0) > 0);
+  registerMacroMetadata(config.name, {
+    name: config.name,
+    block: isBlock,
+    subMacros: config.subMacros ?? [],
+    storeVar: config.storeVar,
+    interpolate: config.interpolate,
+    merged: config.merged,
+    description: config.description,
+    parameters: config.parameters,
+    source,
+  });
+
   if (config.subMacros) {
     for (const sub of config.subMacros) registerSubMacro(sub);
   }
-  if (
-    config.block === true ||
-    (config.block !== false && config.subMacros && config.subMacros.length > 0)
-  ) {
+  if (isBlock) {
     registerBlockMacro(config.name);
   }
 }

package/src/registry.ts

@@ -31,3 +31,38 @@ export function registerSubMacro(name: string): void {
 export function isSubMacro(name: string): boolean {
   return subMacros.has(name.toLowerCase());
 }
+
+export interface ParameterDef {
+  name: string;
+  required?: boolean;
+  description?: string;
+}
+
+export interface MacroMetadata {
+  name: string;
+  block: boolean;
+  subMacros: string[];
+  storeVar?: boolean;
+  interpolate?: boolean;
+  merged?: boolean;
+  source: 'builtin' | 'user';
+  description?: string;
+  parameters?: ParameterDef[];
+}
+
+const metadataRegistry = new Map<string, MacroMetadata>();
+
+export function registerMacroMetadata(
+  name: string,
+  metadata: MacroMetadata,
+): void {
+  metadataRegistry.set(name.toLowerCase(), metadata);
+}
+
+export function getMacroRegistry(): MacroMetadata[] {
+  return Array.from(metadataRegistry.values());
+}
+
+export function clearMetadataRegistry(): void {
+  metadataRegistry.clear();
+}

package/src/story-api.ts

@@ -6,6 +6,8 @@ import { setTitleGenerator } from './saves/save-manager';
 import { registerClass } from './class-registry';
 import { defineMacro } from './define-macro';
 import type { MacroDefinition } from './define-macro';
+import { getMacroRegistry as _getMacroRegistry } from './registry';
+import type { MacroMetadata } from './registry';
 import {
   getActions,
   getAction,
@@ -33,6 +35,7 @@ import type { WatchOptions } from './triggers';
 import type { TransitionConfig } from './transition';
 
 export type { StoryAction };
+export type { MacroMetadata };
 
 type NavigateCallback = (to: string, from: string) => void;
 type ActionsChangedCallback = () => void;
@@ -69,6 +72,7 @@ export interface StoryAPI {
   readonly settings: typeof settings;
   registerClass(name: string, ctor: new (...args: any[]) => any): void;
   defineMacro(config: MacroDefinition): void;
+  getMacroRegistry(): MacroMetadata[];
   readonly saves: {
     setTitleGenerator(fn: (payload: SavePayload) => string): void;
   };
@@ -229,7 +233,11 @@ function createStoryAPI(): StoryAPI {
     },
 
     defineMacro(config: MacroDefinition): void {
-      defineMacro(config);
+      defineMacro(config, 'user');
+    },
+
+    getMacroRegistry(): MacroMetadata[] {
+      return _getMacroRegistry();
     },
 
     saves: {