@elvishscout/mdstory 0.1.1 → 0.1.3

package/README.md

@@ -1,5 +1,295 @@
 # MdStory
 
-An interactive story format based on Markdown and Handlebars with JavaScript support.
+An interactive fiction scripting format based on Markdown and Handlebars.
 
-Online demo available on <https://mdstory.elvish.cc>.
+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.

package/dist/base/chapter.js

@@ -1,6 +1,7 @@
 import Handlebars from "handlebars";
 import MarkdownIt from "markdown-it";
 import pluginAttrs from "markdown-it-attrs";
+const escapeHtml = (text) => text.replace(/[<>&'"]/g, (ch) => `&#${ch.charCodeAt(0)};`);
 const valueType = (value) => {
     if (typeof value === "string") {
         return "string";
@@ -13,7 +14,6 @@ const valueType = (value) => {
     }
     return "object";
 };
-const escapeHtml = (text) => text.replace(/[<>&'"]/g, (ch) => `&#${ch.charCodeAt(0)};`);
 const createElementHtml = (tag, attrs, children) => {
     // prettier-ignore
     const voidTags = [
@@ -21,88 +21,102 @@ const createElementHtml = (tag, attrs, children) => {
         "link", "meta", "param", "source", "track", "wbr",
     ];
     const attrText = Object.entries(attrs)
-        .filter(([, value]) => value !== undefined)
         .map(([name, value]) => {
         if (typeof value === "boolean") {
             value = value ? "" : undefined;
         }
-        const escapedValue = escapeHtml(value ?? "");
-        return `${name}="${escapedValue}"`;
+        if (value === undefined) {
+            return null;
+        }
+        if (value) {
+            const escapedValue = escapeHtml(value ?? "");
+            return `${name}="${escapedValue}"`;
+        }
+        else {
+            return name;
+        }
     })
+        .filter((attr) => attr !== null)
         .join(" ");
     if (voidTags.includes(tag)) {
         return `<${tag} ${attrText}>`;
     }
     return `<${tag} ${attrText}>${children ?? ""}</${tag}>`;
 };
-const createInputHtml = ({ tagMap = {}, name, type, value, required, readonly, }) => {
-    const tag = tagMap["input"] ?? "input";
+const createInputHtml = ({ name, type, value }) => {
     const inputType = type === "boolean" ? "checkbox" : "text";
     const inputAttrs = {
         name,
         type: inputType,
         value: inputType !== "checkbox" ? (type === "object" ? JSON.stringify(value) : String(value)) : undefined,
         checked: inputType === "checkbox" && value ? "" : undefined,
-        required,
-        readonly,
         "aria-label": name,
     };
-    return createElementHtml(tag, inputAttrs);
+    return createElementHtml("input", inputAttrs);
 };
-const createSubmitButtonHtml = ({ tagMap = {}, target, children, }) => {
-    const tag = tagMap["button"] ?? "button";
+const createSubmitButtonHtml = ({ target, children }) => {
     const buttonAttrs = {
         name: "@target",
         type: "submit",
         value: target,
     };
-    return createElementHtml(tag, buttonAttrs, children);
+    return createElementHtml("button", buttonAttrs, children);
 };
-const createInputMarkdown = ({ name, type }) => {
-    if (type === "boolean") {
-        return `[ ${name}? ]`;
-    }
-    return `[> ${name} <]`;
+const markdownRenderer = {
+    input({ name, type }) {
+        if (type === "boolean") {
+            return `[? _${name}_]`;
+        }
+        else {
+            return `[> _${name}_]`;
+        }
+    },
+    nav({ children }) {
+        return `[@ __${children}__]`;
+    },
+};
+const htmlRenderer = {
+    input({ type, name, value }) {
+        return createInputHtml({ name, type, value });
+    },
+    nav({ target, children }) {
+        return createSubmitButtonHtml({ target: target ?? "", children });
+    },
 };
-const useHelper = ({ inputs, sets, navs }, options) => {
+const useHelper = ({ inputs, sets, navs }, assets, renderer) => {
     return {
         input(type, opt) {
-            let result = "";
             for (const name in opt.hash) {
                 const value = opt.hash[name];
                 inputs.push({ name, type, value });
-                if (options.format === "html") {
-                    result = createInputHtml({ name, type, value, ...options });
-                }
-                else {
-                    result = createInputMarkdown({ name, type });
-                }
-                break;
+                const result = renderer.input ? renderer.input({ name, type, value }) : "";
+                return new Handlebars.SafeString(result);
             }
-            return new Handlebars.SafeString(result);
+            return "";
         },
         set(opt) {
-            const result = Object.entries(opt.hash)
-                .map(([name, value]) => {
+            for (const name in opt.hash) {
+                const value = opt.hash[name];
                 const type = valueType(value);
                 sets.push({ name, type, value });
-                if (options.format === "html") {
-                    return createInputHtml({ name, type, value, readonly: true, ...options });
-                }
-                return "";
-            })
-                .join("");
-            return new Handlebars.SafeString(result);
+            }
+            return "";
         },
         nav(target, opt) {
-            let result = "";
             const text = opt.fn(this).trim();
             navs.push({ text, target });
-            if (options.format === "html") {
-                result = createSubmitButtonHtml({ target: target ?? "", children: text, ...options });
-            }
+            const result = renderer.nav ? renderer.nav({ target, children: text }) : "";
             return new Handlebars.SafeString(result);
         },
+        asset(name) {
+            return new Handlebars.SafeString(assets[name]?.url ?? "");
+        },
+        mime(name) {
+            return new Handlebars.SafeString(assets[name]?.mime ?? "");
+        },
+        linebreak(n) {
+            return new Handlebars.SafeString("<br>".repeat(n ?? 1));
+        },
     };
 };
 export class Chapter {
@@ -112,19 +126,31 @@ export class Chapter {
         this.template = template;
         this.hooks = hooks;
     }
-    render(scope, options) {
-        const md = new MarkdownIt({ html: true }).use(pluginAttrs);
+    render(scope, assets = {}, { format, html }) {
+        let renderer;
+        if (format === "markdown") {
+            renderer = markdownRenderer;
+        }
+        else if (format === "html") {
+            renderer = htmlRenderer;
+        }
+        else {
+            renderer = format;
+        }
         const fields = {
             inputs: [],
             sets: [],
             navs: [],
         };
-        const handle = Handlebars.create();
-        handle.registerHelper(useHelper(fields, options));
-        let text = handle.compile(this.template)(scope);
-        if (options.format === "html") {
+        const helpers = useHelper(fields, assets, renderer);
+        let text;
+        if (html) {
+            const md = new MarkdownIt({ html: true }).use(pluginAttrs);
+            text = Handlebars.compile(this.template)(scope, { helpers });
             text = md.render(text);
-            text = createElementHtml("input", { type: "submit", disabled: true, hidden: true }) + text;
+        }
+        else {
+            text = Handlebars.compile(this.template, { noEscape: true })(scope, { helpers });
         }
         return { text, ...fields };
     }

package/dist/base/definitions.js

@@ -1,9 +1,18 @@
 import { z } from "zod";
 export const ValueSchema = z.any().transform((v) => v);
 export const ScopeSchema = z.record(ValueSchema);
+const AssetObjectSchema = z.object({ url: z.string(), mime: z.string().optional() });
+export const AssetSchema = z.union([
+    z.string().transform((url) => AssetObjectSchema.parse({ url, mime: undefined })),
+    AssetObjectSchema,
+]);
+export const AssetsSchema = z.record(AssetSchema);
 export const MetadataSchema = z.object({
-    title: z.string().default(""),
-    globals: ScopeSchema.default({}),
+    title: z.string().optional(),
+    author: z.string().optional(),
+    email: z.string().optional(),
+    globals: ScopeSchema.optional(),
+    assets: AssetsSchema.optional(),
 });
 const TargetSchema = z.string().or(z.null());
 export const StoryHooksSchema = z

package/dist/base/index.js

@@ -1,4 +1,5 @@
 export * from "./definitions.js";
 export * from "./story.js";
+export * from "./parser.js";
 export * from "./chapter.js";
 export * from "./error.js";

package/dist/base/parser.js

@@ -0,0 +1,86 @@
+import yaml from "js-yaml";
+import MarkdownIt from "markdown-it";
+import pluginFrontMatter from "markdown-it-front-matter";
+import pluginAttrs from "markdown-it-attrs";
+import { MetadataSchema } from "./definitions.js";
+import { DuplicateIdError, EmptyChapterIdError, InvalidMetadataError } from "./error.js";
+export const parseStoryContent = (content) => {
+    const md = new MarkdownIt({ html: true }).use(pluginAttrs).use(pluginFrontMatter, () => { });
+    const tokens = md.parse(content, {});
+    let metadata = MetadataSchema.parse({});
+    let storyScript = "";
+    let stylesheet = "";
+    const ignoredRanges = [];
+    const divisions = [];
+    tokens.forEach((token, i) => {
+        if (token.type === "front_matter" && token.meta) {
+            try {
+                const frontMatter = MetadataSchema.parse(yaml.load(token.meta));
+                metadata = Object.assign(metadata, frontMatter);
+            }
+            catch {
+                throw new InvalidMetadataError(token.meta);
+            }
+        }
+        else if (token.type === "heading_open" && token.tag === "h1" && token.level === 0 && token.map) {
+            const lineno = token.map[0];
+            let id = token.attrs?.find(([key]) => key === "id")?.[1] ?? "";
+            let title = "";
+            const nextToken = tokens[i + 1];
+            if (nextToken && nextToken.type === "inline") {
+                const content = nextToken.content.trim();
+                id || (id = content);
+                title = content;
+            }
+            if (!id) {
+                throw new EmptyChapterIdError();
+            }
+            if (divisions.find(({ id: _id }) => id === _id)) {
+                throw new DuplicateIdError(id);
+            }
+            divisions.push({ id, title, lineno, script: "" });
+        }
+        else if (token.type === "html_block" && token.map) {
+            let regres;
+            if ((regres = /^[\s]*<script>(.*)<\/script>[\s]*$/s.exec(token.content))) {
+                const script = regres[1].trim();
+                if (script) {
+                    if (divisions.length === 0) {
+                        storyScript = script;
+                    }
+                    else {
+                        divisions[divisions.length - 1].script = script;
+                    }
+                    ignoredRanges.push(token.map);
+                }
+            }
+            else if ((regres = /^[\s]*<style>(.*)<\/style>[\s]*$/s.exec(token.content))) {
+                const style = regres[1].trim();
+                stylesheet += style;
+                ignoredRanges.push(token.map);
+            }
+        }
+    });
+    const lines = content.split("\n").map((line, i) => {
+        if (ignoredRanges.find(([from, to]) => i >= from && i < to)) {
+            return null;
+        }
+        return line;
+    });
+    const chapterEntries = divisions.map(({ id, title, lineno, script }, i) => {
+        const template = lines
+            .slice(lineno, divisions[i + 1]?.lineno)
+            .filter((line) => line !== null)
+            .join("\n");
+        return [id, { title, template, script }];
+    });
+    const chapters = Object.fromEntries(chapterEntries);
+    const entry = chapterEntries[0]?.[0] || null;
+    return {
+        metadata,
+        chapters,
+        entry,
+        script: storyScript,
+        stylesheet,
+    };
+};

package/dist/base/story.js

@@ -1,10 +1,6 @@
-import yaml from "js-yaml";
-import MarkdownIt from "markdown-it";
-import pluginFrontMatter from "markdown-it-front-matter";
-import pluginAttrs from "markdown-it-attrs";
-import { MetadataSchema, StoryHooksSchema, ChapterHooksSchema, } from "./definitions.js";
+import { ChapterHooksSchema, StoryHooksSchema, } from "./definitions.js";
 import { Chapter } from "./chapter.js";
-import { ChapterNotFoundError, DuplicateIdError, EmptyChapterIdError, InvalidInputError, InvalidMetadataError, } from "./error.js";
+import { ChapterNotFoundError, InvalidInputError } from "./error.js";
 const parstInput = (type, text) => {
     if (type === "boolean") {
         return text === "on";
@@ -30,114 +26,36 @@ const parseFormData = (formData, { inputs, sets }) => {
     }));
     return { target, updates };
 };
-export const parseStoryContent = (content) => {
-    const md = new MarkdownIt({ html: true }).use(pluginAttrs).use(pluginFrontMatter, () => { });
-    const tokens = md.parse(content, {});
-    let metadata = MetadataSchema.parse({});
-    let storyScript = "";
-    let stylesheet = "";
-    const ignoredRanges = [];
-    const divisions = [];
-    tokens.forEach((token, i) => {
-        if (token.type === "front_matter" && token.meta) {
-            try {
-                const frontMatter = MetadataSchema.parse(yaml.load(token.meta));
-                metadata = { ...metadata, ...frontMatter };
-            }
-            catch {
-                throw new InvalidMetadataError(token.meta);
-            }
-        }
-        else if (token.type === "heading_open" && token.tag === "h1" && token.level === 0 && token.map) {
-            const lineno = token.map[0];
-            let id = token.attrs?.find(([key]) => key === "id")?.[1] ?? "";
-            let title = "";
-            const nextToken = tokens[i + 1];
-            if (nextToken && nextToken.type === "inline") {
-                const content = nextToken.content.trim();
-                id || (id = content);
-                title = content;
-            }
-            if (!id) {
-                throw new EmptyChapterIdError();
-            }
-            if (divisions.find(({ id: _id }) => id === _id)) {
-                throw new DuplicateIdError(id);
-            }
-            divisions.push({ id, title, lineno, script: "" });
-        }
-        else if (token.type === "html_block" && token.map) {
-            let regres;
-            if ((regres = /^[\s]*<script>(.*)<\/script>[\s]*$/s.exec(token.content))) {
-                const script = regres[1].trim();
-                if (script) {
-                    if (divisions.length === 0) {
-                        storyScript = script;
-                    }
-                    else {
-                        divisions[divisions.length - 1].script = script;
-                    }
-                    ignoredRanges.push(token.map);
-                }
-            }
-            else if ((regres = /^[\s]*<style>(.*)<\/style>[\s]*$/s.exec(token.content))) {
-                const style = regres[1].trim();
-                stylesheet += style;
-                ignoredRanges.push(token.map);
-            }
-        }
-    });
-    const lines = content.split("\n").map((line, i) => {
-        if (ignoredRanges.find(([from, to]) => i >= from && i < to)) {
-            return null;
-        }
-        return line;
-    });
-    const chapterEntries = divisions.map(({ id, title, lineno, script }, i) => {
-        const template = lines
-            .slice(lineno, divisions[i + 1]?.lineno)
-            .filter((line) => line !== null)
-            .join("\n");
-        const hooks = script ? ChapterHooksSchema.parse(new Function(script)()) : {};
-        return [id, { title, template, hooks }];
-    });
-    const chapters = Object.fromEntries(chapterEntries);
-    const entry = chapterEntries[0]?.[0] || null;
-    const hooks = storyScript ? StoryHooksSchema.parse(new Function(storyScript)()) : {};
-    return {
-        metadata,
-        chapters,
-        entry,
-        hooks,
-        stylesheet,
-    };
-};
 export class StoryBase {
-    constructor({ metadata, chapters, entry, hooks, stylesheet }) {
-        const realChapters = Object.fromEntries(Object.entries(chapters).map(([id, options]) => {
-            return [id, new Chapter({ id, ...options })];
+    constructor({ metadata, chapters, entry, script, stylesheet }) {
+        const realChapters = Object.fromEntries(Object.entries(chapters).map(([id, { title, template, script }]) => {
+            const hooks = (script && ChapterHooksSchema.parse(new Function(script)())) || {};
+            return [id, new Chapter({ id, title, template, hooks })];
         }));
         this.metadata = metadata;
-        this.globals = metadata.globals;
+        this.globals = metadata.globals ?? {};
         this.chapters = realChapters;
         this.entry = (entry && realChapters[entry]) || null;
-        this.hooks = hooks;
+        this.hooks = (script && StoryHooksSchema.parse(new Function(script)())) || {};
         this.stylesheet = stylesheet;
+        this.assets = metadata.assets ?? {};
     }
     async play(prompt, options) {
         if (this.hooks.onStart) {
             this.hooks.onStart(this.globals);
         }
+        const assetsUrl = Object.fromEntries(Object.entries(this.assets).map(([name, { url }]) => [name, url]));
         let chapter = this.entry;
         while (chapter) {
-            let modifiedGlobals = this.globals;
+            let scope = this.globals;
+            scope = Object.assign(scope, assetsUrl);
             if (chapter.hooks.onEnter) {
                 const modified = chapter.hooks.onEnter(this.globals);
                 if (modified !== undefined) {
-                    modifiedGlobals = Object.assign(modifiedGlobals, modified);
+                    scope = Object.assign(scope, modified);
                 }
             }
-            const renderResult = chapter.render(modifiedGlobals, options);
+            const renderResult = chapter.render(scope, this.assets, options);
             const promptResult = await prompt({ chapter, ...renderResult });
             const { target, updates } = promptResult instanceof FormData ? parseFormData(promptResult, renderResult) : promptResult;
             let modifiedTarget = target;

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@elvishscout/mdstory",
-  "version": "0.1.1",
-  "description": "An interactive story format based on Markdown and Handlebars with JavaScript support.",
+  "repository": "https://github.com/ElvishScout/mdstory.git",
+  "version": "0.1.3",
+  "description": "An interactive fiction scripting format based on Markdown and Handlebars.",
   "main": "./dist/index.js",
   "type": "module",
   "files": [
@@ -37,4 +38,4 @@
   ],
   "author": "Jiakai Jiang",
   "license": "ISC"
-}
+}

package/types/base/chapter.d.ts

@@ -1,13 +1,22 @@
-import { ValueType, Value, ChapterHooks, Scope } from "./definitions.js";
-type MarkdownOptions = {};
-type HtmlOptions = {
-    tagMap?: Record<string, string>;
+import { ValueType, Value, ChapterHooks, Scope, Asset } from "./definitions.js";
+export type Renderer = {
+    input?: ({ name, type, value }: {
+        name: string;
+        type: ValueType;
+        value: string;
+    }) => string;
+    nav?: ({ target, children }: {
+        target: string | null;
+        children: string;
+    }) => string;
 };
-export type RenderOptions = ({
-    format: "markdown";
-} & MarkdownOptions) | ({
-    format: "html";
-} & HtmlOptions);
+export type RenderOptions = {
+    format: "markdown" | "html" | Renderer;
+    html?: boolean;
+};
+export type RenderResult = {
+    text: string;
+} & Fields;
 type Fields = {
     inputs: {
         name: string;
@@ -24,9 +33,6 @@ type Fields = {
         target: string | null;
     }[];
 };
-export type RenderResult = {
-    text: string;
-} & Fields;
 export type ChapterOptions = {
     id: string;
     title: string;
@@ -39,6 +45,6 @@ export declare class Chapter {
     template: string;
     hooks: ChapterHooks;
     constructor({ id, title, template, hooks }: ChapterOptions);
-    render(scope: Scope, options: RenderOptions): RenderResult;
+    render(scope: Scope, assets: Record<string, Asset> | undefined, { format, html }: RenderOptions): RenderResult;
 }
 export {};

package/types/base/definitions.d.ts

@@ -7,15 +7,68 @@ type JsonObject = {
 type JsonValue = JsonPrimitive | JsonArray | JsonObject;
 export declare const ValueSchema: z.ZodEffects<z.ZodAny, string | number | boolean | JsonArray | JsonObject | null, any>;
 export declare const ScopeSchema: z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodAny, string | number | boolean | JsonArray | JsonObject | null, any>>;
+export declare const AssetSchema: z.ZodUnion<[z.ZodEffects<z.ZodString, {
+    url: string;
+    mime?: string | undefined;
+}, string>, z.ZodObject<{
+    url: z.ZodString;
+    mime: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    mime?: string | undefined;
+}, {
+    url: string;
+    mime?: string | undefined;
+}>]>;
+export declare const AssetsSchema: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodEffects<z.ZodString, {
+    url: string;
+    mime?: string | undefined;
+}, string>, z.ZodObject<{
+    url: z.ZodString;
+    mime: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    mime?: string | undefined;
+}, {
+    url: string;
+    mime?: string | undefined;
+}>]>>;
 export declare const MetadataSchema: z.ZodObject<{
-    title: z.ZodDefault<z.ZodString>;
-    globals: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodAny, string | number | boolean | JsonArray | JsonObject | null, any>>>;
+    title: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    globals: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodAny, string | number | boolean | JsonArray | JsonObject | null, any>>>;
+    assets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodEffects<z.ZodString, {
+        url: string;
+        mime?: string | undefined;
+    }, string>, z.ZodObject<{
+        url: z.ZodString;
+        mime: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        mime?: string | undefined;
+    }, {
+        url: string;
+        mime?: string | undefined;
+    }>]>>>;
 }, "strip", z.ZodTypeAny, {
-    title: string;
-    globals: Record<string, string | number | boolean | JsonArray | JsonObject | null>;
+    title?: string | undefined;
+    author?: string | undefined;
+    email?: string | undefined;
+    globals?: Record<string, string | number | boolean | JsonArray | JsonObject | null> | undefined;
+    assets?: Record<string, {
+        url: string;
+        mime?: string | undefined;
+    }> | undefined;
 }, {
     title?: string | undefined;
+    author?: string | undefined;
+    email?: string | undefined;
     globals?: Record<string, any> | undefined;
+    assets?: Record<string, string | {
+        url: string;
+        mime?: string | undefined;
+    }> | undefined;
 }>;
 export declare const StoryHooksSchema: z.ZodObject<{
     onStart: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodAny, string | number | boolean | JsonArray | JsonObject | null, any>>], z.ZodUnknown>, z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodAny, string | number | boolean | JsonArray | JsonObject | null, any>>, z.ZodVoid]>>>;
@@ -39,8 +92,22 @@ export declare const ChapterHooksSchema: z.ZodObject<{
 }>;
 export type Value = z.infer<typeof ValueSchema>;
 export type Scope = z.infer<typeof ScopeSchema>;
+export type Asset = z.infer<typeof AssetSchema>;
 export type Metadata = z.infer<typeof MetadataSchema>;
 export type StoryHooks = z.infer<typeof StoryHooksSchema>;
 export type ChapterHooks = z.infer<typeof ChapterHooksSchema>;
 export type ValueType = "string" | "number" | "boolean" | "object";
+export type ChapterBody = {
+    title: string;
+    template: string;
+    script: string;
+};
+export type StoryBody = {
+    metadata: Metadata;
+    chapters: Record<string, ChapterBody>;
+    entry: string | null;
+    script: string;
+    stylesheet: string;
+};
+export type StoryAssets = Record<string, string>;
 export {};

package/types/base/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./definitions.js";
 export * from "./story.js";
+export * from "./parser.js";
 export * from "./chapter.js";
 export * from "./error.js";

package/types/base/parser.d.ts

@@ -0,0 +1,2 @@
+import { StoryBody } from "./definitions.js";
+export declare const parseStoryContent: (content: string) => StoryBody;

package/types/base/story.d.ts

@@ -1,4 +1,4 @@
-import { StoryHooks, Scope, Metadata, ChapterHooks } from "./definitions.js";
+import { StoryBody, StoryHooks, Scope, Metadata, Asset } from "./definitions.js";
 import { Chapter, RenderOptions, RenderResult } from "./chapter.js";
 export type StoryPrompt = (props: {
     chapter: Chapter;
@@ -6,19 +6,6 @@ export type StoryPrompt = (props: {
     target: string | null;
     updates: Scope;
 } | FormData>;
-type ChapterBody = {
-    title: string;
-    template: string;
-    hooks: ChapterHooks;
-};
-type StoryBody = {
-    metadata: Metadata;
-    chapters: Record<string, ChapterBody>;
-    entry: string | null;
-    hooks: StoryHooks;
-    stylesheet: string;
-};
-export declare const parseStoryContent: (content: string) => StoryBody;
 export declare class StoryBase {
     metadata: Metadata;
     globals: Scope;
@@ -26,7 +13,7 @@ export declare class StoryBase {
     entry: Chapter | null;
     hooks: StoryHooks;
     stylesheet: string;
-    constructor({ metadata, chapters, entry, hooks, stylesheet }: StoryBody);
+    assets: Record<string, Asset>;
+    constructor({ metadata, chapters, entry, script, stylesheet }: StoryBody);
     play(prompt: StoryPrompt, options: RenderOptions): Promise<void>;
 }
-export {};