@elvishscout/mdstory 0.1.3 → 0.2.0

package/README.md

@@ -1,295 +1,323 @@
-# MdStory
-
-An interactive fiction scripting format based on Markdown and Handlebars.
-
-Online demo: <https://mdstory.elvish.cc>
-
-## Features
-
-- Seamless intergration 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 in 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 acts the same way as `{{name}}` except that it supports resource names with special characters.
-
-#### `{{mime name}}`
-
-Retrieves the MIME type of a resource file named `name`.
-
-### JavaScript Scripts
-
-JavaScript may be included into the story file 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, they will be 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`
-
-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 Scope`
-
-An object of variable values by their names, used to store global variables or input fields.
-
-### `type Asset`
-
-A referenceable resource file.
-
-#### Properties
-
-- `url`: The URL of the resource.
-- `mime (optional)`: The MIME type of the resource.
-
-### `type Metadata`
-
-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)`: An object of type [Scope](#type-scope) containing initial values of global variables.
-- `assets (optional)`: An object of resource names and [Asset](#type-asset) objects, containing all assets used in the story.
-
-### `type ChapterBody`
-
-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`
-
-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`
-
-Defines the global lifecycle hooks of the story.
-
-#### Properties
-
-- `onStart (optional)`: Called when the story starts.
-  - Parameters:
-    - `globals`: The initial values of global variables.
-  - Return value: Updated `globals` or `void`.
-
-### `type ChapterHooks`
-
-Defines the lifecycle hooks of a chapter.
-
-#### Properties
-
-- `onEnter (optional)`: Called when entering a chapter.
-  - Parameters:
-    - `globals`: Current global variables.
-  - Return value: Updated `globals` or `void`, effective only during the lifecycle of current chapter.
-- `onLeave (optional)`: Called when leaving a chapter.
-  - Parameters:
-    - `globals`: Current global variables.
-    - `fields`: Input fields from current chapter.
-  - Return value: Updated `globals` or `void`.
-- `onNavigate (optional)`: Called during chapter navigation.
-  - Parameters:
-    - `target` : `id` of target chapter.
-    - `globals`: Current global variables.
-    - `fields`: Input fields from current chapter.
-  - Return value: Updated `target` or `void`.
-
-### `type Renderer`
-
-Defines the renderer interface for generating outputs in different formats.
-
-#### Methods
-
-- `input({ name, type, value }) (optional)`: Generates the rendering result of an input field.
-
-  - Parameters:
-    - `name`: The name of the variable.
-    - `type`: The type of the variable.
-    - `value`: The default value of the variable.
-  - Return value: The rendered input field.
-
-- `nav({ target, children }) (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`
-
-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`
-
-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 type of the variable.
-  - `value`: The default value of the variable.
-- `sets`: An array of set fields, each containing:
-  - `name`: The name of the variable.
-  - `type`: The type of the variable.
-  - `value`: The 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`
-
-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`
-
-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(options)`: Initializes the chapter instance.
-  - Parameters:
-    - `options`: The chapter options of type [ChapterOptions](#type-chapteroptions).
-- `render(scope, assets, options)`: Renders the story content.
-  - Parameters:
-    - `scope`: The rendering context.
-    - `assets`: The story assets.
-    - `options`: The rendering options of type [RenderOptions](#type-renderoptions).
-  - Return value: The rendering result of type [RenderResult](#type-renderresult).
-
-### `type StoryPrompt`
-
-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.
-  - `text`: The rendered chapter content.
-  - `inputs`, `sets`, `navs`: Fields from the rendering result.
-
-#### Return value
-
-- A `Promise` resolving to one of the following forms:
-  - `{ target, updates }`: The `id` of the target chapter and updated global variables.
-  - `FormData`: Contains the form data of user input.
-
-### `class StoryBase`
-
-Defines the base class of the story, containing the core logic of the story.
-
-#### Properties
-
-- `metadata`: Story [Metadata](#type-metadata).
-- `globals`: Global variables.
-- `chapters`: An object of chapters by their `id`s.
-- `entry`: The entry chapter of the story.
-- `hooks`: An object of type [StoryHooks](#type-storyhooks).
-- `stylesheet`: The global stylesheet of the story.
-- `assets`: An object of asset files by their alias names.
-
-#### Methods
-
-- `constructor({ metadata, chapters, entry, script, stylesheet })`: Initializes the story instance.
-- `play(prompt, options)`: Starts playing the story.
-  - Parameters:
-    - `prompt`: A function of type [StoryPrompt](#type-storyprompt).
-    - `options`: An object of type [RenderOptions](#type-renderoptions).
-
-### `function parseStoryContent`
-
-Parses the story content in Markdown format.
-
-#### Parameters
-
-- `content`: The story content in Markdown format.
-
-#### Return value
-
-- An object of type [StoryBody](#type-storybody).
-
-### `class Story`
-
-Inherits from [StoryBase](#class-storybase), creating a story instance from the story content in Markdown format.
-
-#### Methods
-
-- `constructor(content: string)`: Initializes the story instance.
+**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}}
+```