@rohal12/spindle 0.52.9 → 0.54.0

package/src/utils/value-kinds.ts

@@ -0,0 +1,45 @@
+// Kinds of story values that structural operations (clone, equality, merge)
+// and property paths treat as a whole, by their content.
+
+export const toStringTag = (value: object): string =>
+  Object.prototype.toString.call(value).slice(8, -1);
+
+/** Temporal values are immutable: copies may share them. */
+export const isTemporal = (value: object): boolean =>
+  toStringTag(value).startsWith('Temporal.');
+
+/** new Number(), new String(), new Boolean(), Object(1n). */
+export const isBoxed = (value: object): boolean =>
+  value instanceof Number ||
+  value instanceof String ||
+  value instanceof Boolean ||
+  toStringTag(value) === 'BigInt';
+
+/**
+ * Values compared and copied as a whole, by their content: they have no
+ * own keys to merge by, or their keys are not the data (a property written
+ * into one would be dropped by clones and saves, and by Immer for Map and
+ * Set).
+ */
+export function isAtomic(value: object): boolean {
+  return (
+    value instanceof Date ||
+    value instanceof RegExp ||
+    value instanceof Map ||
+    value instanceof Set ||
+    ArrayBuffer.isView(value) ||
+    value instanceof ArrayBuffer ||
+    value instanceof URL ||
+    value instanceof URLSearchParams ||
+    value instanceof Error ||
+    isBoxed(value) ||
+    isTemporal(value)
+  );
+}
+
+/** "a Map", "an Error", ... for an atomic value (see isAtomic), else undefined. */
+export function atomicName(value: object): string | undefined {
+  if (!isAtomic(value)) return undefined;
+  const tag = value instanceof Error ? 'Error' : toStringTag(value);
+  return `${/^[AEIOU]/.test(tag) ? 'an' : 'a'} ${tag}`;
+}

package/src/widgets/widget-def.ts

@@ -0,0 +1,60 @@
+/**
+ * Reading widget definitions without rendering anything: the `{widget}`
+ * macro, startup and markup validation (also in tooling) share these.
+ */
+import { parseMacroArgs } from '../components/macros/macro-args';
+import type { MacroArgs } from '../registry';
+
+/** A {widget} definition's name, then its `@` parameters. */
+export const WIDGET_PARAMETERS = [
+  { name: 'name', type: 'text', required: true },
+  { name: 'parameters', type: 'expression' },
+] as const;
+
+export interface WidgetDef {
+  name: string;
+  params: string[];
+}
+
+/**
+ * The widget a {widget} definition's arguments declare: its name and its
+ * parameters, the words after it that start with `@` (docs/widgets.md).
+ * Other words, such as `$name`, are not parameters.
+ */
+export function widgetDef({
+  name = '',
+  parameters = '',
+}: MacroArgs<typeof WIDGET_PARAMETERS>): WidgetDef {
+  return {
+    name,
+    params: parameters.split(/\s+/).filter((word) => word.startsWith('@')),
+  };
+}
+
+/** Read the arguments of a {widget} definition (see widgetDef). */
+export function parseWidgetDef(rawArgs: string): WidgetDef {
+  return widgetDef(parseMacroArgs(rawArgs, WIDGET_PARAMETERS));
+}
+
+const BLOCK_WIDGET = /\{widget\s+["']?(\w+)["']?[^}]*\}([\s\S]*?)\{\/widget\}/g;
+
+/**
+ * The names of the block widgets (those whose body renders `{@children}`)
+ * that StoryInit and the passages tagged `widget` define. They must be
+ * known as block macros before any passage is parsed, so that passages
+ * invoking them nest their content whatever the passage order.
+ */
+export function blockWidgetNames(
+  passages: Iterable<{ name: string; tags?: string[]; content: string }>,
+): string[] {
+  const names: string[] = [];
+  for (const passage of passages) {
+    if (passage.name !== 'StoryInit' && !passage.tags?.includes('widget')) {
+      continue;
+    }
+    for (const match of passage.content.matchAll(BLOCK_WIDGET)) {
+      if (/\{@children\}/.test(match[2]!)) names.push(match[1]!);
+    }
+  }
+  return names;
+}

package/types/index.d.ts

@@ -575,7 +575,18 @@ export interface SaveMeta {
  */
 export interface SaveRecord {
   meta: SaveMeta;
-  payload: SavePayload;
+  /** The payload as stored: serialized in one piece, with its format version. */
+  payload: EncodedPayload;
+}
+
+/**
+ * A save payload as stored. `data` is opaque serialized text; read it with
+ * the Story API (loading a save), not directly.
+ */
+export interface EncodedPayload {
+  /** The save format version `data` was written in. */
+  formatVersion: number;
+  data: string;
 }
 
 /**
@@ -584,7 +595,8 @@ export interface SaveRecord {
  * @see {@link ../../src/saves/types.ts} for the implementation.
  */
 export interface SaveExport {
-  version: 1;
+  /** The save format version of the export. */
+  formatVersion: number;
   /** IFID of the story the save belongs to. Imports into other stories are rejected. */
   ifid: string;
   /** ISO 8601 timestamp of the export. */
@@ -614,13 +626,18 @@ export interface StoryAPI {
   set(name: string, value: unknown): void;
   set(vars: Record<string, unknown>): void;
 
-  /** Navigate to a passage by name. */
+  /**
+   * Navigate to a passage by name. Writes the session: if the variables hold
+   * a value a save cannot hold (a function, an instance of an unregistered
+   * class, a unique symbol), the navigation completes and then throws an
+   * error naming the variable.
+   */
   goto(passageName: string): void;
 
-  /** Go back one step in history. */
+  /** Go back one step in history. Throws like `goto()`. */
   back(): void;
 
-  /** Go forward one step in history. */
+  /** Go forward one step in history. Throws like `goto()`. */
   forward(): void;
 
   /** Restart the story from the beginning. */
@@ -629,7 +646,9 @@ export interface StoryAPI {
   /**
    * Save the current state. Pass `slot` for a named save, `custom` for metadata.
    * Resolves once the save is persisted (after `aftersave` handlers ran and
-   * `hasSave(slot)` is true); rejects if persisting fails.
+   * `hasSave(slot)` is true); rejects if persisting fails, or if the state
+   * holds a value a save cannot hold (a function, an instance of an
+   * unregistered class, a unique symbol, a symbol key), naming it.
    */
   save(slot?: string, custom?: Record<string, unknown>): Promise<void>;
 
@@ -638,7 +657,8 @@ export interface StoryAPI {
    * 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.
+   * if loading fails, e.g. for a save holding an instance of a class that is
+   * not registered, or one from an incompatible save format version.
    */
   load(slot?: string): Promise<void>;
 
@@ -744,7 +764,11 @@ export interface StoryAPI {
   /** Check whether any dialog is currently open. */
   isDialogOpen(): boolean;
 
-  /** Register a class constructor for use in story expressions. */
+  /**
+   * Register a class so its instances keep their class through clones,
+   * history, saves and loads. A save refuses instances of classes that are
+   * not registered.
+   */
   registerClass(name: string, ctor: new (...args: any[]) => any): void;
 
   /** Register a custom macro. */

package/types/tooling.d.ts

@@ -99,3 +99,45 @@ export declare function parseStoryVariables(
   content: string,
   sigil?: '$' | '%',
 ): Map<string, VariableSchema>;
+
+/** A passage to validate. */
+export interface MarkupPassage {
+  name: string;
+  content: string;
+  tags?: string[];
+  /**
+   * Passage attributes; `data-source-file` and `data-source-line` (the
+   * line of its `::` header) place errors in the source file.
+   */
+  metadata?: Record<string, string>;
+}
+
+/** An error in a passage's markup. */
+export interface MarkupDiagnostic {
+  passage: string;
+  /** 1-based line within the passage's content. */
+  line: number;
+  /** 1-based column (UTF-16 code units). */
+  column: number;
+  message: string;
+  /** The source file and line, when the passage says where it came from. */
+  file?: string;
+  fileLine?: number;
+}
+
+/**
+ * Validate the markup of a story's passages as Spindle does when the story
+ * starts: malformed markup (unclosed or mismatched macros, tags, links,
+ * braces and attribute values) and unknown macros, checked against the
+ * built-in macros, those registered with `defineMacro` and the widgets the
+ * passages define. Spindle refuses to start a story with any of these.
+ */
+export declare function validateMarkup(
+  passages: Iterable<MarkupPassage>,
+): MarkupDiagnostic[];
+
+/**
+ * A diagnostic as one line of text, as Spindle shows it:
+ * `Passage "Start", line 3, column 5 (story.twee:12): Unclosed {if}: …`.
+ */
+export declare function formatDiagnostic(diagnostic: MarkupDiagnostic): string;