@rohal12/spindle 0.45.1 → 0.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.45.1",
+  "version": "0.47.0",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",

package/src/define-macro.ts

@@ -88,7 +88,7 @@ export interface MacroDefinition {
   storeVar?: boolean;
   description?: string;
   parameters?: ParameterDef[];
-  render: (props: MacroProps, ctx: MacroContext) => VNode | null;
+  render: (props: MacroProps, ctx: MacroContext) => ComponentChildren;
 }
 
 const sharedHooks = {

package/src/index.tsx

@@ -3,7 +3,11 @@ import { App } from './components/App';
 import { parseStoryData } from './parser';
 import { useStoryStore, enterRuntimePhase } from './store';
 import { emit } from './event-emitter';
-import { installStoryAPI, getReadyPromise } from './story-api';
+import {
+  installStoryAPI,
+  getReadyPromise,
+  setDeclaredVariables,
+} from './story-api';
 import { resetIdCounters } from './action-registry';
 import { executeStoryInit } from './story-init';
 import { checkTriggers, reinitTriggerState } from './triggers';
@@ -118,6 +122,7 @@ function boot() {
   }
 
   defaults = extractDefaults(schema);
+  setDeclaredVariables(Object.keys(defaults), Object.keys(transientDefaults));
 
   useStoryStore.getState().init(storyData, defaults, transientDefaults);
 

package/src/story-api.ts

@@ -232,11 +232,63 @@ export interface StoryAPI {
   };
 }
 
+// Names declared in StoryVariables / StoryTransients, registered at boot.
+// null until a schema is registered (e.g. unit tests that init the store
+// directly), in which case Story.set() does not check names.
+let declaredVariables: ReadonlySet<string> | null = null;
+let declaredTransients: ReadonlySet<string> | null = null;
+const warnedUndeclared = new Set<string>();
+
+/** Register the declared variable names so Story.set() can flag typos. */
+export function setDeclaredVariables(
+  variables: Iterable<string>,
+  transients: Iterable<string> = [],
+): void {
+  declaredVariables = new Set(variables);
+  declaredTransients = new Set(transients);
+  warnedUndeclared.clear();
+}
+
+/** Test-only: forget the registered declarations. */
+export function _resetDeclaredVariables(): void {
+  declaredVariables = null;
+  declaredTransients = null;
+  warnedUndeclared.clear();
+}
+
+/**
+ * Split an API variable name into namespace and key. Accepts the bare name
+ * (`hp`), the `$` sigil authors use in passages (`$hp`), and `%` for
+ * transients (`%npcs`). Dot-paths are kept in the key.
+ */
+function parseName(name: string): {
+  isTransient: boolean;
+  key: string;
+} {
+  if (name.startsWith('%')) return { isTransient: true, key: name.slice(1) };
+  if (name.startsWith('$')) return { isTransient: false, key: name.slice(1) };
+  return { isTransient: false, key: name };
+}
+
+function warnIfUndeclared(isTransient: boolean, key: string): void {
+  const declared = isTransient ? declaredTransients : declaredVariables;
+  if (!declared) return;
+  const root = key.split('.')[0]!;
+  if (declared.has(root)) return;
+  const label = (isTransient ? '%' : '$') + root;
+  if (warnedUndeclared.has(label)) return;
+  warnedUndeclared.add(label);
+  const where = isTransient ? 'StoryTransients' : 'StoryVariables';
+  console.warn(
+    `spindle: Story.set() wrote ${label}, which is not declared in ${where}. Passages cannot reference it; check the name or declare it.`,
+  );
+}
+
 /** Set a single variable, resolving dot-paths if present. */
 function setOne(name: string, value: unknown): void {
-  const isTransient = name.startsWith('%');
-  const key = isTransient ? name.slice(1) : name;
+  const { isTransient, key } = parseName(name);
   const namespace = isTransient ? 'transient' : 'variables';
+  warnIfUndeclared(isTransient, key);
 
   if (key.includes('.')) {
     useStoryStore.setState((state) => {
@@ -255,8 +307,7 @@ function setOne(name: string, value: unknown): void {
 function createStoryAPI(): StoryAPI {
   return {
     get(name: string): unknown {
-      const isTransient = name.startsWith('%');
-      const key = isTransient ? name.slice(1) : name;
+      const { isTransient, key } = parseName(name);
       const store = isTransient
         ? useStoryStore.getState().transient
         : useStoryStore.getState().variables;

package/src/types-drift-check.ts

@@ -23,3 +23,71 @@ import type { parseStoryVariables as PublishedParse } from '../types/tooling';
 const _parseSourceToPublished: typeof PublishedParse = {} as typeof SourceParse;
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 const _parsePublishedToSource: typeof SourceParse = {} as typeof PublishedParse;
+
+// Custom macro API: the published MacroContext/MacroDefinition must match the
+// ones defineMacro() actually passes and accepts.
+import type {
+  MacroContext as SourceMacroContext,
+  MacroDefinition as SourceMacroDefinition,
+} from './define-macro';
+import type { MacroProps as SourceMacroProps } from './registry';
+import type { ASTNode as SourceASTNode } from './markup/ast';
+import type {
+  MacroContext as PublishedMacroContext,
+  MacroDefinition as PublishedMacroDefinition,
+  MacroProps as PublishedMacroProps,
+  ASTNode as PublishedASTNode,
+} from '../types/index';
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _ctxSourceToPublished: PublishedMacroContext = {} as SourceMacroContext;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _ctxPublishedToSource: SourceMacroContext = {} as PublishedMacroContext;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _defSourceToPublished: PublishedMacroDefinition =
+  {} as SourceMacroDefinition;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _defPublishedToSource: SourceMacroDefinition =
+  {} as PublishedMacroDefinition;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _propsSourceToPublished: PublishedMacroProps = {} as SourceMacroProps;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _propsPublishedToSource: SourceMacroProps = {} as PublishedMacroProps;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _astSourceToPublished: PublishedASTNode = {} as SourceASTNode;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _astPublishedToSource: SourceASTNode = {} as PublishedASTNode;
+
+// A typical custom macro written against the published types must type-check,
+// and misuse of the hooks must not (no `any` leaking through).
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _exampleMacro: PublishedMacroDefinition = {
+  name: 'counter',
+  block: true,
+  render(props, ctx) {
+    const [count, setCount] = ctx.hooks.useState(0);
+    const countIsNumber: number = count;
+    setCount((n) => n + 1);
+    // @ts-expect-error -- state setter is typed by the initial value
+    setCount('one');
+    const ref = ctx.hooks.useRef<HTMLSpanElement>(null);
+    ctx.hooks.useEffect(() => {
+      ref.current?.focus();
+      return () => undefined;
+    }, [count]);
+    // @ts-expect-error -- deps must be an array
+    ctx.hooks.useEffect(() => undefined, 'count');
+    const doubled: number = ctx.hooks.useMemo(() => count * 2, [count]);
+    const body = ctx.renderNodes(props.children ?? [], { nobr: true });
+    const label: string = ctx.collectText(props.children ?? []);
+    return ctx.wrap(
+      ctx.h(
+        'span',
+        { ref, class: ctx.cls, title: label },
+        body,
+        countIsNumber,
+        doubled,
+      ),
+    );
+  },
+};

package/types/index.d.ts

@@ -1,3 +1,14 @@
+import type { ComponentChildren, VNode, h } from 'preact';
+import type {
+  useState,
+  useRef,
+  useEffect,
+  useLayoutEffect,
+  useCallback,
+  useMemo,
+  useContext,
+} from 'preact/hooks';
+
 // Format metadata (used by twee-ts)
 export declare const name: string;
 export declare const version: string;
@@ -242,6 +253,68 @@ export interface MacroMetadata {
   parameters?: ParameterDef[];
 }
 
+/** Plain text in a parsed passage. */
+export interface TextNode {
+  type: 'text';
+  value: string;
+}
+
+/** A variable display such as `{$hp}`, `{_tmp}`, `{@local}` or `{%transient}`. */
+export interface VariableNode {
+  type: 'variable';
+  name: string;
+  scope: 'variable' | 'temporary' | 'local' | 'transient';
+  className?: string;
+  id?: string;
+}
+
+/** An expression display such as `{= $hp * 2}`. */
+export interface ExpressionNode {
+  type: 'expression';
+  expression: string;
+  className?: string;
+  id?: string;
+}
+
+/** One branch of a block macro (`{elseif}`, `{else}`, `{case}`, ...). */
+export interface Branch {
+  rawArgs: string;
+  className?: string;
+  id?: string;
+  children: ASTNode[];
+}
+
+/** A macro invocation, with its body and branches for block macros. */
+export interface MacroNode {
+  type: 'macro';
+  name: string;
+  rawArgs: string;
+  children: ASTNode[];
+  branches?: Branch[];
+  className?: string;
+  id?: string;
+}
+
+/** An HTML element written in passage markup. */
+export interface HtmlNode {
+  type: 'html';
+  tag: string;
+  attributes: Record<string, string>;
+  children: ASTNode[];
+}
+
+/**
+ * A node of a parsed passage. Macros receive their body as `props.children`
+ * and render it with `ctx.renderNodes()`.
+ * @see {@link ../../src/markup/ast.ts} for the implementation.
+ */
+export type ASTNode =
+  | TextNode
+  | VariableNode
+  | ExpressionNode
+  | MacroNode
+  | HtmlNode;
+
 /**
  * Props passed to a macro's render function.
  * @see {@link ../../src/registry.ts} for the implementation.
@@ -250,13 +323,8 @@ export interface MacroProps {
   rawArgs: string;
   className?: string;
   id?: string;
-  children?: any[];
-  branches?: Array<{
-    rawArgs: string;
-    className?: string;
-    id?: string;
-    children: any[];
-  }>;
+  children?: ASTNode[];
+  branches?: Branch[];
 }
 
 /**
@@ -278,8 +346,9 @@ export interface UseActionOptions {
 
 /**
  * Context object passed to a macro's render function alongside props.
- * Internal Preact/AST types are represented as `any` since consumers
- * may not have Preact type definitions installed.
+ *
+ * Rendering helpers and hooks are Preact's own (`preact` is a dependency of
+ * this package), so `ctx.hooks.useState<T>()`, `ctx.h()` etc. are fully typed.
  * @see {@link ../../src/define-macro.ts} for the implementation.
  */
 export interface MacroContext {
@@ -301,26 +370,38 @@ export interface MacroContext {
   setValue?: (value: unknown) => void;
   getValue?: () => unknown;
   evaluate?: (expr: string) => unknown;
-  collectText: (nodes: any[]) => string;
+  /** Concatenate the text nodes of an AST (e.g. a macro body holding a passage name). */
+  collectText: (nodes: ASTNode[]) => string;
+  /** Source location of the current passage, for error messages. */
   sourceLocation: () => string;
   parseVarArgs: (rawArgs: string) => { varName: string; placeholder: string };
-  extractOptions: (children: any[]) => string[];
-  wrap: (content: any) => any;
+  /** Collect the labels of `{option}` sub-macros in a macro body. */
+  extractOptions: (children: ASTNode[]) => string[];
+  /** Wrap content in a `<span>` carrying the macro's class/id, or a fragment if it has neither. */
+  wrap: (content: ComponentChildren) => VNode<any>;
   useAction: (opts: UseActionOptions) => string;
-  h: (type: any, props: any, ...children: any[]) => any;
+  /** Preact's `h` (createElement). */
+  h: typeof h;
+  /** Render AST nodes as block content (markdown, `<p>` wrapping unless nobr). */
   renderNodes: (
-    nodes: any[],
-    options?: { nobr?: boolean; locals?: Record<string, unknown> },
-  ) => any;
-  renderInlineNodes: (nodes: any[]) => any;
+    nodes: ASTNode[],
+    options?: {
+      nobr?: boolean;
+      locals?: Record<string, unknown>;
+      inline?: boolean;
+    },
+  ) => ComponentChildren;
+  /** Render AST nodes as inline content (no markdown block processing). */
+  renderInlineNodes: (nodes: ASTNode[]) => ComponentChildren;
+  /** Preact hooks, shared with Spindle's own Preact instance. */
   hooks: {
-    useState: any;
-    useRef: any;
-    useEffect: any;
-    useLayoutEffect: any;
-    useCallback: any;
-    useMemo: any;
-    useContext: any;
+    useState: typeof useState;
+    useRef: typeof useRef;
+    useEffect: typeof useEffect;
+    useLayoutEffect: typeof useLayoutEffect;
+    useCallback: typeof useCallback;
+    useMemo: typeof useMemo;
+    useContext: typeof useContext;
   };
 }
 
@@ -330,14 +411,21 @@ export interface MacroContext {
  */
 export interface MacroDefinition {
   name: string;
+  /** Sub-macro names (e.g. `['option']`); a non-empty list makes the macro a block macro. */
   subMacros?: string[];
+  /** Accept a `{name}...{/name}` body. Inferred from `subMacros` when omitted. */
   block?: boolean;
+  /** Resolve `{$var}` interpolation in the macro's class/id (`ctx.resolve`). */
   interpolate?: boolean;
+  /** Provide `ctx.merged` and `ctx.evaluate` (variables, temporaries, locals, transients). */
   merged?: boolean;
+  /** Bind the first argument as a story variable (`ctx.varName`, `ctx.value`, `ctx.setValue`). */
   storeVar?: boolean;
+  /** Tooling hint: one-line description shown by editors. */
   description?: string;
+  /** Tooling hint: positional parameters. */
   parameters?: ParameterDef[];
-  render: (props: MacroProps, ctx: MacroContext) => any;
+  render: (props: MacroProps, ctx: MacroContext) => ComponentChildren;
 }
 
 /**