@elvishscout/mdstory 0.1.3 → 0.2.0

package/package.json

@@ -1,34 +1,54 @@
 {
+  "workspaces": [
+    "html-template"
+  ],
   "name": "@elvishscout/mdstory",
-  "repository": "https://github.com/ElvishScout/mdstory.git",
-  "version": "0.1.3",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ElvishScout/mdstory.git"
+  },
+  "version": "0.2.0",
   "description": "An interactive fiction scripting format based on Markdown and Handlebars.",
   "main": "./dist/index.js",
+  "sideEffects": false,
   "type": "module",
   "files": [
     "./dist",
-    "./types"
+    "./types",
+    "./html-template/dist"
   ],
+  "bin": {
+    "mdstory": "dist/cli/index.js"
+  },
   "scripts": {
-    "build": "tsc",
-    "test": "tsx ./test/index.test.ts"
+    "prebuild": "shx rm -rf \"dist/*\" \"dist/.*\"",
+    "build": "tsc -b",
+    "build:template": "cd html-template && npm run build",
+    "build:all": "npm run build && npm run build:template",
+    "cli": "node ./dist/cli/index.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",
+    "@types/node": "^22.20.0",
+    "shx": "^0.4.0",
     "tsx": "^4.19.3",
-    "typescript": "~5.7.2"
+    "typescript": "~5.7.2",
+    "words-count": "^2.0.2"
   },
   "dependencies": {
+    "commander": "^15.0.0",
     "handlebars": "^4.7.8",
+    "inquirer": "^12.6.0",
     "js-yaml": "^4.1.0",
     "markdown-it": "^14.1.0",
     "markdown-it-attrs": "^4.3.1",
     "markdown-it-front-matter": "^0.2.4",
+    "markdown-it-mark": "^4.0.0",
+    "markdown-it-terminal": "^0.4.0",
+    "nanoid": "^5.1.16",
+    "open": "^10.2.0",
     "zod": "^3.24.3"
   },
   "types": "./types",
@@ -38,4 +58,4 @@
   ],
   "author": "Jiakai Jiang",
   "license": "ISC"
-}
+}

package/types/cli/commands/build.d.ts

@@ -0,0 +1,6 @@
+export interface BuildOptions {
+    output?: string;
+    open?: boolean;
+    debug?: boolean;
+}
+export declare function buildCommand(storyPath: string, options: BuildOptions): Promise<void>;

package/types/cli/commands/play.d.ts

@@ -0,0 +1,4 @@
+export interface PlayOptions {
+    debug?: boolean;
+}
+export declare function playCommand(storyPath: string, options: PlayOptions): Promise<void>;

package/types/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/types/cli/markdown.d.ts

@@ -0,0 +1,2 @@
+import MarkdownIt from "markdown-it";
+export declare function createMarkdownRenderer(): MarkdownIt;

package/types/cli/prompt.d.ts

@@ -0,0 +1,3 @@
+import type MarkdownIt from "markdown-it";
+import type { StoryPrompt } from "../index.js";
+export declare function createPrompt(md: MarkdownIt): StoryPrompt;

package/types/core/chapter.d.ts

@@ -0,0 +1,19 @@
+import { Scene } from "./scene.js";
+import type { RenderOptions, RenderResult } from "./render.js";
+import type { ChapterHooks, Scope, Asset, ChapterInit, DEFAULT_CHAPTER } from "./definitions.js";
+import type { ParsedChapter } from "./parser.js";
+/** A chapter grouping scenes with shared hooks and local variables. */
+export declare class Chapter {
+    id: string | typeof DEFAULT_CHAPTER;
+    title: string;
+    template: string;
+    hooks: ChapterHooks;
+    locals: Scope;
+    scenes: Scene[];
+    constructor({ id, title, template, hooks, locals, scenes }: ChapterInit);
+    static fromParsed(chapter: ParsedChapter): Promise<Chapter>;
+    /** Renders the chapter template with the given scope and render options. */
+    render(scope: Scope, assets: Record<string, Asset>, options: RenderOptions): RenderResult;
+    /** Get scene by scene id */
+    getScene(id: string): Scene | null;
+}

package/types/core/definitions.d.ts

@@ -0,0 +1,83 @@
+import type { Chapter } from "./chapter.js";
+import type { Scene } from "./scene.js";
+type JsonPrimitive = number | string | boolean | null;
+type JsonArray = JsonValue[];
+type JsonObject = {
+    [key: string]: JsonValue;
+};
+type JsonValue = JsonPrimitive | JsonArray | JsonObject;
+type HookResult<T = void> = T | Promise<T>;
+export type { JsonValue };
+/** All JSON-compatible values. */
+export type Variable = JsonValue;
+/** An object of variable values by their names. */
+export type Scope = JsonObject;
+/** A referenceable resource file. */
+export type Asset = {
+    url: string;
+    mime?: string;
+    alt?: string;
+};
+/** Story metadata. */
+export type Metadata = {
+    title?: string;
+    author?: string;
+    email?: string;
+    globals?: Scope;
+    assets?: Record<string, Asset>;
+};
+export type HookContext = {
+    globals: Scope;
+    locals: Scope;
+};
+export type StoryHookContext = Pick<HookContext, "globals">;
+export type LeaveHookContext = HookContext & {
+    target: string | null;
+};
+/** Type indicator for input fields. */
+export type InputType = "string" | "number" | "boolean";
+/** Story-level lifecycle hooks. */
+export type StoryHooks = {
+    globals?: () => HookResult<Scope | undefined>;
+    onStart?: (context: StoryHookContext) => HookResult;
+};
+/** Chapter-level lifecycle hooks. */
+export type ChapterHooks = {
+    locals?: (context: StoryHookContext) => HookResult<Scope | undefined>;
+    onEnter?: (context: HookContext) => HookResult;
+    onLeave?: (context: LeaveHookContext) => HookResult;
+};
+/** Scene-level lifecycle hooks. */
+export type SceneHooks = {
+    view?: (context: HookContext) => HookResult<Scope | undefined>;
+    onEnter?: (context: HookContext) => HookResult;
+    onLeave?: (context: LeaveHookContext) => HookResult;
+};
+/** Symbol key for the implicit default chapter holding orphan scenes. */
+export declare const DEFAULT_CHAPTER: unique symbol;
+/** Structured representation of a scene's content. */
+export type SceneInit = {
+    id: string;
+    title?: string;
+    template: string;
+    hooks?: SceneHooks;
+};
+/** Structured representation of a chapter. */
+export type ChapterInit = {
+    id: string | typeof DEFAULT_CHAPTER;
+    title?: string;
+    template?: string;
+    hooks?: ChapterHooks;
+    locals?: Scope;
+    scenes: Scene[];
+};
+/** Structured representation of the full story. */
+export type StoryInit = {
+    metadata?: Metadata;
+    title?: string;
+    template?: string;
+    chapters: Chapter[];
+    stylesheet?: string;
+    hooks?: StoryHooks;
+    debug?: boolean;
+};

package/types/{base → core}/index.d.ts

@@ -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/types/core/parser.d.ts

@@ -0,0 +1,39 @@
+import { DEFAULT_CHAPTER } from "./definitions.js";
+import type { Metadata } from "./definitions.js";
+export type IncludeResolver = (path: string) => string | Promise<string>;
+export type ParseStoryOptions = {
+    base: string;
+    resolveInclude: IncludeResolver;
+};
+export type ParsedScene = {
+    id: string;
+    title: string;
+    template: string;
+    script: string;
+};
+export type ParsedChapter = {
+    id: string | typeof DEFAULT_CHAPTER;
+    title: string;
+    template: string;
+    script: string;
+    scenes: ParsedScene[];
+};
+export type ParsedStory = {
+    metadata: Metadata;
+    title: string;
+    template: string;
+    chapters: ParsedChapter[];
+    stylesheet: string;
+    script: string;
+    debug?: boolean;
+};
+export declare function resolveParseOptions(options?: Partial<ParseStoryOptions>): Promise<ParseStoryOptions>;
+/**
+ * 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 declare function parseStorySource(source: string, options?: Partial<ParseStoryOptions>): Promise<ParsedStory>;

package/types/core/render.d.ts

@@ -0,0 +1,46 @@
+import type { InputType, Variable, Scope, Asset } from "./definitions.js";
+/** Custom renderer for generating output in different formats. */
+export interface Renderer {
+    /** Whether to convert Markdown to HTML */
+    html?: boolean;
+    /** Render input area */
+    input?(options: {
+        name: string;
+        type: InputType;
+        value: string;
+    }): string;
+    /** Render navigation area */
+    nav?(options: {
+        target: string | null;
+        children: string;
+    }): string;
+    /** Render line breaks */
+    linebreak?(options: {
+        n?: number;
+    }): string;
+}
+/** Rendering options. */
+export type RenderOptions = {
+    renderer: "markdown" | "html" | Renderer;
+};
+/** The rendering result containing rendered text and extracted fields. */
+export type RenderResult = {
+    text: string;
+} & Fields;
+type Fields = {
+    inputs: {
+        name: string;
+        type: InputType;
+        value: Variable;
+    }[];
+    navs: {
+        text: string;
+        target: string | null;
+    }[];
+};
+/**
+ * Compiles a Handlebars template with built-in helpers, optionally renders
+ * through MarkdownIt, and returns the rendered text with extracted fields.
+ */
+export declare function renderTemplate(template: string, scope: Scope, assets: Record<string, Asset>, options: RenderOptions): RenderResult;
+export {};

package/types/core/scene.d.ts

@@ -0,0 +1,20 @@
+import type { SceneHooks, Scope, Asset, SceneInit, DEFAULT_CHAPTER } from "./definitions.js";
+import type { ParsedScene } from "./parser.js";
+import type { RenderOptions, RenderResult } from "./render.js";
+export type { RenderOptions, RenderResult };
+/** Defines a scene with a Handlebars template and lifecycle hooks. */
+export declare class Scene {
+    id: string;
+    title: string;
+    template: string;
+    hooks: SceneHooks;
+    constructor({ id, title, template, hooks }: SceneInit);
+    static fromParsed(scene: ParsedScene, chapterId: string | typeof DEFAULT_CHAPTER): Promise<Scene>;
+    /**
+     * 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: Scope, assets: Record<string, Asset>, options: RenderOptions): RenderResult;
+}

package/types/core/schema.d.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import type { JsonValue, StoryHooks, ChapterHooks, SceneHooks } from "./definitions.js";
+export declare const VariableSchema: z.ZodEffects<z.ZodAny, string | number | boolean | JsonValue[] | {
+    [key: string]: JsonValue;
+} | null, any>;
+export declare const ScopeSchema: z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodAny, string | number | boolean | JsonValue[] | {
+    [key: string]: JsonValue;
+} | null, any>>;
+export declare const AssetSchema: z.ZodUnion<[z.ZodEffects<z.ZodString, {
+    url: string;
+    mime?: string | undefined;
+    alt?: string | undefined;
+}, string>, z.ZodObject<{
+    url: z.ZodString;
+    mime: z.ZodOptional<z.ZodString>;
+    alt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    mime?: string | undefined;
+    alt?: string | undefined;
+}, {
+    url: string;
+    mime?: string | undefined;
+    alt?: string | undefined;
+}>]>;
+export declare const AssetsSchema: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodEffects<z.ZodString, {
+    url: string;
+    mime?: string | undefined;
+    alt?: string | undefined;
+}, string>, z.ZodObject<{
+    url: z.ZodString;
+    mime: z.ZodOptional<z.ZodString>;
+    alt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    mime?: string | undefined;
+    alt?: string | undefined;
+}, {
+    url: string;
+    mime?: string | undefined;
+    alt?: string | undefined;
+}>]>>;
+export declare const MetadataSchema: z.ZodObject<{
+    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 | JsonValue[] | {
+        [key: string]: JsonValue;
+    } | null, any>>>;
+    assets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodEffects<z.ZodString, {
+        url: string;
+        mime?: string | undefined;
+        alt?: string | undefined;
+    }, string>, z.ZodObject<{
+        url: z.ZodString;
+        mime: z.ZodOptional<z.ZodString>;
+        alt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        mime?: string | undefined;
+        alt?: string | undefined;
+    }, {
+        url: string;
+        mime?: string | undefined;
+        alt?: string | undefined;
+    }>]>>>;
+}, "strip", z.ZodTypeAny, {
+    title?: string | undefined;
+    author?: string | undefined;
+    email?: string | undefined;
+    globals?: Record<string, string | number | boolean | JsonValue[] | {
+        [key: string]: JsonValue;
+    } | null> | undefined;
+    assets?: Record<string, {
+        url: string;
+        mime?: string | undefined;
+        alt?: 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;
+        alt?: string | undefined;
+    }> | undefined;
+}>;
+export declare const StoryHooksSchema: z.ZodType<StoryHooks>;
+export declare const ChapterHooksSchema: z.ZodType<ChapterHooks>;
+export declare const SceneHooksSchema: z.ZodType<SceneHooks>;

package/types/core/story.d.ts

@@ -0,0 +1,54 @@
+import type { StoryInit, StoryHooks, Scope, Metadata, Asset } from "./definitions.js";
+import { Scene } from "./scene.js";
+import { Chapter } from "./chapter.js";
+import type { RenderOptions, RenderResult } from "./render.js";
+import type { ParsedStory, ParseStoryOptions } from "./parser.js";
+/**
+ * Prompt function for handling user input during story playback.
+ * Receives the current scene and render result, returns navigation target and submitted input values.
+ */
+export type StoryPrompt = (props: {
+    scene: Scene;
+} & RenderResult) => Promise<{
+    target: string | null;
+    inputs: Scope;
+} | FormData>;
+export type PlayOptions = RenderOptions & {
+    debug?: boolean;
+};
+/**
+ * Story runtime containing core playback logic.
+ * Construct via `fromSource(source)`, `fromPath(path)`,
+ * `fromParsed(parsedStory)`, or manually with a parsed StoryInit.
+ */
+export declare class Story {
+    metadata: Metadata;
+    title: string;
+    template: string;
+    globals: Scope;
+    assets: Record<string, Asset>;
+    hooks: StoryHooks;
+    stylesheet: string;
+    chapters: Chapter[];
+    debug: boolean;
+    /** @internal */ _storyTitleShown: boolean;
+    constructor(init: StoryInit);
+    /** Get chapter by chapter id */
+    getChapter(id: string): Chapter | null;
+    resolveTarget(target: string, currentChapter: Chapter): {
+        chapter: Chapter;
+        scene: Scene;
+    } | null;
+    /** Renders the story template with the given scope and render options. */
+    render(scope: Scope, assets: Record<string, Asset>, options: RenderOptions): RenderResult;
+    private enterChapter;
+    private leaveChapter;
+    /** Starts playing the story, looping through chapters and scenes until navigation ends. */
+    play(prompt: StoryPrompt, options: PlayOptions): Promise<void>;
+}
+/** Creates a Story instance from a parsed story object. */
+export declare function fromParsed(story: ParsedStory): Promise<Story>;
+/** Parses a story source string and creates a Story instance. */
+export declare function fromSource(source: string, options?: Partial<ParseStoryOptions>): Promise<Story>;
+/** Loads a story from a path or URL and resolves includes relative to each containing resource. */
+export declare function fromPath(path: string, options?: Partial<ParseStoryOptions>): Promise<Story>;

package/types/core/utils.d.ts

@@ -0,0 +1,7 @@
+import { DEFAULT_CHAPTER } from "./definitions.js";
+export declare function getScriptModuleId(chapterId?: string | typeof DEFAULT_CHAPTER, sceneId?: string): string;
+export declare function importScriptModule(script: string, id?: string): Promise<any>;
+export declare function parseScript<T>(script: string, schema: Zod.ZodType<T>, id: string): Promise<T>;
+export declare function normalizePath(path: string, base?: string): Promise<any>;
+export declare function loadSource(normalizedPath: string): Promise<string>;
+export declare function escapeHtml(text: string): string;

package/types/index.d.ts

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

package/types/tools/count-words.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/base/definitions.js

@@ -1,29 +0,0 @@
-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().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
-    .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

@@ -1,30 +0,0 @@
-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/parser.js

@@ -1,86 +0,0 @@
-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,
-    };
-};