feat: add passage metadata, currentPassage() and previousPassage()

- Parse Twee 3 metadata from passage headers into `metadata` field on Passage
- Add `Story.currentPassage()` and `Story.previousPassage()` to Story API
- Add `currentPassage()` and `previousPassage()` as expression functions
- Add pre-commit hook with husky + lint-staged for prettier formatting

release-npm

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: clem

.gitignore

@@ -12,3 +12,4 @@ PLAN.md
 TODO
 skills-lock.json
 menubar-default.png
+.vscode-diagnostics.json

.husky/pre-commit

@@ -0,0 +1 @@
+bunx lint-staged

CHANGELOG.md

@@ -7,11 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-3-5
+
 ### Added
 
 - Seedable PRNG (Mulberry32) with `Story.prng.init()`, `Story.random()`, `Story.randomInt()`
 - `random()` and `randomInt(min, max)` available in expressions
 - PRNG state survives save/load and history navigation via pull-counter approach
+- `metadata` field on passages, parsed from Twee 3 passage header metadata (exposed as `Record<string, string>`)
+- `Story.currentPassage()` and `Story.previousPassage()` return the full `Passage` object
+- `currentPassage()` and `previousPassage()` available in expressions
+- Pre-commit hook with husky + lint-staged to run prettier on staged files
 
 ## [0.3.2] - 2026-3-5
 

bun.lock

@@ -82,6 +82,50 @@ Register a class so its instances can be cloned, saved, and restored with their
 
 See [Using Classes](variables.md#using-classes) for full details.
 
+## Passage Lookup
+
+### `Story.currentPassage()`
+
+Returns the full passage object for the current passage, or `undefined` if not found.
+
+```js
+var p = Story.currentPassage();
+console.log(p.name); // "Forest"
+console.log(p.tags); // ["dark", "outdoor"]
+console.log(p.metadata); // { position: "600,400" }
+```
+
+### `Story.previousPassage()`
+
+Returns the full passage object for the previous passage in history, or `undefined` if there is no previous passage (e.g. on the start passage).
+
+```js
+var prev = Story.previousPassage();
+if (prev) {
+  console.log('Came from: ' + prev.name);
+}
+```
+
+### Passage object
+
+Both methods return a passage object with these properties:
+
+| Property   | Type                     | Description                                                                       |
+| ---------- | ------------------------ | --------------------------------------------------------------------------------- |
+| `pid`      | `number`                 | Passage ID from the story data                                                    |
+| `name`     | `string`                 | Passage name                                                                      |
+| `tags`     | `string[]`               | Tags from the passage header                                                      |
+| `metadata` | `Record<string, string>` | Metadata from the Twee 3 passage header (e.g. `position`, `size`, or custom keys) |
+| `content`  | `string`                 | Raw passage content                                                               |
+
+The `metadata` field contains all attributes from the passage header's JSON metadata block. In Twee 3 format, this is the JSON object at the end of the header line:
+
+```
+:: Forest [dark outdoor] {"position":"600,400","size":"100,200","difficulty":"hard"}
+```
+
+Standard keys like `position` and `size` are included alongside any custom keys the author adds.
+
 ## Passage Tracking
 
 Spindle tracks how many times each passage has been **visited** (navigated to) and **rendered** (visited or included). Back/forward navigation does not increment counts — only new visits and `{include}` calls do.

docs/story-api.md

@@ -129,6 +129,8 @@ The following functions are available in any expression to check passage visit a
 
 | Function                        | Returns   | Description                                                  |
 | ------------------------------- | --------- | ------------------------------------------------------------ |
+| `currentPassage()`              | `object`  | The current passage object (name, tags, metadata, content)   |
+| `previousPassage()`             | `object`  | The previous passage object, or `undefined` on start         |
 | `visited("name")`               | `number`  | Times the passage was visited                                |
 | `hasVisited("name")`            | `boolean` | Whether the passage was visited at least once                |
 | `hasVisitedAny("a", "b", ...)`  | `boolean` | Whether **any** of the passages were visited                 |
@@ -154,6 +156,18 @@ Use these directly in `{if}` conditions or any expression:
 {print visited("Start")} visits to the start passage.
 ```
 
+Access passage metadata in expressions:
+
+```
+{if currentPassage().tags.includes("dark")}
+  It's too dark to see.
+{/if}
+
+{if previousPassage()}
+  You came from {print previousPassage().name}.
+{/if}
+```
+
 **Visited** counts passages the player navigated to via links, `{goto}`, or as the start passage. Back/forward navigation does not increment the count.
 
 **Rendered** is a superset of visited — it also counts passages rendered inline via `{include}`.

docs/variables.md

@@ -46,7 +46,8 @@
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",
-    "prepublishOnly": "bun run test && bun run build"
+    "prepublishOnly": "bun run test && bun run build",
+    "prepare": "husky"
   },
   "dependencies": {
     "immer": "^11.1.4",
@@ -56,13 +57,18 @@
     "preact": "^10.28.4",
     "zustand": "^5.0.11"
   },
+  "lint-staged": {
+    "*": "prettier --write --ignore-unknown"
+  },
   "devDependencies": {
     "@preact/preset-vite": "^2.10.3",
     "@rohal12/twee-ts": "^1.1.2",
     "@types/js-yaml": "^4.0.9",
     "@vitest/coverage-v8": "^4.0.18",
     "happy-dom": "^20.8.3",
+    "husky": "^9.1.7",
     "js-yaml": "^4.1.1",
+    "lint-staged": "^16.3.2",
     "playwright": "^1.58.2",
     "prettier": "^3.8.1",
     "typescript": "^5.9.3",

package.json

@@ -1,8 +1,11 @@
 import type { StoryState } from './store';
 import { useStoryStore } from './store';
+import type { Passage } from './parser';
 import { random, randomInt } from './prng';
 
 interface ExpressionFns {
+  currentPassage: () => Passage | undefined;
+  previousPassage: () => Passage | undefined;
   visited: (name: string) => number;
   hasVisited: (name: string) => boolean;
   hasVisitedAny: (...names: string[]) => boolean;
@@ -39,7 +42,7 @@ function transform(expr: string): string {
 }
 
 const preamble =
-  'const {visited,hasVisited,hasVisitedAny,hasVisitedAll,rendered,hasRendered,hasRenderedAny,hasRenderedAll,random,randomInt}=__fns;';
+  'const {currentPassage,previousPassage,visited,hasVisited,hasVisitedAny,hasVisitedAll,rendered,hasRendered,hasRenderedAny,hasRenderedAll,random,randomInt}=__fns;';
 
 function getOrCompile(key: string, body: string): CompiledExpression {
   const cached = fnCache.get(key);
@@ -94,7 +97,20 @@ export function buildExpressionFns() {
   const hasRenderedAll = (...names: string[]): boolean =>
     names.every((n) => rendered(n) > 0);
 
+  const currentPassage = (): Passage | undefined => {
+    const s = useStoryStore.getState();
+    return s.storyData?.passages.get(s.currentPassage);
+  };
+  const previousPassage = (): Passage | undefined => {
+    const s = useStoryStore.getState();
+    if (s.historyIndex <= 0) return undefined;
+    const prevName = s.history[s.historyIndex - 1]?.passage;
+    return prevName ? s.storyData?.passages.get(prevName) : undefined;
+  };
+
   cachedFns = {
+    currentPassage,
+    previousPassage,
     visited,
     hasVisited,
     hasVisitedAny,

src/expression.ts

@@ -2,6 +2,7 @@ export interface Passage {
   pid: number;
   name: string;
   tags: string[];
+  metadata: Record<string, string>;
   content: string;
 }
 
@@ -53,7 +54,21 @@ export function parseStoryData(): StoryData {
       .filter((t) => t.length > 0);
     const content = el.textContent || '';
 
-    const passage: Passage = { pid, name: passageName, tags, content };
+    const metadata: Record<string, string> = {};
+    const skipAttrs = new Set(['pid', 'name', 'tags']);
+    for (const attr of el.attributes) {
+      if (!skipAttrs.has(attr.name)) {
+        metadata[attr.name] = attr.value;
+      }
+    }
+
+    const passage: Passage = {
+      pid,
+      name: passageName,
+      tags,
+      metadata,
+      content,
+    };
     passages.set(passageName, passage);
     passagesById.set(pid, passage);
   }

src/parser.ts

@@ -1,4 +1,5 @@
 import { useStoryStore } from './store';
+import type { Passage } from './parser';
 import { settings } from './settings';
 import type { SavePayload } from './saves/types';
 import { setTitleGenerator } from './saves/save-manager';
@@ -46,6 +47,8 @@ export interface StoryAPI {
   hasRendered(name: string): boolean;
   hasRenderedAny(...names: string[]): boolean;
   hasRenderedAll(...names: string[]): boolean;
+  currentPassage(): Passage | undefined;
+  previousPassage(): Passage | undefined;
   readonly title: string;
   readonly passage: string;
   readonly settings: typeof settings;
@@ -150,6 +153,18 @@ function createStoryAPI(): StoryAPI {
       return names.every((n) => (renderCounts[n] ?? 0) > 0);
     },
 
+    currentPassage(): Passage | undefined {
+      const state = useStoryStore.getState();
+      return state.storyData?.passages.get(state.currentPassage);
+    },
+
+    previousPassage(): Passage | undefined {
+      const state = useStoryStore.getState();
+      if (state.historyIndex <= 0) return undefined;
+      const prevName = state.history[state.historyIndex - 1]?.passage;
+      return prevName ? state.storyData?.passages.get(prevName) : undefined;
+    },
+
     get title(): string {
       return useStoryStore.getState().storyData?.name || '';
     },