questmark 0.0.36 → 0.1.0

package/docs/how-to/play-a-document.md

@@ -0,0 +1,57 @@
+# How to play a Questmark document
+
+This guide shows you how to run a Questmark document interactively.
+
+## From the project directory
+
+After cloning the repository and running `npm install`, play any local
+document with:
+
+```bash
+npm start -- --input path/to/document.md
+```
+
+The document must have one of the extensions `.md`, `.qmd`, `.md.html`, or
+`.qmd.html` (or be a compiled `.json` — see
+[compile a document to bytecode](compile-to-bytecode.md)).
+
+## From the published CLI
+
+If you don't have a checkout of the repository, the CLI is published on npm:
+
+```bash
+npx questmark --input path/to/document.md
+```
+
+## From a URL
+
+The input path can be an `http://` or `https://` URL, so you can play a
+document that's hosted online:
+
+```bash
+npx questmark --input https://ghcdn.rawgit.org/jorisvddonk/questmark/master/examples/self-describing.md
+```
+
+## During a play session
+
+- The interpreter prints the current state's text, then shows a menu of the
+  options currently available.
+- Use the arrow keys to navigate and `Enter` to choose.
+- Text that appears *after* an option line in the source is only shown once
+  that option has been chosen.
+- Options can be hidden by preconditions, or appear only once when marked
+  `@once` — if an option is missing from the menu, that's the story telling
+  you it isn't available.
+
+## Troubleshooting
+
+- **"Missing input!"** — you didn't pass `--input`. Pass the path or URL of a
+  document.
+- **The menu loops forever** — you chose an option that has neither a link nor
+  an `exit`/`goto` effect. With the default `loopback_to_options` behaviour the
+  interpreter returns to the menu. Change the behaviour in the document header
+  (see the [language reference](../reference/language.md)), or give the option
+  a link or an effect.
+- **The interpreter quits immediately** — the document uses the `exit`
+  `no_link_behaviour`, or the state you entered runs an `exit` instruction.
+  This is often intended.

package/docs/how-to/use-the-library.md

@@ -0,0 +1,98 @@
+# How to embed Questmark in your own application
+
+The library exposes two pieces: `parseMarkdown`, which compiles a Questmark
+document into a Tzo VM state, and `QuestVM`, which interprets that state. This
+guide wires them together in a small Node.js application.
+
+## Install
+
+```bash
+npm install questmark
+```
+
+## Compile and run a document
+
+```js
+const { parseMarkdown, QuestVM } = require("questmark");
+const fs = require("fs");
+
+const markdown = fs.readFileSync("conversation.md", "utf8");
+const { qvmState } = parseMarkdown(markdown);
+
+const vm = new QuestVM(
+  // emitFunction: called every time the document emits text.
+  (body) => process.stdout.write(String(body)),
+
+  // getResponseFunction: called whenever the document asks the player
+  // to choose. Return a Promise of the chosen option's id.
+  async (choices) => {
+    choices.forEach((c) => console.log(`${c.id}: ${c.title}`));
+    const id = Number(await askUser("Your choice: "));
+    return id;
+  },
+
+  // additionalFunctions: optional extra Tzo opcodes.
+  {}
+);
+
+vm.loadVMState(qvmState);
+vm.run();
+```
+
+## What the callbacks do
+
+- **emitFunction** — invoked by the `emit` opcode with the text (or number) the
+  document wants to show. It can be called several times while rendering a
+  single state (for example `` You have `"cookies" getContext emit` cookies! ``).
+  Concatenate the calls to reconstruct the full text.
+
+- **getResponseFunction** — invoked by the `getResponse` opcode with the list
+  of options currently available, as `{ title, id }` objects. The ids are
+  positional (0, 1, 2, ...). Return a `Promise` resolving to the chosen id;
+  the VM resumes execution from that option's effect.
+
+- **additionalFunctions** — a map of extra opcode names to functions. Opcode
+  names beginning with `_` are ignored at compile time, so you can use
+  underscore-prefixed calls in documents as hooks for your own logic.
+
+## Running in a browser
+
+The webpack build produces a browser bundle at `dist/browser/bundle.js`. Load
+it with a `<script>` tag and use the global `Questmark` object the same way:
+
+```html
+<script src="questmark/dist/browser/bundle.js"></script>
+<script>
+  const { parseMarkdown, QuestVM } = Questmark;
+  // ...same API as above, wiring emitFunction to the DOM instead of stdout.
+</script>
+```
+
+## Handling errors
+
+`QuestVM` extends `EventEmitter`. Runtime errors in the interpreter are emitted
+on the `eventBus` under the `error` event:
+
+```js
+vm.eventBus.on("error", (err) => {
+  console.error("Interpreter error:", err);
+  vm.quit();
+});
+```
+
+The `eventBus` also emits `emit` and `response` events for every text emission
+and option registration, which can be useful for logging or debug UIs.
+
+## A note on preconditions
+
+Context lookups with `getContext` throw if the key is not present, so always
+initialize every variable you plan to read in the document's
+`initial-context` (see the [language reference](../reference/language.md)).
+
+## Further reading
+
+- [API reference](../reference/api.md) — exact signatures and types.
+- [Tutorial: write your first conversation](../tutorials/first-conversation.md) —
+  the basics of the language.
+- The repository's `test/` directory contains more complete examples of
+  driving a `QuestVM` programmatically.

package/docs/index.md

@@ -0,0 +1,61 @@
+---
+layout: home
+
+hero:
+  name: Questmark
+  text: Dialogue trees and hypertext fiction in Markdown
+  tagline: A language, compiler, interpreter, and TypeScript library for conversation trees and interactive fiction — built on the Markdown everyone already knows.
+  actions:
+    - theme: brand
+      text: Start the tutorial
+      link: /tutorials/first-conversation
+    - theme: alt
+      text: Why Questmark?
+      link: /explanation/why-questmark
+
+features:
+  - icon: 📝
+    title: Markdown-native
+    details: Every properly-structured Markdown document with headers and links is already a Questmark document. Prose stays readable; behaviour is added with small backticked code snippets.
+  - icon: 🧭
+    title: Conversation trees
+    details: States and options model dialogue graphs — like Star Control 2 — and quests, hypertext fiction, text adventures, and visual novels — like Space Rangers 2.
+  - icon: 🧠
+    title: Context and side-effects
+    details: A context bag tracks what the player has done, gating options with preconditions and driving branching narrative and in-world side effects.
+  - icon: ⚙️
+    title: Compiles to Tzo bytecode
+    details: Documents compile to a portable Tzo VMState that can be stored, shipped, and interpreted in a game, a CLI, or a browser.
+---
+
+## Documentation
+
+Questmark's docs follow the [Diátaxis](https://diataxis.fr/) framework, which
+splits documentation into four complementary modes of use:
+
+| Mode | Audience | Purpose | Start here |
+| --- | --- | --- | --- |
+| [Tutorials](tutorials/first-conversation) | Learners | Learning-oriented lessons that take you by the hand | [Your first conversation](tutorials/first-conversation) |
+| [How-to guides](how-to/play-a-document) | Doers | Goal-oriented steps for solving real problems | [Play a document](how-to/play-a-document) |
+| [Reference](reference/language) | Everyone | Information-oriented descriptions of the machinery | [Language reference](reference/language) |
+| [Explanation](explanation/why-questmark) | Everyone | Understanding-oriented background and context | [Why Questmark?](explanation/why-questmark) |
+
+## Quick orientation
+
+- **New to Questmark?** Start with the [tutorial](tutorials/first-conversation).
+  It takes about ten minutes and gets you writing and playing your first
+  conversation.
+- **Trying to get something done?** The [how-to guides](how-to/play-a-document)
+  show you how to play a document, compile one to bytecode, and embed Questmark
+  in your own app.
+- **Need a fact?** The [reference](reference/language) pages describe the
+  language, the CLI, and the library API precisely and completely.
+- **Want to understand the design?** The [explanation](explanation/why-questmark)
+  pages cover why Questmark exists and how it works under the hood.
+
+## Related projects
+
+- [Tzo](https://github.com/jorisvddonk/tzo) — the stack-machine bytecode and VM
+  that Questmark compiles to.
+- [questmark-webrenderer](https://github.com/jorisvddonk/questmark-webrenderer) —
+  render and play Questmark documents in the browser.

package/docs/reference/api.md

@@ -0,0 +1,135 @@
+# Questmark API reference
+
+The library entry point (`src/index.ts`, built to `dist/node/`) exports the
+compiler and the interpreter. All of the API below is available from the
+package entry point (`import ... from "questmark"` / `require("questmark")`).
+
+## `parseMarkdown(fileContents: string)`
+
+Compiles a Questmark document into a Tzo VM state.
+
+**Returns** `{ parsedMDFile, qvmState }`
+
+- `parsedMDFile` — the parsed document as a unist tree, with position
+  information removed.
+- `qvmState` — a `TzoVMState` (see below) ready to load into a `QuestVM`.
+
+**Throws** on malformed option headers (for example an unknown
+`no_link_behaviour`) or Tzo tokenizer errors.
+
+## `QuestVM`
+
+`class QuestVM extends VM` — an interpreter for compiled Questmark documents.
+It extends Tzo's `VM` and adds the `emit`, `response`, and `getResponse`
+opcodes that implement text output and choices.
+
+### Constructor
+
+```ts
+new QuestVM(
+  emitFunction: (body: string | number) => void,
+  getResponseFunction: (choices: Choice[]) => Promise<number>,
+  additionalFunctions?: Functions
+)
+```
+
+- `emitFunction` — called by the `emit` opcode for each piece of text output.
+- `getResponseFunction` — called by the `getResponse` opcode whenever the
+  document asks the player to choose. Receives the currently available options
+  and must return a `Promise` resolving to the chosen option's `id`.
+- `additionalFunctions` — a map of extra Tzo opcode names to functions, merged
+  into the function table.
+
+### Events
+
+`eventBus` is an `EventEmitter` with these events:
+
+| Event | Payload | When |
+| --- | --- | --- |
+| `emit` | `string \| number` | Every text emission. |
+| `response` | `{ response, pc }` | Every option registration. |
+| `error` | `Error` | Runtime errors in the response flow. |
+
+### Inherited methods (from Tzo `VM`)
+
+| Method | Description |
+| --- | --- |
+| `loadVMState(tzoVMState)` | Load a compiled VM state and prepare it for execution. |
+| `run()` | Execute the program until the VM exits or suspends. |
+| `quit()` | Mark the VM as exited. |
+| `suspend()` | Pause execution (the `pause` opcode / `getResponse`). |
+| `tick()` | Execute a single instruction. |
+
+### Properties
+
+`stack`, `context`, `programList`, `labelMap`, `programCounter`, `exit`,
+`pause` — the interpreter state.
+
+## `Choice`
+
+```ts
+interface Choice {
+  title: string;
+  id: number;
+}
+```
+
+An option offered to the player. `id` is the option's positional index within
+the current state's choice list.
+
+## `NoLinkBehaviour`
+
+```ts
+enum NoLinkBehaviour {
+  EXIT = 0,
+  LOOPBACK_TO_OPTIONS = 1
+}
+```
+
+Behaviour when a chosen option has no link and no effect. Exported for host
+applications; documents configure this via the header flag
+`options.no_link_behaviour`.
+
+## `TzoVMState`
+
+The compiled representation produced by `parseMarkdown` and consumed by
+`loadVMState`:
+
+```ts
+interface TzoVMState {
+  stack: any[];
+  context: { [key: string]: string | number };
+  programList: Instruction[];
+  labelMap: { [label: string]: number };
+  programCounter: number;
+  exit: boolean;
+  pause: boolean;
+}
+```
+
+## `Tokenizer`
+
+Re-exported from Tzo. Parses a string of Tzo source code into an array of
+instructions:
+
+```ts
+new Tokenizer().parse("1 2 +") // -> [push-number 1, push-number 2, invoke +]
+```
+
+## Full usage example
+
+```js
+const { parseMarkdown, QuestVM } = require("questmark");
+const { qvmState } = parseMarkdown(md);
+
+const vm = new QuestVM(
+  (text) => console.log(text),
+  async (choices) => {
+    const index = await pickFrom(choices);
+    return choices[index].id;
+  },
+  {}
+);
+vm.loadVMState(qvmState);
+vm.run();
+```

package/docs/reference/cli.md

@@ -0,0 +1,66 @@
+# Questmark CLI reference
+
+The Questmark command line interface compiles and interprets Questmark
+documents.
+
+## Usage
+
+```
+questmark [options]
+```
+
+Run it from a checkout with `npm start -- [options]`, or from the published
+package with `npx questmark [options]`.
+
+## Options
+
+| Option | Description |
+| --- | --- |
+| `-V, --version` | Print the version number. |
+| `-c, --clear` | Clear the console on each state. *(Declared but not yet implemented.)* |
+| `--input <path>` | Load a source `.md`, `.qmd`, `.qmd.html`, `.md.html`, or `.json` file. `path` can be a local filesystem path or an `http(s)://` URL. |
+| `--output <path>` | Emit the compiled VMState as JSON to `path`. |
+| `--no-run` | Do not interpret the input; only parse and (optionally) emit output. |
+| `-h, --help` | Display help. |
+
+`--input` is required. Without it the CLI prints `Missing input!` and exits
+with status 1.
+
+## Examples
+
+Play a local document:
+
+```bash
+questmark --input examples/space_alien.md
+```
+
+Compile a document to bytecode without running it:
+
+```bash
+questmark --input examples/space_alien.md --output vmstate.json --no-run
+```
+
+Play a compiled document:
+
+```bash
+questmark --input vmstate.json
+```
+
+Play a document hosted online:
+
+```bash
+questmark --input https://example.com/document.md
+```
+
+## Exit codes
+
+- `0` — success.
+- `1` — missing `--input`, or a runtime/interpretation error.
+
+## Behaviour
+
+- `.json` inputs are treated as pre-compiled VM states and interpreted directly.
+- `.md`, `.qmd`, `.md.html`, and `.qmd.html` inputs are compiled with
+  `parseMarkdown` before interpretation.
+- Any other extension is an error.
+- Inputs beginning with `http://` or `https://` are fetched before processing.

package/docs/reference/language.md

@@ -0,0 +1,213 @@
+# Questmark language reference
+
+Questmark is a dialect of Markdown for dialogue trees and interactive fiction.
+A document is a series of `#`-headed sections called **states**, connected by
+links and code. The compiler turns the document into Tzo bytecode, which an
+interpreter such as `QuestVM` executes.
+
+## Document structure
+
+```markdown
+# QUESTMARK-OPTIONS-HEADER
+
+    { "questmark-spec": "1.0", "initial-state": "start" }
+
+# start
+
+Some text.
+
+* An option
+* Another option
+```
+
+- The `QUESTMARK-OPTIONS-HEADER` section is optional. When present, its
+  indented code block must contain valid JSON (see below).
+- Every other `# heading` defines a state.
+- Text before the first list item is the state's text.
+- List items are the state's **options**.
+
+## Options header
+
+The `QUESTMARK-OPTIONS-HEADER` section configures the document. Its fields:
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `questmark-spec` | string | Spec version. Currently `"1.0"`. |
+| `initial-state` | string | Name of the state to start in. |
+| `initial-context` | object | Initial values for the context bag. |
+| `options` | object | Interpreter behaviour flags, below. |
+
+### `options` flags
+
+| Flag | Values | Default | Meaning |
+| --- | --- | --- | --- |
+| `no_link_behaviour` | `"loopback_to_options"`, `"exit"` | `"loopback_to_options"` | What happens when a chosen option has neither a link nor an `exit`/`goto` effect. |
+| `whitespace` | `"retain"` | normal | Retain original source whitespace instead of the parsed text. |
+| `emit_on` | `"end_of_line"` | `"classic"` | Only emit text when a line ends, instead of on every text node. |
+| `strip_leading_newlines` | `true` | `false` | Strip leading newlines from emitted text. |
+
+## States
+
+A state is a `#`-headed section. Its name is the heading text. `#` characters
+inside the heading are removed from the name.
+
+A state contains:
+
+- **Text** — paragraphs shown to the player on entry.
+- **Options** — the list of things the player can do.
+- **Code** — backticked Tzo code (see below), executed in place.
+
+### State text and code
+
+Plain paragraphs are emitted as text when the player enters the state.
+Inline code in the text is executed as Tzo code at that point:
+
+```markdown
+You have `"cookies" getContext emit` cookies!
+```
+
+This pushes the value of `cookies`, then emits it, so the player sees
+`You have 3 cookies!`.
+
+A code block with language `comment` is ignored entirely and never reaches the
+player or the interpreter:
+
+````markdown
+```comment
+This is a note for the human writers. It is never executed or shown.
+```
+````
+
+## Options
+
+Options are list items under a state's text. An option can have:
+
+- a **text** (the label shown in the menu),
+- a **link** (a `#state` target to jump to when chosen),
+- **precondition** code (backticks before the text; the option is hidden when
+  the code leaves a non-positive value),
+- a **directive** (backticks before the text starting with `@`),
+- **effect** code (backticks after the text; executed when chosen),
+- **post-option text** (paragraphs after the option line; emitted when chosen).
+
+Examples:
+
+```markdown
+* A simple statement with no effect
+* [A link to another state](#other)
+* A statement that quits when chosen `exit`
+* `"key" getContext` A conditional option (hidden unless "key" is positive)
+* `@once` An option that can only be chosen once
+* `@once` `"a" getContext` Once, and only when "a" is positive
+```
+
+When a player chooses an option, the interpreter:
+
+1. runs the option's effect code,
+2. emits the option's post-option text (interleaved with the effect),
+3. follows the option's link (`goto`),
+4. or, if there is no link and no effect, applies `no_link_behaviour`.
+
+### Preconditions
+
+Backticked code before an option's text is a precondition. The interpreter
+executes it and offers the option only if the code leaves a value greater than
+zero on the stack. Preconditions are how you build branching, story-aware menus
+(see [context](#context)).
+
+Note that `getContext` throws if the key is not present in the context, so
+every key read in a precondition should be initialized in `initial-context`.
+
+### The `@once` directive
+
+An option marked `@once` is only offered once per play session. After the
+player chooses it, it disappears from the menu. The interpreter implements this
+with an internal context key (`__once__N`).
+
+## Context
+
+The **context** is a bag of named variables (numbers and strings) that tracks
+what the player has done. It is initialized from `initial-context` and mutated
+by effect code.
+
+Common patterns:
+
+```markdown
+`1 "door_open" setContext`          ; store the number 1 under "door_open"
+`"door_open" getContext`            ; push the value of "door_open"
+`"door_open" hasContext`            ; push 1 if the key exists, else 0
+`"door_open" delContext`            ; remove the key
+```
+
+Use the `emit` opcode to show a context value in text, and `getContext` in a
+precondition to gate options on it.
+
+## Tzo code
+
+Code inside backticks is Tzo bytecode written in reverse-Polish order: operands
+first, operator last. Strings are double-quoted. Example:
+
+```
+"NORMAL_HELLO_" 2 randInt 65 + charCode rconcat goto
+```
+
+### Opcodes
+
+The standard opcode set (provided by Tzo and QuestVM):
+
+| Opcode | Stack effect | Description |
+| --- | --- | --- |
+| `emit` | `(value)` | Emit text/number to the player. |
+| `exit` | | End the conversation. |
+| `goto` | `(label \| pc)` | Jump to a label or program position. |
+| `pause` | | Suspend the VM. |
+| `getContext` | `(key) -> value` | Push the value of a context key (throws if absent). |
+| `hasContext` | `(key) -> 0 \| 1` | Push whether the key exists. |
+| `setContext` | `(key value)` | Store `value` under `key`. |
+| `delContext` | `(key)` | Remove `key` from the context. |
+| `eq` | `(a b) -> 0 \| 1` | Push `1` if `a == b`. |
+| `gt` | `(a b) -> 0 \| 1` | Push `1` if `a > b`. |
+| `lt` | `(a b) -> 0 \| 1` | Push `1` if `a < b`. |
+| `and` | `(a b) -> 0 \| 1` | Logical and. |
+| `or` | `(a b) -> 0 \| 1` | Logical or. |
+| `not` | `(a) -> 0 \| 1` | Logical not. |
+| `jgz` | `(a)` | Skip the next instruction if `a > 0`. |
+| `jz` | `(a)` | Skip the next instruction if `a == 0`. |
+| `+` / `plus` | `(a b) -> a+b` | Addition. |
+| `-` / `min` | `(a b) -> a-b` | Subtraction. |
+| `*` / `mul` | `(a b) -> a*b` | Multiplication. |
+| `concat` | `(a b) -> "a"+"b"` | Concatenate (topmost value first). |
+| `rconcat` | `(a b) -> "b"+"a"` | Concatenate (topmost value last). |
+| `dup` | `(a) -> a a` | Duplicate the top of stack. |
+| `pop` | `(a)` | Discard the top of stack. |
+| `stacksize` | `() -> n` | Push the stack depth. |
+| `randInt` | `(max) -> 0..max-1` | Push a random integer. |
+| `charCode` | `(n) -> char` | Push the character for code point `n`. |
+| `nop` | | Do nothing. |
+| `{` / `}` | | Block delimiters used by `jgz`/`jz` to skip code. |
+| `ppc` | `() -> pc` | Push the current program counter (used internally). |
+
+The QuestVM adds the choice machinery, used by the compiler internally:
+
+| Opcode | Description |
+| --- | --- |
+| `response` | Register the current option's effect position as a choice. |
+| `getResponse` | Suspend the VM and ask the host for a choice. |
+
+`optionEnabled`, `optionDisabled`, `disableOption`, and `enableOption` are
+deprecated and should not be used.
+
+Functions not registered in the VM are an error at runtime, unless their name
+starts with `_`, in which case they are silently treated as a no-op (handy as
+markers or hooks for host applications).
+
+## Limitations and notes
+
+- The spec is still informal, and the feature set is still evolving.
+- `getContext` on an uninitialized key throws; initialize keys up front.
+- An option that has neither a link nor an effect loops back to the menu by
+  default (`loopback_to_options`), which can appear to loop forever if the
+  option is always available. Set `no_link_behaviour` to `"exit"` or give the
+  option a link/effect if that's not what you want.
+- Comments inside option text are not yet supported by the interpreter; a
+  backtick in an option label produces a warning.