@elvishscout/mdstory 0.1.4 → 0.2.1

package/dist/cli/index.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { playCommand } from "./commands/play.js";
+import { buildCommand } from "./commands/build.js";
+const program = new Command();
+program
+    .name("mdstory")
+    .description("An interactive fiction scripting format based on Markdown and Handlebars.")
+    .version("0.1.4");
+program
+    .command("play")
+    .description("Play a story interactively in the terminal")
+    .argument("<story>", "Path to the story .md file")
+    .option("--debug", "Enable debug output")
+    .action(async (storyPath, options) => {
+    try {
+        await playCommand(storyPath, { debug: options.debug ?? false });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+program
+    .command("build")
+    .description("Generate a complete HTML page from a story and open it in the browser")
+    .argument("<story>", "Path to the story .md file")
+    .option("-o, --output <path>", "Output HTML file path")
+    .option("--no-open", "Do not open the generated HTML in the browser")
+    .option("--debug", "Print debug output to the browser console")
+    .action(async (storyPath, options) => {
+    try {
+        await buildCommand(storyPath, {
+            output: options.output,
+            open: options.open,
+            debug: options.debug ?? false,
+        });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/cli/markdown.js

@@ -0,0 +1,27 @@
+import MarkdownIt from "markdown-it";
+import pluginAttrs from "markdown-it-attrs";
+import pluginTerminal from "markdown-it-terminal";
+import pluginMark from "markdown-it-mark";
+export function createMarkdownRenderer() {
+    const md = new MarkdownIt({ html: true }).use(pluginAttrs).use(pluginTerminal).use(pluginMark);
+    // markdown-it-terminal doesn't support mark or <u> tags
+    const defaultHtmlInline = md.renderer.rules.html_inline;
+    md.renderer.rules.html_inline = (tokens, idx, ...args) => {
+        const tag = tokens[idx].content;
+        if (tag === "<u>")
+            return "\x1b[4m";
+        if (tag === "</u>")
+            return "\x1b[24m";
+        return defaultHtmlInline(tokens, idx, ...args);
+    };
+    const defaultHeadingClose = md.renderer.rules.heading_close;
+    md.renderer.rules.heading_close = (...args) => {
+        return (defaultHeadingClose?.(...args) ?? "") + "\n";
+    };
+    md.renderer.rules.mark_open = () => "\x1b[7m";
+    md.renderer.rules.mark_close = () => "\x1b[27m";
+    // markdown-it-terminal has a bug: blockquote_open/close don't declare (tokens, idx) params
+    md.renderer.rules.blockquote_open = () => "";
+    md.renderer.rules.blockquote_close = () => "\n";
+    return md;
+}

package/dist/cli/prompt.js

@@ -0,0 +1,44 @@
+import inquirer from "inquirer";
+export function createPrompt(md) {
+    return async ({ text, inputs: fields, navs }) => {
+        console.log(md.render(text).trim());
+        console.log();
+        let inputReplies;
+        let targetReplies;
+        try {
+            inputReplies = await inquirer.prompt(fields.map(({ name, type, value }) => {
+                if (type === "number") {
+                    return { type: "number", name, message: name, default: Number(value) };
+                }
+                else if (type === "boolean") {
+                    return { type: "confirm", name, message: name, default: Boolean(value) };
+                }
+                else {
+                    return { type: "input", name, message: name, default: String(value) };
+                }
+            }));
+            if (navs.length) {
+                targetReplies = await inquirer.prompt([
+                    {
+                        type: "list",
+                        name: "target",
+                        message: "Choose target",
+                        choices: navs.map(({ text, target }) => ({ name: text, value: target })),
+                    },
+                ]);
+            }
+            else {
+                targetReplies = null;
+            }
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "ExitPromptError") {
+                process.exit(0);
+            }
+            throw err;
+        }
+        const { target } = targetReplies ?? { target: null };
+        const inputs = Object.fromEntries(fields.map(({ name }) => [name, inputReplies[name]]));
+        return { target, inputs };
+    };
+}

package/dist/core/chapter.js

@@ -0,0 +1,31 @@
+import { Scene } from "./scene.js";
+import { renderTemplate } from "./render.js";
+import { getScriptModuleId, importScriptModule } from "./utils.js";
+/** A chapter grouping scenes with shared hooks and local variables. */
+export class Chapter {
+    constructor({ id, title, template, hooks, locals, scenes }) {
+        this.id = id;
+        this.title = title ?? "";
+        this.template = template ?? "";
+        this.hooks = hooks ?? {};
+        this.locals = locals ?? {};
+        this.scenes = scenes;
+    }
+    static async fromParsed(chapter) {
+        return new Chapter({
+            id: chapter.id,
+            title: chapter.title,
+            template: chapter.template,
+            scenes: await Promise.all(chapter.scenes.map((scene) => Scene.fromParsed(scene, chapter.id))),
+            hooks: await importScriptModule(chapter.script, getScriptModuleId(chapter.id)),
+        });
+    }
+    /** Renders the chapter template with the given scope and render options. */
+    render(scope, assets, options) {
+        return renderTemplate(this.template, scope, assets, options);
+    }
+    /** Get scene by scene id */
+    getScene(id) {
+        return this.scenes.find((scene) => scene.id === id) ?? null;
+    }
+}

package/dist/core/definitions.js

@@ -0,0 +1,2 @@
+/** Symbol key for the implicit default chapter holding orphan scenes. */
+export const DEFAULT_CHAPTER = Symbol("default");

package/dist/{base → core}/index.js

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

package/dist/core/parser.js

@@ -0,0 +1,228 @@
+import yaml from "js-yaml";
+import MarkdownIt from "markdown-it";
+import pluginFrontMatter from "markdown-it-front-matter";
+import pluginAttrs from "markdown-it-attrs";
+import { nanoid } from "nanoid";
+import { MetadataSchema, SceneHooksSchema, ChapterHooksSchema, StoryHooksSchema } from "./schema.js";
+import { DEFAULT_CHAPTER } from "./definitions.js";
+import { getScriptModuleId, loadSource, normalizePath, parseScript } from "./utils.js";
+async function expandIncludes(source, options, stack = []) {
+    const lines = source.split("\n");
+    const expanded = [];
+    for (const line of lines) {
+        const match = /^!include\(\s*(?:"([^"]+)"|'([^']+)')\s*\)\s*$/.exec(line.trim());
+        if (!match) {
+            expanded.push(line);
+            continue;
+        }
+        const target = match[1] ?? match[2];
+        const normalizedPath = await normalizePath(target, options.base);
+        if (stack.includes(normalizedPath)) {
+            throw new Error(`Circular include detected: ${[...stack, normalizedPath].join(" -> ")}`);
+        }
+        const source = await options.resolveInclude(normalizedPath);
+        expanded.push(await expandIncludes(source, { ...options, base: normalizedPath }, [...stack, normalizedPath]));
+    }
+    return expanded.join("\n");
+}
+export async function resolveParseOptions(options) {
+    return {
+        base: options?.base ?? (await normalizePath("./")),
+        resolveInclude: options?.resolveInclude ?? ((path) => loadSource(path)),
+    };
+}
+/**
+ * Parses a Markdown-formatted story source string into a structured StoryInit.
+ *
+ * Document structure:
+ * - `#` (h1): Optional story title — its `<script>` is story hooks
+ * - `##` (h2): Chapters — with chapter hooks, contain scenes
+ * - `###` (h3): Scenes — with scene hooks and Handlebars templates
+ */
+export async function parseStorySource(source, options) {
+    const parseOptions = await resolveParseOptions(options);
+    source = await expandIncludes(source, parseOptions);
+    source = source.replace(/\r\n?/g, "\n");
+    const md = new MarkdownIt({ html: true }).use(pluginAttrs).use(pluginFrontMatter, () => { });
+    const tokens = md.parse(source, {});
+    let metadata = MetadataSchema.parse({});
+    let stylesheet = "";
+    const headings = [];
+    const scripts = [];
+    const styleRanges = [];
+    tokens.forEach((token, i) => {
+        if (token.type === "front_matter" && token.meta) {
+            const frontMatter = MetadataSchema.parse(yaml.load(token.meta));
+            Object.assign(metadata, frontMatter);
+        }
+        else if (token.type === "heading_open" &&
+            ["h1", "h2", "h3"].includes(token.tag) &&
+            token.level === 0 &&
+            token.map) {
+            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();
+                title = content.replace(/(\s*\{[^{}]*\})+$/, "").trim();
+                id || (id = title);
+            }
+            id || (id = nanoid());
+            if (id.includes(".")) {
+                throw new Error(`Chapter or scene id must not contain "." to avoid ambiguity: ${id}`);
+            }
+            {
+                let chapterId = null;
+                const chapterIdSet = new Set();
+                const fullSceneIdSet = new Set();
+                for (const heading of headings) {
+                    if (heading.tag === "h2") {
+                        if (chapterIdSet.has(heading.id)) {
+                            throw new Error(`Duplicated chapter id found: ${heading.id}`);
+                        }
+                        chapterId = heading.id;
+                        chapterIdSet.add(chapterId);
+                    }
+                    else if (heading.tag === "h3") {
+                        const fullSceneId = `${chapterId ?? ""}.${heading.id}`;
+                        if (fullSceneIdSet.has(fullSceneId)) {
+                            throw new Error(`Duplicated scene id found: ${fullSceneId}`);
+                        }
+                        fullSceneIdSet.add(fullSceneId);
+                    }
+                }
+            }
+            headings.push({ tag: token.tag, id, title, lineno: token.map[0] });
+        }
+        else if (token.type === "html_block" && token.map) {
+            let match;
+            if ((match = /^[\s]*<script>(.*)<\/script>[\s]*$/s.exec(token.content))) {
+                const script = match[1].trim();
+                if (script) {
+                    scripts.push({ from: token.map[0], to: token.map[1], content: script });
+                }
+            }
+            else if ((match = /^[\s]*<style>(.*)<\/style>[\s]*$/s.exec(token.content))) {
+                const style = match[1].trim();
+                if (style) {
+                    stylesheet += style;
+                    styleRanges.push(token.map);
+                }
+            }
+        }
+    });
+    const storyHeading = headings.find((h) => h.tag === "h1");
+    const chapterHeadings = headings.filter((h) => h.tag === "h2");
+    const sceneHeadings = headings.filter((h) => h.tag === "h3");
+    // Collect all script ranges and style ranges into a set for filtering
+    const ignoredLines = new Set();
+    for (const [from, to] of [...scripts.map(({ from, to }) => [from, to]), ...styleRanges]) {
+        for (let i = from; i < to; i++)
+            ignoredLines.add(i);
+    }
+    const lines = source.split("\n");
+    const storyEnd = chapterHeadings[0]?.lineno ?? sceneHeadings[0]?.lineno ?? lines.length;
+    // Story template from h1 heading to the first h2 or h3 (whichever comes first)
+    const storyTemplateEnd = Math.min(chapterHeadings[0]?.lineno ?? Infinity, sceneHeadings[0]?.lineno ?? Infinity);
+    const storyTemplate = (() => {
+        if (!isFinite(storyTemplateEnd))
+            return "";
+        const start = storyHeading?.lineno ?? 0;
+        return lines
+            .slice(start, storyTemplateEnd)
+            .filter((_, i) => !ignoredLines.has(start + i))
+            .join("\n")
+            .replace(/^\n+/, "");
+    })();
+    // Orphan h3s before the first h2 get a default chapter
+    const firstChapterLine = chapterHeadings[0]?.lineno ?? Infinity;
+    const defaultScenes = sceneHeadings.filter((sh) => sh.lineno < firstChapterLine);
+    // Build all chapters (default first, then parsed ones)
+    const chapters = [];
+    let chapterOrder = [];
+    if (defaultScenes.length > 0) {
+        const scenes = [];
+        let entryScene = null;
+        for (let si = 0; si < defaultScenes.length; si++) {
+            const sh = defaultScenes[si];
+            const seEnd = defaultScenes[si + 1]?.lineno ?? firstChapterLine;
+            const scScript = getScriptInScope(scripts, sh.lineno, seEnd, `scene "${sh.id}"`);
+            await parseScript(scScript, SceneHooksSchema, getScriptModuleId(DEFAULT_CHAPTER, sh.id));
+            const templateStart = sh.title ? sh.lineno : sh.lineno + 1;
+            const template = lines
+                .slice(templateStart, seEnd)
+                .filter((_, i) => !ignoredLines.has(templateStart + i))
+                .join("\n")
+                .replace(/^\n+/, "");
+            scenes.push({ id: sh.id, title: sh.title, template, script: scScript });
+            if (entryScene === null) {
+                entryScene = sh.id;
+            }
+        }
+        chapters.push({
+            id: DEFAULT_CHAPTER,
+            title: "",
+            template: "",
+            script: "",
+            scenes,
+        });
+    }
+    for (let ci = 0; ci < chapterHeadings.length; ci++) {
+        const ch = chapterHeadings[ci];
+        const chEnd = chapterHeadings[ci + 1]?.lineno ?? lines.length;
+        const chapterScenes = sceneHeadings.filter((sh) => sh.lineno > ch.lineno && sh.lineno < chEnd);
+        // Chapter script ends before the first scene heading
+        const chScriptEnd = chapterScenes[0]?.lineno ?? chEnd;
+        const chTemplateStart = ch.title ? ch.lineno : ch.lineno + 1;
+        const chTemplate = lines
+            .slice(chTemplateStart, chScriptEnd)
+            .filter((_, i) => !ignoredLines.has(chTemplateStart + i))
+            .join("\n")
+            .replace(/^\n+/, "");
+        const chScript = getScriptInScope(scripts, ch.lineno, chScriptEnd, `chapter "${ch.id}"`);
+        await parseScript(chScript, ChapterHooksSchema, getScriptModuleId(ch.id));
+        const scenes = [];
+        let entryScene = null;
+        for (let si = 0; si < chapterScenes.length; si++) {
+            const sh = chapterScenes[si];
+            const seEnd = chapterScenes[si + 1]?.lineno ?? chEnd;
+            const scScript = getScriptInScope(scripts, sh.lineno, seEnd, `scene "${sh.id}"`);
+            await parseScript(scScript, SceneHooksSchema, getScriptModuleId(ch.id, sh.id));
+            const templateStart = sh.title ? sh.lineno : sh.lineno + 1;
+            const template = lines
+                .slice(templateStart, seEnd)
+                .filter((_, i) => !ignoredLines.has(templateStart + i))
+                .join("\n")
+                .replace(/^\n+/, "");
+            scenes.push({ id: sh.id, title: sh.title, template, script: scScript });
+            if (entryScene === null) {
+                entryScene = sh.id;
+            }
+        }
+        chapters.push({
+            id: ch.id,
+            title: ch.title,
+            template: chTemplate,
+            script: chScript,
+            scenes,
+        });
+        chapterOrder.push(ch);
+    }
+    const storyScript = getScriptInScope(scripts, storyHeading?.lineno ?? 0, storyEnd, "story");
+    await parseScript(storyScript, StoryHooksSchema, getScriptModuleId());
+    return {
+        metadata,
+        title: storyHeading?.title ?? "",
+        template: storyTemplate,
+        chapters,
+        stylesheet,
+        script: storyScript,
+    };
+}
+function getScriptInScope(scripts, from, to, scope) {
+    const scopedScripts = scripts.filter((script) => script.from >= from && script.to <= to);
+    if (scopedScripts.length > 1) {
+        throw new Error(`More than one script block found in ${scope}`);
+    }
+    return scopedScripts[0]?.content ?? "";
+}

package/dist/{base/chapter.js → core/render.js}

@@ -1,19 +1,8 @@
 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";
-    }
-    if (typeof value === "number" || value === null) {
-        return "number";
-    }
-    if (typeof value === "boolean") {
-        return "boolean";
-    }
-    return "object";
-};
+import pluginMark from "markdown-it-mark";
+import { escapeHtml } from "./utils.js";
 const createElementHtml = (tag, attrs, children) => {
     // prettier-ignore
     const voidTags = [
@@ -48,7 +37,7 @@ const createInputHtml = ({ name, type, value }) => {
     const inputAttrs = {
         name,
         type: inputType,
-        value: inputType !== "checkbox" ? (type === "object" ? JSON.stringify(value) : String(value)) : undefined,
+        value: inputType !== "checkbox" ? String(value) : undefined,
         checked: inputType === "checkbox" && value ? "" : undefined,
         "aria-label": name,
     };
@@ -63,49 +52,49 @@ const createSubmitButtonHtml = ({ target, children }) => {
     return createElementHtml("button", buttonAttrs, children);
 };
 const markdownRenderer = {
+    html: false,
     input({ name, type }) {
         if (type === "boolean") {
-            return `[? _${name}_]`;
+            return `<u>[? ${name}]</u>`;
         }
         else {
-            return `[> _${name}_]`;
+            return `<u>[> ${name}]</u>`;
         }
     },
     nav({ children }) {
-        return `[@ __${children}__]`;
+        return `<u>[@ ${children}]</u>`;
+    },
+    linebreak({ n }) {
+        return "\n".repeat(n ?? 1);
     },
 };
 const htmlRenderer = {
+    html: true,
     input({ type, name, value }) {
         return createInputHtml({ name, type, value });
     },
     nav({ target, children }) {
         return createSubmitButtonHtml({ target: target ?? "", children });
     },
+    linebreak({ n }) {
+        return "<br>".repeat(n ?? 1);
+    },
 };
-const useHelper = ({ inputs, sets, navs }, assets, renderer) => {
+function useHelper({ inputs, navs }, assets, renderer) {
     return {
         input(type, opt) {
             for (const name in opt.hash) {
                 const value = opt.hash[name];
                 inputs.push({ name, type, value });
-                const result = renderer.input ? renderer.input({ name, type, value }) : "";
+                const result = renderer.input?.({ name, type, value }) ?? "";
                 return new Handlebars.SafeString(result);
             }
             return "";
         },
-        set(opt) {
-            for (const name in opt.hash) {
-                const value = opt.hash[name];
-                const type = valueType(value);
-                sets.push({ name, type, value });
-            }
-            return "";
-        },
         nav(target, opt) {
             const text = opt.fn(this).trim();
             navs.push({ text, target });
-            const result = renderer.nav ? renderer.nav({ target, children: text }) : "";
+            const result = renderer.nav?.({ target, children: text }) ?? "";
             return new Handlebars.SafeString(result);
         },
         asset(name) {
@@ -115,43 +104,36 @@ const useHelper = ({ inputs, sets, navs }, assets, renderer) => {
             return new Handlebars.SafeString(assets[name]?.mime ?? "");
         },
         linebreak(n) {
-            return new Handlebars.SafeString("<br>".repeat(n ?? 1));
+            const result = renderer.linebreak?.({ n }) ?? "";
+            return new Handlebars.SafeString(result);
         },
     };
-};
-export class Chapter {
-    constructor({ id, title, template, hooks }) {
-        this.id = id;
-        this.title = title;
-        this.template = template;
-        this.hooks = hooks;
+}
+/**
+ * Compiles a Handlebars template with built-in helpers, optionally renders
+ * through MarkdownIt, and returns the rendered text with extracted fields.
+ */
+export function renderTemplate(template, scope, assets, options) {
+    let resolvedRenderer;
+    if (options.renderer === "markdown") {
+        resolvedRenderer = markdownRenderer;
     }
-    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 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);
-        }
-        else {
-            text = Handlebars.compile(this.template, { noEscape: true })(scope, { helpers });
-        }
-        return { text, ...fields };
+    else if (options.renderer === "html") {
+        resolvedRenderer = htmlRenderer;
+    }
+    else {
+        resolvedRenderer = options.renderer;
+    }
+    const fields = { inputs: [], navs: [] };
+    const helpers = useHelper(fields, assets, resolvedRenderer);
+    let text;
+    if (resolvedRenderer.html) {
+        const md = new MarkdownIt({ html: true }).use(pluginAttrs).use(pluginMark);
+        text = Handlebars.compile(template)(scope, { helpers });
+        text = md.render(text);
+    }
+    else {
+        text = Handlebars.compile(template, { noEscape: true })(scope, { helpers });
     }
+    return { text, ...fields };
 }

package/dist/core/scene.js

@@ -0,0 +1,28 @@
+import { renderTemplate } from "./render.js";
+import { getScriptModuleId, importScriptModule } from "./utils.js";
+/** Defines a scene with a Handlebars template and lifecycle hooks. */
+export class Scene {
+    constructor({ id, title, template, hooks }) {
+        this.id = id;
+        this.title = title ?? "";
+        this.template = template;
+        this.hooks = hooks ?? {};
+    }
+    static async fromParsed(scene, chapterId) {
+        return new Scene({
+            id: scene.id,
+            title: scene.title,
+            template: scene.template,
+            hooks: await importScriptModule(scene.script, getScriptModuleId(chapterId, scene.id)),
+        });
+    }
+    /**
+     * Renders the scene content using the given scope and render options.
+     * @param scope - Variables available to the Handlebars template.
+     * @param assets - Asset objects keyed by name.
+     * @param options - Rendering options (format, html).
+     */
+    render(scope, assets, options) {
+        return renderTemplate(this.template, scope, assets, options);
+    }
+}

package/dist/core/schema.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+function PromiseLikeSchema(schema) {
+    return schema.or(schema.promise());
+}
+export const VariableSchema = z.any().transform((v) => v);
+export const ScopeSchema = z.record(VariableSchema);
+const AssetObjectSchema = z.object({
+    url: z.string(),
+    mime: z.string().optional(),
+    alt: 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().optional(),
+    author: z.string().optional(),
+    email: z.string().optional(),
+    globals: ScopeSchema.optional(),
+    assets: AssetsSchema.optional(),
+});
+export const StoryHooksSchema = z
+    .object({
+    globals: z.function().returns(PromiseLikeSchema(ScopeSchema.optional())),
+    onStart: z.function(),
+})
+    .partial();
+export const ChapterHooksSchema = z
+    .object({
+    locals: z.function().returns(PromiseLikeSchema(ScopeSchema.optional())),
+    onEnter: z.function(),
+    onLeave: z.function(),
+})
+    .partial();
+export const SceneHooksSchema = z
+    .object({
+    view: z.function().returns(PromiseLikeSchema(ScopeSchema.optional())),
+    onEnter: z.function(),
+    onLeave: z.function(),
+})
+    .partial();