@rohal12/spindle 0.51.4 → 0.52.1

package/src/utils/live-locals.ts

@@ -1,3 +1,5 @@
+import { createNamespace, ownValue } from './namespace';
+
 /**
  * Read-only view of a locals scope that always reflects its current values.
  *
@@ -9,9 +11,14 @@
 export function liveLocalsView(
   getValues: () => Record<string, unknown>,
 ): Record<string, unknown> {
-  return new Proxy({} as Record<string, unknown>, {
-    get: (_, key) => (typeof key === 'string' ? getValues()[key] : undefined),
-    has: (_, key) => key in getValues(),
+  // No prototype and own entries only, like every namespace (see
+  // utils/namespace.ts)
+  return new Proxy(createNamespace(), {
+    get: (_, key) =>
+      typeof key === 'string' ? ownValue(getValues(), key) : undefined,
+    has: (_, key) =>
+      typeof key === 'string' &&
+      Object.prototype.hasOwnProperty.call(getValues(), key),
     ownKeys: () => Reflect.ownKeys(getValues()),
     getOwnPropertyDescriptor: (_, key) => {
       const desc = Object.getOwnPropertyDescriptor(getValues(), key);

package/src/utils/namespace.ts

@@ -0,0 +1,71 @@
+/**
+ * Variable namespaces: the records holding $story variables, _temporary
+ * variables, %transient variables and @locals, keyed by variable name.
+ *
+ * They have no prototype, so every name is plain storage: a variable may be
+ * called `constructor`, `toString` or `hasOwnProperty`, and reading one
+ * that was never set gives undefined rather than an Object.prototype
+ * member. The one name they cannot hold is `__proto__`: story state (and so
+ * saves) never holds a property by that name, and on an ordinary object
+ * writing it would replace the prototype instead of storing a value. It is
+ * refused wherever a variable name enters (checkVariableName).
+ */
+
+export type Namespace = Record<string, unknown>;
+
+/** The variable name no namespace can hold. */
+export const RESERVED_NAME = '__proto__';
+
+/**
+ * Throw a TypeError if `name` (without its sigil) cannot be a variable
+ * name. `label` is the name as the author wrote it (e.g. `$__proto__`).
+ */
+export function checkVariableName(name: string, label = name): void {
+  if (name === RESERVED_NAME) {
+    throw new TypeError(
+      `spindle: "${label}" cannot be used as a variable name (${RESERVED_NAME} is reserved)`,
+    );
+  }
+}
+
+/** A namespace with no prototype holding the own entries of `sources`. */
+export function createNamespace(
+  ...sources: readonly (object | null | undefined)[]
+): Namespace {
+  const ns = Object.create(null) as Namespace;
+  for (const source of sources) {
+    if (!source) continue;
+    for (const key of Object.keys(source)) {
+      ns[key] = (source as Namespace)[key];
+    }
+  }
+  return ns;
+}
+
+/** Whether `value` is an object with no prototype. */
+export const isNamespace = (value: object): boolean =>
+  Object.getPrototypeOf(value) === null;
+
+/** `ns` itself if it has no prototype, else a namespace copy of it. */
+export const asNamespace = (ns: Namespace): Namespace =>
+  isNamespace(ns) ? ns : createNamespace(ns);
+
+/** A namespace copy of `ns` with `key` set to `value`. */
+export function withEntry(
+  ns: Namespace,
+  key: string,
+  value: unknown,
+): Namespace {
+  const next = createNamespace(ns);
+  next[key] = value;
+  return next;
+}
+
+/** An empty namespace that cannot change. */
+export const EMPTY_NAMESPACE: Namespace = Object.freeze(createNamespace());
+
+/** `ns[key]` if `ns` holds it as an own property, else undefined. */
+export const ownValue = (ns: object, key: string): unknown =>
+  Object.prototype.hasOwnProperty.call(ns, key)
+    ? (ns as Namespace)[key]
+    : undefined;

package/src/utils/object-path.ts

@@ -1,6 +1,15 @@
 import { isDraft } from 'immer';
 
-/** Traverse dot-path segments on an object and return the nested value. */
+const hasOwn = (obj: object, key: string): boolean =>
+  Object.prototype.hasOwnProperty.call(obj, key);
+
+/**
+ * Traverse dot-path segments on an object and return the nested value.
+ * Members of Object.prototype (`constructor`, `toString`, `__proto__`, ...)
+ * are not story state: unless an object holds one as its own property, it
+ * reads as missing, as setByPath() treats it. Other inherited properties
+ * (class getters, `size` of a Map) are read.
+ */
 export function getByPath(
   obj: Record<string, unknown>,
   segments: readonly string[],
@@ -8,23 +17,50 @@ export function getByPath(
   let current: unknown = obj;
   for (const seg of segments) {
     if (current == null || typeof current !== 'object') return undefined;
+    if (seg in Object.prototype && !hasOwn(current, seg)) return undefined;
     current = (current as Record<string, unknown>)[seg];
   }
   return current;
 }
 
+/** Array indices ("0", "1", …) and "length": the keys an array holds. */
+const isArrayKey = (key: string): boolean =>
+  key === 'length' || /^(0|[1-9]\d*)$/.test(key);
+
+/**
+ * Built-ins whose content is not their properties: a property written into
+ * one would be dropped by clones and saves (and by Immer, for Map and Set).
+ */
+const builtinName = (value: object): string | undefined =>
+  value instanceof Map
+    ? 'a Map'
+    : value instanceof Set
+      ? 'a Set'
+      : value instanceof Date
+        ? 'a Date'
+        : value instanceof RegExp
+          ? 'a RegExp'
+          : undefined;
+
 /**
  * Shallow copy that keeps the prototype, so a registered class instance
  * stays an instance of its class (with the same own keys deepClone copies).
  */
 function shallowCopy(value: object): Record<string, unknown> {
-  let copy: object;
-  if (Array.isArray(value)) copy = [];
-  else if (value instanceof Map) copy = new Map(value);
-  else if (value instanceof Set) copy = new Set(value);
-  else if (value instanceof Date) copy = new Date(value.getTime());
-  else copy = Object.create(Object.getPrototypeOf(value)) as object;
-  return Object.assign(copy, value) as Record<string, unknown>;
+  const copy = Array.isArray(value)
+    ? []
+    : (Object.create(Object.getPrototypeOf(value) as object | null) as object);
+  // Define rather than assign (Object.assign), so that a "__proto__" key
+  // stays a key instead of replacing the copy's prototype
+  for (const key of Object.keys(value)) {
+    Object.defineProperty(copy, key, {
+      value: (value as Record<string, unknown>)[key],
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    });
+  }
+  return copy as Record<string, unknown>;
 }
 
 export interface SetByPathOptions {
@@ -45,6 +81,12 @@ export interface SetByPathOptions {
  * instance shared with the previous state and with history, and subscribers
  * would see no change. Outside a draft (a private working copy) the path is
  * written in place.
+ *
+ * The path goes through own properties of plain objects, class instances
+ * and arrays (by index); anything else throws a TypeError rather than
+ * writing where no clone or save would see it: an inherited property such
+ * as a method counts as missing, and Map, Set, Date and RegExp values and
+ * other keys of arrays are refused, as is a "__proto__" segment.
  */
 export function setByPath(
   root: Record<string, unknown>,
@@ -59,22 +101,56 @@ export function setByPath(
 /**
  * Delete the property at dot-path `segments` below `root`, copying
  * undrafted objects on the way down like setByPath(). Does nothing when an
- * intermediate is missing or not an object, or the property is absent.
+ * intermediate is missing or not an object, or the property is absent (or
+ * only inherited).
  */
 export function deleteByPath(
   root: Record<string, unknown>,
   segments: readonly string[],
 ): void {
   const last = segments[segments.length - 1]!;
-  // Check first, so a no-op delete copies nothing.
-  const holder = getByPath(root, segments.slice(0, -1));
-  if (holder == null || typeof holder !== 'object' || !(last in holder)) {
+  checkSegments(segments);
+  // Check first, so a no-op delete copies nothing
+  let holder: unknown = root;
+  for (const seg of segments.slice(0, -1)) {
+    if (holder == null || typeof holder !== 'object' || !hasOwn(holder, seg)) {
+      return;
+    }
+    holder = (holder as Record<string, unknown>)[seg];
+  }
+  if (holder == null || typeof holder !== 'object' || !hasOwn(holder, last)) {
     return;
   }
   const parent = walkToParent(root, segments, false);
   delete parent[last];
 }
 
+/** Refuse a segment that would reach a prototype instead of story state. */
+function checkSegments(segments: readonly string[]): void {
+  if (segments.includes('__proto__')) {
+    throw new TypeError(
+      `spindle: Cannot use "__proto__" in a variable path ("${segments.join('.')}")`,
+    );
+  }
+}
+
+/** Throw unless `holder` can take `key` as story state (see setByPath). */
+function checkHolder(
+  holder: object,
+  key: string,
+  segments: readonly string[],
+  depth: number,
+): void {
+  const builtin = builtinName(holder);
+  const kind =
+    builtin ?? (Array.isArray(holder) && !isArrayKey(key) ? 'an array' : '');
+  if (kind) {
+    throw new TypeError(
+      `spindle: Cannot set property "${key}" on ${kind} (at "${segments.slice(0, depth).join('.')}")`,
+    );
+  }
+}
+
 /**
  * Walk to the object holding the last of `segments`, copying undrafted
  * objects when `root` is an Immer draft (see setByPath). A missing or
@@ -86,11 +162,14 @@ function walkToParent(
   segments: readonly string[],
   createMissing: boolean,
 ): Record<string, unknown> {
+  checkSegments(segments);
   const copyOnWrite = isDraft(root);
   let current: Record<string, unknown> = root;
   for (let i = 0; i < segments.length - 1; i++) {
     const seg = segments[i]!;
-    let next = current[seg];
+    checkHolder(current, seg, segments, i);
+    // An inherited property (a method, "constructor") counts as missing
+    let next = hasOwn(current, seg) ? current[seg] : undefined;
     if (next == null || typeof next !== 'object') {
       if (!createMissing) {
         throw new TypeError(
@@ -99,11 +178,17 @@ function walkToParent(
       }
       next = {};
       current[seg] = next;
-    } else if (copyOnWrite && !isDraft(next)) {
+    } else if (copyOnWrite && !isDraft(next) && !builtinName(next)) {
       next = shallowCopy(next);
       current[seg] = next;
     }
     current = next as Record<string, unknown>;
   }
+  checkHolder(
+    current,
+    segments[segments.length - 1]!,
+    segments,
+    segments.length - 1,
+  );
   return current;
 }

package/src/utils/stable-key.ts

@@ -1,6 +1,4 @@
-import { getClassName } from '../class-registry';
-
-type Constructor = new (...args: any[]) => any;
+import { registeredClassName } from '../class-registry';
 
 /**
  * Content-derived string key for a value, used to remount components when
@@ -10,9 +8,10 @@ type Constructor = new (...args: any[]) => any;
  * plain objects of those) produce exactly their `JSON.stringify` output. Other
  * values get distinct, unambiguous markers so their contents are reflected
  * too: Map and Set entries (nested at any depth), Date, RegExp, BigInt,
- * undefined, NaN/±Infinity, symbols, functions and registered class
- * instances. Cyclic references become a back-reference marker instead of
- * throwing, and the function never throws.
+ * undefined, NaN/±Infinity, symbols (by description), functions (by name)
+ * and registered class instances. A hole in an array reads as undefined.
+ * Cyclic references become a back-reference marker instead of throwing,
+ * and the function never throws.
  */
 export function stableKey(value: unknown): string {
   try {
@@ -35,7 +34,11 @@ function keyOf(val: unknown, ancestors: object[]): string {
     case 'undefined':
       return 'undefined';
     case 'symbol':
-      return val.toString();
+      // Quote the description: `Symbol('a),Symbol(b')` must not read like
+      // two symbols.
+      return val.description === undefined
+        ? 'Symbol()'
+        : `Symbol(${JSON.stringify(val.description)})`;
     case 'function':
       return `<function ${JSON.stringify(val.name)}>`;
   }
@@ -51,7 +54,9 @@ function keyOf(val: unknown, ancestors: object[]): string {
   ancestors.push(obj);
   try {
     if (Array.isArray(val)) {
-      return `[${val.map((v) => keyOf(v, ancestors)).join(',')}]`;
+      // Array.from reads a hole as undefined (map would skip it, giving
+      // `[,]` the key of `[]`), matching deepClone, which fills holes.
+      return `[${Array.from(val, (v) => keyOf(v, ancestors)).join(',')}]`;
     }
     if (val instanceof Map) {
       const entries = [...val].map(
@@ -67,7 +72,7 @@ function keyOf(val: unknown, ancestors: object[]): string {
     const body = Object.keys(record)
       .map((k) => `${JSON.stringify(k)}:${keyOf(record[k], ancestors)}`)
       .join(',');
-    const className = getClassName(obj.constructor as Constructor);
+    const className = registeredClassName(obj);
     return className === undefined
       ? `{${body}}`
       : `Class(${JSON.stringify(className)}){${body}}`;

package/src/widgets/widget-registry.ts

@@ -1,4 +1,5 @@
 import type { ASTNode } from '../markup/ast';
+import { checkVariableName } from '../utils/namespace';
 
 interface WidgetEntry {
   body: ASTNode[];
@@ -8,6 +9,11 @@ interface WidgetEntry {
 
 const widgets = new Map<string, WidgetEntry>();
 
+/**
+ * Register a widget. Its `@` parameters become locals of its body, so one
+ * that no namespace can hold (`@__proto__`) throws a TypeError and the
+ * widget is not registered.
+ */
 export function registerWidget(
   name: string,
   bodyAST: ASTNode[],
@@ -15,6 +21,9 @@ export function registerWidget(
   isBlock = false,
 ): void {
   const filteredParams = params.filter((p) => p !== '@children');
+  for (const param of filteredParams) {
+    if (param.startsWith('@')) checkVariableName(param.slice(1), param);
+  }
   widgets.set(name.toLowerCase(), {
     body: bodyAST,
     params: filteredParams,

package/types/index.d.ts

@@ -401,6 +401,8 @@ export interface MacroContext {
       nobr?: boolean;
       locals?: Record<string, unknown>;
       inline?: boolean;
+      /** Literal content, as inside `<pre>`: no markdown processing. */
+      raw?: boolean;
     },
   ) => ComponentChildren;
   /** Render AST nodes as inline content (no markdown block processing). */
@@ -417,6 +419,20 @@ export interface MacroContext {
   };
 }
 
+/**
+ * Context object passed to a macro's text form (`MacroDefinition.text`).
+ * @see {@link ../../src/registry.ts} for the implementation.
+ */
+export interface MacroTextContext {
+  /** Evaluate an expression in the current scope. */
+  evaluate: (expr: string) => unknown;
+  /**
+   * The text of AST nodes (a body or branch) in the current scope, with
+   * `locals` (keys without `@`) added on top of the current locals.
+   */
+  renderText: (nodes: ASTNode[], locals?: Record<string, unknown>) => string;
+}
+
 /**
  * Configuration object for `Story.defineMacro()`.
  * @see {@link ../../src/define-macro.ts} for the implementation.
@@ -427,7 +443,7 @@ export interface MacroDefinition {
   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`). */
+  /** Resolve markup (`{$var}`, expressions, macros) in the macro's class/id, and provide `ctx.resolve`. */
   interpolate?: boolean;
   /** Provide `ctx.merged` and `ctx.evaluate` (variables, temporaries, locals, transients). */
   merged?: boolean;
@@ -438,6 +454,12 @@ export interface MacroDefinition {
   /** Tooling hint: positional parameters. */
   parameters?: ParameterDef[];
   render: (props: MacroProps, ctx: MacroContext) => ComponentChildren;
+  /**
+   * The macro's text form, used where markup becomes a string: HTML
+   * attribute values, image alt text and link titles, macro labels. Without
+   * one, the macro can't be used there and is reported as an error.
+   */
+  text?: (props: MacroProps, ctx: MacroTextContext) => string;
 }
 
 /**
@@ -549,8 +571,11 @@ export interface StoryAPI {
   save(slot?: string, custom?: Record<string, unknown>): Promise<void>;
 
   /**
-   * Load a saved state (quick load). Resolves once the loaded state is applied
-   * (immediately if the slot is empty); rejects if loading fails.
+   * Load a saved state (quick load). The game moves to the loaded save's
+   * playthrough, in call order: a save issued after the load belongs to it.
+   * Resolves once the loaded state is applied (immediately if the slot is
+   * empty, without loading if a restart was issued after the load); rejects
+   * if loading fails.
    */
   load(slot?: string): Promise<void>;
 
@@ -671,11 +696,19 @@ export interface StoryAPI {
     getInfo(): Promise<StorageInfo>;
     /** Get browser storage quota estimate. */
     getQuota(): Promise<StorageQuota>;
-    /** Delete all saves for the current game. */
+    /**
+     * Delete all saves and playthroughs of the current game and restart it.
+     * The restart happens at once; the promise settles once the data is
+     * deleted.
+     */
     clearGameData(): Promise<void>;
-    /** Delete all Spindle data across all games. */
+    /** Delete all Spindle data across all games and restart, as clearGameData. */
     clearAllData(): Promise<void>;
-    /** Delete a specific playthrough and its saves. */
+    /**
+     * Delete a specific playthrough and its saves. Deleting the current
+     * playthrough (the one the game started, restarted or last loaded a save
+     * in) moves the running game to a new one.
+     */
     deletePlaythrough(playthroughId: string): Promise<void>;
     /** The active storage backend. */
     readonly backend: 'indexeddb' | 'localstorage' | 'memory';
@@ -731,7 +764,10 @@ export interface StoryAPI {
 
   /** Story configuration. */
   readonly config: {
-    /** Maximum number of history moments to retain. */
+    /**
+     * Maximum number of history moments to retain. Lowering it trims history
+     * at once, keeping the newest moments that include the current one.
+     */
     maxHistory: number;
     /**
      * Key that triggers a quick save (`KeyboardEvent.key`, default `'F6'`).

package/types/tooling.d.ts

@@ -26,6 +26,7 @@ export interface MacroDefinition {
   description?: string;
   parameters?: ParameterDef[];
   render: (...args: any[]) => any;
+  text?: (...args: any[]) => string;
 }
 
 /**