@elvishscout/mdstory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ElvishScout
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# MdStory
+
+An interactive story format based on Markdown and Handlebars with JavaScript support.
+
+Online demo available on <https://mdstory.elvish.cc>.

package/dist/base/chapter.js

@@ -0,0 +1,128 @@
+import handlebars from "handlebars";
+import MarkdownIt from "markdown-it";
+import pluginAttrs from "markdown-it-attrs";
+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";
+};
+const escapeHtml = (text) => text.replace(/[<>&'"]/g, (ch) => `&#${ch.charCodeAt(0)};`);
+const createElementHtml = (tag, attrs, children) => {
+    // prettier-ignore
+    const voidTags = [
+        "area", "base", "br", "col", "embed", "hr", "img", "input",
+        "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}"`;
+    })
+        .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 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);
+};
+const createSubmitButtonHtml = ({ tagMap = {}, target, children, }) => {
+    const tag = tagMap["button"] ?? "button";
+    const buttonAttrs = {
+        name: "@target",
+        type: "submit",
+        value: target,
+    };
+    return createElementHtml(tag, buttonAttrs, children);
+};
+const createInputMarkdown = ({ name, type }) => {
+    if (type === "boolean") {
+        return `[ ${name}? ]`;
+    }
+    return `[> ${name} <]`;
+};
+const useHelper = ({ inputs, sets, navs }, options) => {
+    return {
+        input(type, opt) {
+            for (const name in opt.hash) {
+                const value = opt.hash[name];
+                inputs.push({ name, type, value });
+                if (options.format === "html") {
+                    return createInputHtml({ name, type, value, ...options });
+                }
+                return createInputMarkdown({ name, type });
+            }
+            return "";
+        },
+        set(opt) {
+            return Object.entries(opt.hash)
+                .map(([name, value]) => {
+                const type = valueType(value);
+                sets.push({ name, type, value });
+                if (options.format === "html") {
+                    return createInputHtml({ name, type, value, readonly: true, ...options });
+                }
+                return "";
+            })
+                .join("");
+        },
+        nav(target, opt) {
+            const text = opt.fn(target).trim();
+            navs.push({ text, target });
+            if (options.format === "html") {
+                return createSubmitButtonHtml({ target: target ?? "", children: text, ...options });
+            }
+            return "";
+        },
+        br(num) {
+            return new Array(num ?? 1).fill("<br>").join();
+        },
+    };
+};
+export class Chapter {
+    constructor({ id, title, template, hooks }) {
+        this.id = id;
+        this.title = title;
+        this.template = template;
+        this.hooks = hooks;
+    }
+    render(scope, options) {
+        const md = new MarkdownIt({ html: true }).use(pluginAttrs);
+        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") {
+            text = md.render(text);
+            text = createElementHtml("input", { type: "submit", disabled: true, hidden: true }) + text;
+        }
+        return { text, ...fields };
+    }
+}

package/dist/base/definitions.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+export const ValueSchema = z.any().transform((v) => v);
+export const ScopeSchema = z.record(ValueSchema);
+export const MetadataSchema = z.object({
+    title: z.string().default(""),
+    globals: ScopeSchema.default({}),
+});
+const TargetSchema = z.string().or(z.null());
+export const StoryHooksSchema = z
+    .object({
+    onStart: z.function().args(ScopeSchema).returns(ScopeSchema.or(z.void())),
+})
+    .partial();
+export const ChapterHooksSchema = z
+    .object({
+    onEnter: z.function().args(ScopeSchema).returns(ScopeSchema.or(z.void())),
+    onLeave: z.function().args(ScopeSchema, ScopeSchema).returns(ScopeSchema.or(z.void())),
+    onNavigate: z.function().args(TargetSchema, ScopeSchema, ScopeSchema).returns(TargetSchema.or(z.void())),
+})
+    .partial();

package/dist/base/error.js

@@ -0,0 +1,30 @@
+export class InvalidMetadataError extends Error {
+    constructor(content, message) {
+        super(message ?? `Invalid metadata:\n\`\`\`\n${content}\n\`\`\``);
+        this.content = content;
+    }
+}
+export class DuplicateIdError extends Error {
+    constructor(id, message) {
+        super(message ?? `Two chapters with the same id \`${id}\`.`);
+        this.id = id;
+    }
+}
+export class EmptyChapterIdError extends Error {
+    constructor(message) {
+        super(message ?? `Chapter id cannot be empty, either use an non-empty chapter title or explicitly specify an id.`);
+    }
+}
+export class ChapterNotFoundError extends Error {
+    constructor(target, message) {
+        super(message ?? `Chapter \`${target}\` not found.`);
+        this.target = target;
+    }
+}
+export class InvalidInputError extends Error {
+    constructor(name, input, message) {
+        super(message ?? `Invalid input \`${input}\` for variable \`${name}\`.`);
+        this.name = name;
+        this.input = input;
+    }
+}

package/dist/base/index.js

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

package/dist/base/story.js

@@ -0,0 +1,164 @@
+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 { Chapter } from "./chapter.js";
+import { ChapterNotFoundError, DuplicateIdError, EmptyChapterIdError, InvalidInputError, InvalidMetadataError, } from "./error.js";
+const parstInput = (type, text) => {
+    if (type === "boolean") {
+        return text === "on";
+    }
+    if (type === "number") {
+        return text ? Number(text) : null;
+    }
+    if (type === "object") {
+        return text ? JSON.parse(text) : null;
+    }
+    return text;
+};
+const parseFormData = (formData, { inputs, sets }) => {
+    const target = formData.get("@target") || null;
+    const updates = Object.fromEntries([...inputs, ...sets].map(({ name, type }) => {
+        const value = formData.get(name);
+        try {
+            return [name, parstInput(type, value)];
+        }
+        catch {
+            throw new InvalidInputError(name, value);
+        }
+    }));
+    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 })];
+        }));
+        this.metadata = metadata;
+        this.globals = metadata.globals;
+        this.chapters = realChapters;
+        this.entry = (entry && realChapters[entry]) || null;
+        this.hooks = hooks;
+        this.stylesheet = stylesheet;
+    }
+    async play(prompt, options) {
+        if (this.hooks.onStart) {
+            this.hooks.onStart(this.globals);
+        }
+        let chapter = this.entry;
+        while (chapter) {
+            let modifiedGlobals = this.globals;
+            if (chapter.hooks.onEnter) {
+                const modified = chapter.hooks.onEnter(this.globals);
+                if (modified !== undefined) {
+                    modifiedGlobals = Object.assign(modifiedGlobals, modified);
+                }
+            }
+            const renderResult = chapter.render(modifiedGlobals, options);
+            const promptResult = await prompt({ chapter, ...renderResult });
+            const { target, updates } = promptResult instanceof FormData ? parseFormData(promptResult, renderResult) : promptResult;
+            let modifiedTarget = target;
+            let modifiedUpdates = updates;
+            if (chapter.hooks.onLeave) {
+                const modified = chapter.hooks.onLeave(updates, this.globals);
+                if (modified !== undefined) {
+                    modifiedUpdates = Object.assign(updates, modified);
+                }
+            }
+            if (chapter.hooks.onNavigate) {
+                const modified = chapter.hooks.onNavigate(target, updates, this.globals);
+                if (modified !== undefined) {
+                    modifiedTarget = modified;
+                }
+            }
+            this.globals = Object.assign(this.globals, modifiedUpdates);
+            if (modifiedTarget !== null && !(modifiedTarget in this.chapters)) {
+                throw new ChapterNotFoundError(modifiedTarget);
+            }
+            chapter = modifiedTarget !== null ? this.chapters[modifiedTarget] : null;
+        }
+    }
+}

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from "./base/index.js";
+import { StoryBase, parseStoryContent } from "./base/index.js";
+export class Story extends StoryBase {
+    constructor(content) {
+        super(parseStoryContent(content));
+    }
+}

package/dist/types/base/chapter.d.ts

@@ -0,0 +1,44 @@
+import { ValueType, Value, ChapterHooks, Scope } from "./definitions.js";
+type MarkdownOptions = {};
+type HtmlOptions = {
+    tagMap?: Record<string, string>;
+};
+export type RenderOptions = ({
+    format: "markdown";
+} & MarkdownOptions) | ({
+    format: "html";
+} & HtmlOptions);
+type Fields = {
+    inputs: {
+        name: string;
+        type: ValueType;
+        value: Value;
+    }[];
+    sets: {
+        name: string;
+        type: ValueType;
+        value: Value;
+    }[];
+    navs: {
+        text: string;
+        target: string | null;
+    }[];
+};
+export type RenderResult = {
+    text: string;
+} & Fields;
+export type ChapterOptions = {
+    id: string;
+    title: string;
+    template: string;
+    hooks: ChapterHooks;
+};
+export declare class Chapter {
+    id: string;
+    title: string;
+    template: string;
+    hooks: ChapterHooks;
+    constructor({ id, title, template, hooks }: ChapterOptions);
+    render(scope: Scope, options: RenderOptions): RenderResult;
+}
+export {};

package/dist/types/base/definitions.d.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+type JsonPrimitive = number | string | boolean | null;
+type JsonArray = JsonValue[];
+type JsonObject = {
+    [key: string]: JsonValue;
+};
+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 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>>>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    globals: Record<string, string | number | boolean | JsonArray | JsonObject | null>;
+}, {
+    title?: string | undefined;
+    globals?: Record<string, any> | 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]>>>;
+}, "strip", z.ZodTypeAny, {
+    onStart?: ((args_0: Record<string, any>, ...args: unknown[]) => void | Record<string, string | number | boolean | JsonArray | JsonObject | null>) | undefined;
+}, {
+    onStart?: ((args_0: Record<string, string | number | boolean | JsonArray | JsonObject | null>, ...args: unknown[]) => void | Record<string, any>) | undefined;
+}>;
+export declare const ChapterHooksSchema: z.ZodObject<{
+    onEnter: 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]>>>;
+    onLeave: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodAny, string | number | boolean | JsonArray | JsonObject | null, any>>, 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]>>>;
+    onNavigate: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodUnion<[z.ZodString, z.ZodNull]>, z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodAny, string | number | boolean | JsonArray | JsonObject | null, any>>, z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodAny, string | number | boolean | JsonArray | JsonObject | null, any>>], z.ZodUnknown>, z.ZodUnion<[z.ZodUnion<[z.ZodString, z.ZodNull]>, z.ZodVoid]>>>;
+}, "strip", z.ZodTypeAny, {
+    onEnter?: ((args_0: Record<string, any>, ...args: unknown[]) => void | Record<string, string | number | boolean | JsonArray | JsonObject | null>) | undefined;
+    onLeave?: ((args_0: Record<string, any>, args_1: Record<string, any>, ...args: unknown[]) => void | Record<string, string | number | boolean | JsonArray | JsonObject | null>) | undefined;
+    onNavigate?: ((args_0: string | null, args_1: Record<string, any>, args_2: Record<string, any>, ...args: unknown[]) => string | void | null) | undefined;
+}, {
+    onEnter?: ((args_0: Record<string, string | number | boolean | JsonArray | JsonObject | null>, ...args: unknown[]) => void | Record<string, any>) | undefined;
+    onLeave?: ((args_0: Record<string, string | number | boolean | JsonArray | JsonObject | null>, args_1: Record<string, string | number | boolean | JsonArray | JsonObject | null>, ...args: unknown[]) => void | Record<string, any>) | undefined;
+    onNavigate?: ((args_0: string | null, args_1: Record<string, string | number | boolean | JsonArray | JsonObject | null>, args_2: Record<string, string | number | boolean | JsonArray | JsonObject | null>, ...args: unknown[]) => string | void | null) | undefined;
+}>;
+export type Value = z.infer<typeof ValueSchema>;
+export type Scope = z.infer<typeof ScopeSchema>;
+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 {};

package/dist/types/base/error.d.ts

@@ -0,0 +1,20 @@
+export declare class InvalidMetadataError extends Error {
+    content: string;
+    constructor(content: string, message?: string);
+}
+export declare class DuplicateIdError extends Error {
+    id: string;
+    constructor(id: string, message?: string);
+}
+export declare class EmptyChapterIdError extends Error {
+    constructor(message?: string);
+}
+export declare class ChapterNotFoundError extends Error {
+    target: string | null;
+    constructor(target: string | null, message?: string);
+}
+export declare class InvalidInputError extends Error {
+    name: string;
+    input: string | null;
+    constructor(name: string, input: string | null, message?: string);
+}

package/dist/types/base/index.d.ts

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

package/dist/types/base/story.d.ts

@@ -0,0 +1,32 @@
+import { StoryHooks, Scope, Metadata, ChapterHooks } from "./definitions.js";
+import { Chapter, RenderOptions, RenderResult } from "./chapter.js";
+export type StoryPrompt = (props: {
+    chapter: Chapter;
+} & RenderResult) => Promise<{
+    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;
+    chapters: Record<string, Chapter>;
+    entry: Chapter | null;
+    hooks: StoryHooks;
+    stylesheet: string;
+    constructor({ metadata, chapters, entry, hooks, stylesheet }: StoryBody);
+    play(prompt: StoryPrompt, options: RenderOptions): Promise<void>;
+}
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./base/index.js";
+import { StoryBase } from "./base/index.js";
+export declare class Story extends StoryBase {
+    constructor(content: string);
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@elvishscout/mdstory",
+  "version": "0.1.0",
+  "description": "An interactive story format based on Markdown and Handlebars with JavaScript support",
+  "main": "./dist/index.js",
+  "type": "module",
+  "files": [
+    "./dist",
+    "./types"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node ./test/index.test.js"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/markdown-it": "^14.1.2",
+    "@types/markdown-it-attrs": "^4.1.3",
+    "@types/node": "^22.14.1",
+    "inquirer": "^12.6.0",
+    "markdown-it-terminal": "^0.4.0",
+    "typescript": "~5.7.2"
+  },
+  "dependencies": {
+    "handlebars": "^4.7.8",
+    "js-yaml": "^4.1.0",
+    "markdown-it": "^14.1.0",
+    "markdown-it-attrs": "^4.3.1",
+    "markdown-it-front-matter": "^0.2.4",
+    "zod": "^3.24.3"
+  },
+  "types": "./types",
+  "keywords": [
+    "markdown",
+    "handlebars"
+  ],
+  "author": "Jiakai Jiang",
+  "license": "ISC"
+}

package/types/base/chapter.d.ts

@@ -0,0 +1,44 @@
+import { ValueType, Value, ChapterHooks, Scope } from "./definitions.js";
+type MarkdownOptions = {};
+type HtmlOptions = {
+    tagMap?: Record<string, string>;
+};
+export type RenderOptions = ({
+    format: "markdown";
+} & MarkdownOptions) | ({
+    format: "html";
+} & HtmlOptions);
+type Fields = {
+    inputs: {
+        name: string;
+        type: ValueType;
+        value: Value;
+    }[];
+    sets: {
+        name: string;
+        type: ValueType;
+        value: Value;
+    }[];
+    navs: {
+        text: string;
+        target: string | null;
+    }[];
+};
+export type RenderResult = {
+    text: string;
+} & Fields;
+export type ChapterOptions = {
+    id: string;
+    title: string;
+    template: string;
+    hooks: ChapterHooks;
+};
+export declare class Chapter {
+    id: string;
+    title: string;
+    template: string;
+    hooks: ChapterHooks;
+    constructor({ id, title, template, hooks }: ChapterOptions);
+    render(scope: Scope, options: RenderOptions): RenderResult;
+}
+export {};

package/types/base/definitions.d.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+type JsonPrimitive = number | string | boolean | null;
+type JsonArray = JsonValue[];
+type JsonObject = {
+    [key: string]: JsonValue;
+};
+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 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>>>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    globals: Record<string, string | number | boolean | JsonArray | JsonObject | null>;
+}, {
+    title?: string | undefined;
+    globals?: Record<string, any> | 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]>>>;
+}, "strip", z.ZodTypeAny, {
+    onStart?: ((args_0: Record<string, any>, ...args: unknown[]) => void | Record<string, string | number | boolean | JsonArray | JsonObject | null>) | undefined;
+}, {
+    onStart?: ((args_0: Record<string, string | number | boolean | JsonArray | JsonObject | null>, ...args: unknown[]) => void | Record<string, any>) | undefined;
+}>;
+export declare const ChapterHooksSchema: z.ZodObject<{
+    onEnter: 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]>>>;
+    onLeave: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodAny, string | number | boolean | JsonArray | JsonObject | null, any>>, 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]>>>;
+    onNavigate: z.ZodOptional<z.ZodFunction<z.ZodTuple<[z.ZodUnion<[z.ZodString, z.ZodNull]>, z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodAny, string | number | boolean | JsonArray | JsonObject | null, any>>, z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodAny, string | number | boolean | JsonArray | JsonObject | null, any>>], z.ZodUnknown>, z.ZodUnion<[z.ZodUnion<[z.ZodString, z.ZodNull]>, z.ZodVoid]>>>;
+}, "strip", z.ZodTypeAny, {
+    onEnter?: ((args_0: Record<string, any>, ...args: unknown[]) => void | Record<string, string | number | boolean | JsonArray | JsonObject | null>) | undefined;
+    onLeave?: ((args_0: Record<string, any>, args_1: Record<string, any>, ...args: unknown[]) => void | Record<string, string | number | boolean | JsonArray | JsonObject | null>) | undefined;
+    onNavigate?: ((args_0: string | null, args_1: Record<string, any>, args_2: Record<string, any>, ...args: unknown[]) => string | void | null) | undefined;
+}, {
+    onEnter?: ((args_0: Record<string, string | number | boolean | JsonArray | JsonObject | null>, ...args: unknown[]) => void | Record<string, any>) | undefined;
+    onLeave?: ((args_0: Record<string, string | number | boolean | JsonArray | JsonObject | null>, args_1: Record<string, string | number | boolean | JsonArray | JsonObject | null>, ...args: unknown[]) => void | Record<string, any>) | undefined;
+    onNavigate?: ((args_0: string | null, args_1: Record<string, string | number | boolean | JsonArray | JsonObject | null>, args_2: Record<string, string | number | boolean | JsonArray | JsonObject | null>, ...args: unknown[]) => string | void | null) | undefined;
+}>;
+export type Value = z.infer<typeof ValueSchema>;
+export type Scope = z.infer<typeof ScopeSchema>;
+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 {};

package/types/base/error.d.ts

@@ -0,0 +1,20 @@
+export declare class InvalidMetadataError extends Error {
+    content: string;
+    constructor(content: string, message?: string);
+}
+export declare class DuplicateIdError extends Error {
+    id: string;
+    constructor(id: string, message?: string);
+}
+export declare class EmptyChapterIdError extends Error {
+    constructor(message?: string);
+}
+export declare class ChapterNotFoundError extends Error {
+    target: string | null;
+    constructor(target: string | null, message?: string);
+}
+export declare class InvalidInputError extends Error {
+    name: string;
+    input: string | null;
+    constructor(name: string, input: string | null, message?: string);
+}

package/types/base/index.d.ts

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

package/types/base/story.d.ts

@@ -0,0 +1,32 @@
+import { StoryHooks, Scope, Metadata, ChapterHooks } from "./definitions.js";
+import { Chapter, RenderOptions, RenderResult } from "./chapter.js";
+export type StoryPrompt = (props: {
+    chapter: Chapter;
+} & RenderResult) => Promise<{
+    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;
+    chapters: Record<string, Chapter>;
+    entry: Chapter | null;
+    hooks: StoryHooks;
+    stylesheet: string;
+    constructor({ metadata, chapters, entry, hooks, stylesheet }: StoryBody);
+    play(prompt: StoryPrompt, options: RenderOptions): Promise<void>;
+}
+export {};

package/types/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./base/index.js";
+import { StoryBase } from "./base/index.js";
+export declare class Story extends StoryBase {
+    constructor(content: string);
+}