@elvishscout/mdstory 0.1.4 → 0.2.0

package/README.md

@@ -1,438 +1,323 @@
-# MdStory
-
-An interactive fiction scripting format based on Markdown and Handlebars.
-
-Online demo: <https://mdstory.elvish.cc>
-
-## Features
-
-- Seamless integration of Markdown, Handlebars and JavaScript.
-- Ease-to-use API, for both Web and command line applications.
-
-## File Format
-
-### Metadata
-
-The story file header may include YAML-formatted [Metadata](#type-metadata). Metadata defines the basic information and global configuration of the story.
-
-### Chapters
-
-Story files are divided into chapters by level-one headings. The `id` attribute of the heading serves as the unique identifier (`id`) for the chapter. If omitted, the heading content is used as the chapter `id` instead.
-
-Handlebars template language is supported in the chapter content. During rendering, properties in `globals` and `assets` are added to the context for direct access by the template.
-
-### Helpers
-
-MdStory includes built-in Handlebars helpers for creating interactive components or various functionalities:
-
-#### `{{input type name=default}}`
-
-Creates an input of type `type` and assigns the input value (by default `default`) to a global variable named `name`. Supported input types include: `string`, `number`, `boolean`, and `object` (represented as a JSON string).
-
-In HTML rendering mode, it generates a corresponding `<input>` element.
-
-#### `{{set name=value}}`
-
-Assigns the value `value` to a global variable named `name`.
-
-#### `{{#nav target}}`
-
-Creates an entry to navigate to another chapter identified by `target`.
-
-In HTML rendering mode, it generates a corresponding `<button type="submit">` element.
-
-#### `{{linebreak [n]}}`
-
-Inserts `n` blank lines, where `n` defaults to `1`.
-
-#### `{{asset name}}`
-
-Retrieves the URL of a resource file named `name`. Basically it works the same as `{{name}}` except that it supports resource names with special characters.
-
-#### `{{mime name}}`
-
-Retrieves the MIME type of a resource file named `name`.
-
-### JavaScript Integration
-
-JavaScript may be included into the story source using the `<script>` tag. Scripts before any level-one headings are considered global scripts, while those within chapters are considered chapter scripts. Only one `<script>` tag is allowed at the beginning of the story and in each chapter.
-
-Scripts are evaluated during runtime using the `Function()` constructor, therefore you may use top-level `return` statements to return objects of type [StoryHooks](#type-storyhooks) or [ChapterHooks](#type-chapterhooks).
-
-### Stylesheets
-
-CSS stylesheets may be included using the `<style>` tag, which are extracted and gathered into the `stylesheet` property of [StoryBody](#type-storybody) during parsing.
-
-## Examples
-
-Here are some [examples](./examples/) of story files.
-
-## API
-
-### `type Value`
-
-```typescript
-type JsonPrimitive = number | string | boolean | null;
-type JsonArray = JsonValue[];
-type JsonObject = { [key: string]: JsonValue };
-type JsonValue = JsonPrimitive | JsonArray | JsonObject;
-type Value = JsonValue;
-```
-
-The type of variables in MdStory, basically all types allowed in JSON, including primitive values (`string`, `number`, `boolean`, `null`) and nested `array`s and `object`s. Functions and `undefined` are not supported.
-
-### `type ValueType`
-
-```typescript
-type ValueType = "string" | "number" | "boolean" | "object";
-```
-
-The type indicator for input fields.
-
-### `type Scope`
-
-```typescript
-type Scope = JsonObject;
-```
-
-An object of variable values by their names, used to store global variables or input fields.
-
-### `type Asset`
-
-```typescript
-type Asset = { url: string; mime?: string };
-```
-
-A referenceable resource file.
-
-#### Properties
-
-- `url`: The URL of the resource.
-- `mime (optional)`: The MIME type of the resource.
-
-### `type Metadata`
-
-```typescript
-type Metadata = {
-  title?: string;
-  author?: string;
-  email?: string;
-  assets?: Record<string, Asset>;
-};
-```
-
-The Metadata of the story.
-
-#### Properties
-
-- `title (optional)`: The story title.
-- `author (optional)`: The author's name.
-- `email (optional)`: The author's email address.
-- `globals (optional)`: A [Scope](#type-scope) containing initial values of global variables.
-- `assets (optional)`: An object of all [Asset](#type-asset) objects used in the story by their names.
-
-### `type ChapterBody`
-
-```typescript
-type ChapterBody = {
-  title: string;
-  template: string;
-  script: string;
-};
-```
-
-The structured representation of chapter content.
-
-#### Properties
-
-- `title`: The chapter title.
-- `template`: The Handlebars template for rendering.
-- `script`: The JavaScript script for the chapter.
-
-### `type StoryBody`
-
-```typescript
-type StoryBody = {
-  metadata: Metadata;
-  chapters: Record<string, ChapterBody>;
-  entry: string | null;
-  script: string;
-  stylesheet: string;
-};
-```
-
-The structured representation of story content.
-
-#### Properties
-
-- `metadata`: The story [Metadata](#type-metadata).
-- `chapters`: An object of [ChapterBody](#type-chapterbody) objects by their `id`s.
-- `entry`: The `id` of the entry chapter of the story, which may be `null`.
-- `script`: The global JavaScript script of the story.
-- `stylesheet`: The global stylesheet of the story.
-
-### `type StoryHooks`
-
-```typescript
-type StoryHooks = {
-  onStart?: (globals: Scope) => Scope | void;
-};
-```
-
-Defines the global lifecycle hooks of the story.
-
-#### Methods
-
-- `onStart (optional)`: Called when the story starts.
-  - Parameters:
-    - `globals`: A [Scope](#type-scope) of initial global variables.
-  - Return value:
-    - Updated [Scope](#type-scope) of global variables or `void`.
-
-### `type ChapterHooks`
-
-```typescript
-type ChapterHooks = {
-  onEnter?: (globals: Scope) => Scope | void;
-  onLeave?: (globals: Scope, fields: Scope) => Scope | void;
-  onNavigate?: (target: string | null, globals: Scope, fields: Scope) => string | null;
-};
-```
-
-Defines the lifecycle hooks of a chapter.
-
-#### Methods
-
-- `onEnter (optional)`: Called when entering a chapter.
-  - Parameters:
-    - `globals`: A [Scope](#type-scope) of current global variables.
-  - Return value:
-    - Updated [Scope](#type-scope) of global variables or `void`. Such update only applies to the current lifecycle of the chapter.
-- `onLeave (optional)`: Called when leaving a chapter.
-  - Parameters:
-    - `globals`: A [Scope](#type-scope) of current global variables.
-    - `fields`: A [Scope](#type-scope) of input fields from current chapter.
-  - Return value:
-    - Updated [Scope](#type-scope) of global variables or `void`.
-- `onNavigate (optional)`: Called during chapter navigation.
-  - Parameters:
-    - `target` : `id` of the target chapter.
-    - `globals`: A [Scope](#type-scope) of current global variables.
-    - `fields`: A [Scope](#type-scope) of input fields from current chapter.
-  - Return value:
-    - Updated `target` or `void`.
-
-### `type Renderer`
-
-```typescript
-type Renderer = {
-  input?: (options: { name: string; type: ValueType; value: Value }) => string;
-  nav?: (options: { target: string; children: string }) => string;
-};
-```
-
-Defines the renderer interface for generating outputs in different formats.
-
-#### Methods
-
-- `input (optional)`: Generates the rendering result of an input field.
-  - Parameters:
-    - `name`: The name of the variable.
-    - `type`: The [ValueType](#type-valuetype) of the variable.
-    - `value`: The default [Value](#type-value) of the variable.
-  - Return value:
-    - The rendered input field.
-
-- `nav (optional)`: Generates the rendering result of chapter navigation.
-  - Parameters:
-    - `target`: The `id` of the target chapter.
-    - `children`: The text content of the navigation button.
-  - Return value:
-    - The rendered navigation button.
-
-### `type RenderOptions`
-
-```typescript
-type RenderOptions = {
-  format: "markdown" | "html" | Renderer;
-  html?: boolean;
-};
-```
-
-Defines rendering options.
-
-#### Properties
-
-- `format`: The rendering format, which may be `"markdown"`, `"html"`, or a custom [Renderer](#type-renderer).
-- `html (optional)`: Whether to parse Markdown into HTML, defaults to `false`.
-
-### `type RenderResult`
-
-```typescript
-type RenderResult = {
-  text: string;
-  inputs: { name: string; type: ValueType; value: Value }[];
-  navs: { text: string; target: string | null }[];
-};
-```
-
-The rendering result, containing the rendered text and extracted fields.
-
-#### Properties
-
-- `text`: The rendered text content.
-- `inputs`: An array of input fields, each containing:
-  - `name`: The name of the variable.
-  - `type`: The [ValueType](#type-valuetype) of the variable.
-  - `value`: The default [Value](#type-value) of the variable.
-- `navs`: An array of navigation fields, each containing:
-  - `text`: The text content of the navigation button.
-  - `target`: The `id` of the target chapter.
-
-### `type ChapterOptions`
-
-```typescript
-type ChapterOptions = {
-  id: string;
-  title: string;
-  template: string;
-  hooks: ChapterHooks;
-};
-```
-
-Defines the initialization options of a chapter.
-
-#### Properties
-
-- `id`: The unique identifier of the chapter.
-- `title`: The title of the chapter.
-- `template`: The Handlebars template for rendering.
-- `hooks`: An object of type [ChapterHooks](#type-chapterhooks).
-
-### `class Chapter`
-
-```typescript
-class Chapter {
-  id: string;
-  title: string;
-  template: string;
-  hooks: ChapterHooks;
-
-  constructor(options: ChapterOptions);
-  render(scope: Scope, assets: Record<string, Asset>, options: RenderOptions): string;
-}
-```
-
-Defines a chapter.
-
-#### Properties
-
-- `id`: The unique identifier of the chapter.
-- `title`: The title of the chapter.
-- `template`: The Handlebars template for rendering.
-- `hooks`: Chapter hooks of type [ChapterHooks](#type-chapterhooks).
-
-#### Methods
-
-- `constructor`: Initializes the chapter instance.
-  - Parameters:
-    - `options`: An object of type [ChapterOptions](#type-chapteroptions).
-- `render`: Renders the chapter content.
-  - Parameters:
-    - `scope`: An object of type [Scope](#type-scope) for template rendering.
-    - `assets`: An object of [Asset](#type-asset) objects by their names.
-    - `options`: An object of type [RenderOptions](#type-renderoptions).
-  - Return value:
-    - An object of type [RenderResult](#type-renderresult).
-
-### `type StoryPrompt`
-
-```typescript
-type StoryPrompt = (props: { chapter: Chapter } & RenderResult) => Promise<{ target: string | null; updates: Scope } | FormData>;
-```
-
-Defines the prompt function of the story, used to handle user input.
-
-#### Parameters
-
-- `props`: An object containing the current chapter and rendering result.
-  - `chapter`: Current [Chapter](#class-chapter).
-  - `text`: The rendered chapter content.
-  - `inputs`, `navs`: Fields from [RenderResult](#type-renderresult).
-
-#### Return value
-
-- A `Promise` resolving to one of the following forms:
-  - `{ target, updates }`: The `id` of the target chapter and updated [Scope](#type-scope) of global variables.
-  - `FormData`: Contains the form data of user input, typically from a Web app.
-
-### `class StoryBase`
-
-```typescript
-class StoryBase {
-  metadata: Metadata;
-  globals: Scope;
-  chapters: Record<string, Chapter>;
-  entry: Chapter | null;
-  hooks: StoryHooks;
-  stylesheet: string;
-  assets: Record<string, Asset>;
-
-  constructor(storyBody: StoryBody);
-  play(prompt: StoryPrompt, options: RenderOptions): Promise<void>;
-}
-```
-
-Defines the base class of the story, containing the core logic of the story.
-
-#### Properties
-
-- `metadata`: Story [Metadata](#type-metadata).
-- `globals`: A [Scope](#type-scope) of global variables.
-- `chapters`: An object of [Chapter](#class-chapter) objects by their `id`s.
-- `entry`: The entry [Chapter](#class-chapter) of the story.
-- `hooks`: An object of type [StoryHooks](#type-storyhooks).
-- `stylesheet`: The global stylesheet of the story.
-- `assets`: An object of [Asset](#type-asset) objects by their names.
-
-#### Methods
-
-- `constructor`: Initializes the story instance.
-- `play`: Starts playing the story.
-  - Parameters:
-    - `prompt`: A function of type [StoryPrompt](#type-storyprompt).
-    - `options`: An object of type [RenderOptions](#type-renderoptions).
-  - Return value:
-    - A `Promise` resolving to `void`.
-
-### `function parseStorySource`
-
-```typescript
-function parseStorySource(source: string): StoryBody;
-```
-
-Parses the story source in Markdown format.
-
-#### Parameters
-
-- `source`: The story source in Markdown format.
-
-#### Return value
-
-- An object of type [StoryBody](#type-storybody).
-
-### `class Story`
-
-```typescript
-class Story extends StoryBase {
-  constructor(source: string);
-}
-```
-
-Inherits from [StoryBase](#class-storybase), creating a story instance from the story source in Markdown format.
-
-#### Methods
-
-- `constructor`: Initializes the story instance.
-  - Parameters:
-    - `source`: The story source in Markdown format.
+**English** | [中文](README.zh-CN.md) | [Writing Guide](WRITING_GUIDE.zh-CN.md)
+
+# MdStory
+
+An interactive fiction scripting format based on Markdown and Handlebars.
+
+Online demo: <https://mdstory.elvish.cc>
+
+## Quick Start
+
+A MdStory file is a Markdown document with three levels of headings:
+
+```markdown
+---
+title: My Story
+globals:
+  name: Alice
+---
+
+# My Story
+
+<script>
+  export default {
+    globals() {
+      return { gold: 100 };
+    },
+  };
+</script>
+
+## Chapter One {#chap1}
+
+### A Dark Forest {#forest}
+
+You wake up in a dark forest. Your name is {{name}} and you have {{gold}} gold.
+
+{{input "string" $weapon="stick"}}
+
+{{#nav "chap2.cave"}}Walk forward{{/nav}}
+```
+
+### Structure
+
+| Level | Heading     | Purpose                                                          |
+| ----- | ----------- | ---------------------------------------------------------------- |
+| `#`   | Story title | Optional. `<script>` before chapters/scenes exports story hooks. |
+| `##`  | Chapter     | Groups scenes. Has its own hooks and `locals`.                   |
+| `###` | Scene       | Renderable unit with a Handlebars template.                      |
+
+If no `#` heading is present, the story title comes from metadata `title`, or is empty.
+Scenes placed before any `##` are grouped into an implicit default chapter.
+
+Content between the `#` heading and the first `##`/`###` is the **story template** — it is rendered once at the beginning of the story. Content between a `##` heading and its first `###` is the **chapter template** — it is rendered once when entering that chapter. Both support the same Handlebars syntax and helpers as scenes.
+
+```markdown
+# The Dungeon
+
+*You open a dusty tome...*
+
+## Chapter One {#ch1}
+
+*The air grows cold as you descend.*
+
+### The Entrance {#entrance}
+
+You stand before a massive iron door.
+```
+
+### Navigation
+
+Use `{{#nav target}}label{{/nav}}` to let the reader move between scenes:
+
+```markdown
+{{#nav "forest"}} Go back to the forest {{/nav}} ← same chapter
+{{#nav "chap2.cave"}} Enter the cave (other chapter){{/nav}} ← cross-chapter
+{{#nav "chap2"}} Go to chapter 2 {{/nav}} ← chapter entry scene
+{{#nav null}} The end {{/nav}} ← end story
+```
+
+### Input
+
+Let the reader provide values. `input` does not pause the story where it appears; when the reader leaves the current scene, all inputs in that scene are submitted together with the selected navigation target.
+
+Inputs write to chapter `locals` by default. Prefix the variable name with `$` to write to `globals`.
+
+```markdown
+{{input "string"  name="Alice"}} ← local text input
+{{input "number"  age=30}} ← local number input
+{{input "boolean" brave=true}} ← local checkbox
+{{input "string"  $name="Alice"}} ← global text input
+```
+
+Use global values later anywhere in the story:
+
+```markdown
+Your name is {{name}}.
+```
+
+### Logic & Variables
+
+Handlebars `{{#if}}` works with boolean globals and locals:
+
+```markdown
+{{#if hasKey}}
+You unlock the door.
+{{else}}
+The door is locked.
+{{/if}}
+```
+
+Globals persist across the whole story. Chapter `locals` are reset and re-computed each time the chapter is entered. Scene `view()` provides render-only values for the current scene.
+
+### Images & Resources
+
+Reference assets defined in YAML metadata:
+
+```yaml
+assets:
+  map: "https://example.com/map.png"
+  bgm: { url: "https://example.com/audio.mp3", mime: "audio/mpeg" }
+```
+
+```markdown
+![]({asset "map"})
+{{asset "bgm"}} → outputs the URL
+{{mime "bgm"}} → outputs "audio/mpeg"
+```
+
+### Stylesheets
+
+Include CSS via `<style>` tags under the story heading:
+
+```html
+<style>
+  .clue {
+    color: #ffd700;
+  }
+</style>
+```
+
+### Include
+
+Use `!include("target")` to splice another Markdown source before parsing:
+
+```markdown
+!include("./chapter-1.md")
+!include("/stories/common.md")
+!include("https://example.com/shared.md")
+```
+
+Use `fromPath(pathOrUrl)` to load an entry story and its includes through one path or URL. In Node, relative entry paths are resolved from `cwd`, absolute paths load from the file system, and URLs load over the network. In browsers, relative entry paths resolve from the current page URL, absolute paths resolve from the current origin, and URLs stay unchanged. Includes follow the same rule relative to the file or URL that contains the `!include`. Pass `base` or `resolveInclude` to `fromPath()`, `fromSource()`, or the lower-level `parseStorySource()` when you need custom include loading. You can also use `fromParsed()` to construct a story from an already-parsed structure.
+
+### Hooks
+
+Hooks are JavaScript functions that run at specific points. Export them from `<script>` tags.
+Each story, chapter, or scene scope may contain at most one `<script>` tag.
+
+| Level   | Position    | Hook                                   | Purpose                                                   |
+| ------- | ----------- | -------------------------------------- | --------------------------------------------------------- |
+| Story   | Under `#`   | `globals()`                            | Return initial global variables                           |
+|         |             | `onStart({ globals })`                 | Side effect when story begins                             |
+| Chapter | Under `##`  | `locals({ globals })`                  | Return chapter-local variables                            |
+|         |             | `onEnter({ globals, locals })`         | Side effect when entering the chapter                     |
+|         |             | `onLeave({ globals, locals, target })` | Side effect when leaving the chapter, including story end |
+| Scene   | Under `###` | `view({ globals, locals })`            | Return render-only values for the scene                   |
+|         |             | `onEnter({ globals, locals })`         | Side effect on scene enter                                |
+|         |             | `onLeave({ globals, locals, target })` | Side effect on scene exit                                 |
+
+Hooks with return values support both sync and `async`. `globals()` receives no arguments. `view()` receives the current runtime scopes, but its return value is only used for the current render.
+
+### Line Breaks
+
+```markdown
+{{linebreak}} ← one blank line
+{{linebreak 3}} ← three blank lines
+```
+
+Line breaks are renderer-aware: `\n` in Markdown output, `<br>` in HTML output.
+
+### CLI
+
+```bash
+# Play a story interactively in the terminal
+npx mdstory play my-story.md
+
+# Play with debug output
+npx mdstory play my-story.md --debug
+
+# Build a standalone HTML file and open in browser
+npx mdstory build my-story.md
+
+# Build to a specific output path
+npx mdstory build my-story.md -o dist/story.html
+
+# Build without opening the browser
+npx mdstory build my-story.md --no-open
+
+# Build with debug output in the browser console
+npx mdstory build my-story.md --debug
+```
+
+### Example: Branching Scene
+
+```markdown
+### Crossroads {#crossroads}
+
+A fork in the road. Which way?
+
+{{#nav "chap1.forest"}}🌲 Into the woods{{/nav}}
+{{#nav "chap1.mountain"}}⛰️ Up the mountain{{/nav}}
+```
+
+## Examples
+
+Full working stories in [examples/](./examples/).
+
+### Chapter with Locals and Branching
+
+```markdown
+## The Dungeon {#dungeon}
+
+<script>
+  let attempts = 0;
+  export default {
+    locals() {
+      attempts++;
+      return { attempt: attempts };
+    },
+  };
+</script>
+
+### First Room {#room}
+
+You enter the dungeon. This is your {{attempt}}th attempt.
+
+{{input "boolean" ready=false}}
+
+{{#if ready}}
+The passage splits in two.
+{{#nav "dungeon.left"}}Go left{{/nav}}
+{{#nav "dungeon.right"}}Go right{{/nav}}
+{{else}}
+You're not ready yet.
+{{#nav "dungeon.room"}}Take a breath{{/nav}}
+{{/if}}
+```
+
+### Scene with View Hook
+
+```markdown
+### Treasure Chest {#chest}
+
+<script>
+  export default {
+    view({ globals }) {
+      const opened = globals.chestOpened || false;
+      return {
+        alreadyOpened: opened,
+        coins: opened ? 0 : 50,
+      };
+    },
+    onLeave({ globals }) {
+      globals.chestOpened = true;
+    },
+  };
+</script>
+
+{{#if alreadyOpened}}
+The chest is empty.
+{{else}}
+You found {{coins}} gold pieces!
+{{/if}}
+```
+
+### Cross-Chapter Navigation
+
+```markdown
+### Escape {#escape}
+
+{{#nav "dungeon.room"}}Go back inside{{/nav}}
+{{#nav "overworld.village"}}Run to the village{{/nav}}
+{{#nav null}}Give up{{/nav}}
+```
+
+### Full Story: Simple Choice
+
+```markdown
+---
+title: The Crossing
+---
+
+# The Crossing
+
+### Crossroads {#start}
+
+A stranger approaches you.
+
+{{input "string" $name="traveler"}}
+
+{{#nav "forest.path"}}Enter the forest{{/nav}}
+{{#nav "river.bridge"}}Cross the bridge{{/nav}}
+
+## Forest {#forest}
+
+### Deep Woods {#path}
+
+You walk among ancient trees, {{name}}.
+
+The forest whispers your name.
+
+{{#nav "start"}}Turn back{{/nav}}
+{{#nav null}}Rest here forever{{/nav}}
+
+## River {#river}
+
+### Old Bridge {#bridge}
+
+The wooden bridge creaks under your weight, {{name}}.
+
+On the far side, you see a light.
+
+{{#nav "start"}}Go back{{/nav}}
+{{#nav null}}Cross into the light{{/nav}}
+```