@rohal12/spindle 0.33.0 → 0.35.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.35.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/components/macros/WidgetInvocation.tsx

@@ -24,40 +24,93 @@ interface WidgetInvocationProps {
 }
 
 /**
- * Try to split a raw string into adjacent quoted string literals separated by
- * whitespace. Returns the individual quoted strings if the entire input is
- * consumed, or `null` if any non-quote/non-whitespace content is found.
+ * Check whether a whitespace-delimited token looks like a standalone value
+ * (not an operator or partial expression).
  */
-function trySplitAdjacentQuotes(raw: string): string[] | null {
+function isStandaloneValue(token: string): boolean {
+  const first = token[0]!;
+  // Quoted string
+  if (first === '"' || first === "'" || first === '`') return true;
+  // Variable ($var, _var, @var)
+  if (first === '$' || first === '_' || first === '@') return true;
+  // Number literal
+  if (/\d/.test(first)) return true;
+  // Signed number (-1, +2)
+  if (
+    (first === '-' || first === '+') &&
+    token.length > 1 &&
+    /\d/.test(token[1]!)
+  )
+    return true;
+  // Grouped expression or collection literal
+  if (first === '(' || first === '[' || first === '{') return true;
+  // Boolean / null / undefined
+  if (/^(true|false|null|undefined)$/.test(token)) return true;
+  // Negation (!$flag, !true)
+  if (first === '!' && token.length > 1) return true;
+  return false;
+}
+
+/**
+ * Try to split a raw string on whitespace at depth 0 (respecting quotes,
+ * parentheses, brackets, and braces). Each resulting token must pass
+ * `isStandaloneValue()` or the split is rejected and `null` is returned.
+ */
+function trySplitOnWhitespace(raw: string): string[] | null {
   const args: string[] = [];
-  let i = 0;
-
-  while (i < raw.length) {
-    // skip whitespace between quoted strings
-    while (i < raw.length && /\s/.test(raw[i]!)) i++;
-    if (i >= raw.length) break;
-
-    const quote = raw[i]!;
-    if (quote !== '"' && quote !== "'") return null;
-
-    // consume the quoted string
-    let str = quote;
-    i++;
-    while (i < raw.length) {
-      const ch = raw[i]!;
-      str += ch;
-      i++;
-      if (ch === quote && raw[i - 2] !== '\\') break;
+  let current = '';
+  let depth = 0;
+  let inString: string | null = null;
+
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i]!;
+
+    if (inString) {
+      current += ch;
+      if (ch === inString && raw[i - 1] !== '\\') inString = null;
+      continue;
+    }
+
+    if (ch === '"' || ch === "'" || ch === '`') {
+      inString = ch;
+      current += ch;
+      continue;
     }
 
-    // must be properly closed
-    if (str.length < 2 || str[str.length - 1] !== quote) return null;
+    if (ch === '(' || ch === '[' || ch === '{') {
+      depth++;
+      current += ch;
+      continue;
+    }
+
+    if (ch === ')' || ch === ']' || ch === '}') {
+      depth--;
+      current += ch;
+      continue;
+    }
 
-    args.push(str);
+    if (/\s/.test(ch) && depth === 0) {
+      if (current) {
+        args.push(current);
+        current = '';
+      }
+      continue;
+    }
+
+    current += ch;
   }
 
-  // only use this path when there are 2+ adjacent quoted strings
-  return args.length > 1 ? args : null;
+  if (current) args.push(current);
+
+  // Need 2+ tokens
+  if (args.length < 2) return null;
+
+  // Every token must be a standalone value (not an operator)
+  for (const arg of args) {
+    if (!isStandaloneValue(arg)) return null;
+  }
+
+  return args;
 }
 
 /**
@@ -113,10 +166,10 @@ export function splitArgs(raw: string): string[] {
   if (last) args.push(last);
 
   // If no commas were found and we got a single expression, try splitting
-  // it as adjacent quoted string literals (e.g. "Label" "target").
+  // on whitespace at depth 0 (e.g. "Label" "target", $var "text", $x $y).
   if (!hasComma && args.length === 1) {
-    const quoted = trySplitAdjacentQuotes(args[0]!);
-    if (quoted) return quoted;
+    const split = trySplitOnWhitespace(args[0]!);
+    if (split) return split;
   }
 
   return args;

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);
   }
 }