@ak--47/dungeon-master 1.5.1 → 1.5.3

package/.claude/skills/write-hooks/SKILL.md

@@ -36,8 +36,8 @@ Out of scope:
 - `lib/hook-patterns/index.js` — high-level recipes (one per Mixpanel
   analysis type).
 - `lib/verify/emulate-breakdown.js` — what `verify-dungeon` will check.
-- `dungeons/user/my-buddy.js` — reference dungeon using a mix of atoms and
-  hand-rolled logic.
+- `dungeons/user/my-buddy/my-buddy.js` — reference dungeon using a mix of atoms
+  and hand-rolled logic.
 - `dungeons/technical/pattern-*.js` — five minimal pattern fixtures, one per
   recipe.
 - `HOOKS.md` — encyclopedia of hook recipes organized by story pattern. Contains
@@ -78,6 +78,10 @@ Inside `funnel-pre` and `funnel-post`:
 Inside `everything`:
 - `meta.authTime: number | null` — unix-ms of the stitch event, null if never authed
 - `meta.isPreAuth(event): boolean` — convenience predicate
+- `meta.profile` — full profile object. Mutate or rescue here.
+- `meta.userIsBornInDataset: boolean` — true when user was born inside the dataset window
+- `meta.scd: { <key>: SCDEntry[] }` — SCD entries per key
+- `meta.datasetStart, meta.datasetEnd: number` — unix-seconds bounds
 
 Pattern: gate trend logic on `meta.isFinalAttempt` so failed prior attempts
 don't get the same treatment as the converted attempt.
@@ -196,9 +200,10 @@ writing a custom hook:
 - **Time-series trends** ("conversion rises week over week") — wrap any
   breakdown with `timeBucket: 'week'`. Engineer via temporal-windowed hooks
   using `DATASET_START.add(N, 'days')`.
-- **Identity-model dungeons** — when `avgDevicePerUser > 0` or
-  `hasAnonIds: true`, ALWAYS pass `profiles` to verification. Auto-builds
-  identity map merging pre-auth `device_id` events with post-auth `user_id`.
+- **Identity-model dungeons** — when `identity.avgDevicePerUser > 0`
+  (or the deprecated `hasAnonIds: true`), ALWAYS pass `profiles` to
+  verification. Auto-builds identity map merging pre-auth `device_id`
+  events with post-auth `user_id`.
 
 **Schema-first reminder:** exclusion events must be declared in `events[]`
 before referencing them as `Funnel.exclusionEvents` — the validator throws
@@ -234,6 +239,10 @@ record.was_dropped = false;      // ❌ flag-stamping
 event.engineered_pattern_id = 5; // ❌ flag-stamping
 ```
 
+(One narrow exception: `meta.profile._drop` is engine-recognized — see
+the "Anonymous non-converter `_drop` rescue" section above. All OTHER
+flags must live in `userProps`/event `properties` with a declared default.)
+
 DO WRITE:
 ```js
 record.amount *= 3;                            // ✅ scale existing numeric prop
@@ -259,6 +268,25 @@ hook: function(record, type, meta) {
 }
 ```
 
+### Anonymous non-converter `_drop` rescue (v1.5.1)
+
+Born-in-dataset users who never reach an `isAuthEvent` step get
+`_drop: true` stamped on their profile BEFORE the `everything` hook fires.
+`mixpanel-sender` filters those before pushing to `/engage`. Hooks can
+rescue a profile by deleting the flag:
+
+```js
+if (type === 'everything' && meta.profile) {
+  // Rescue: keep some anonymous power-users in /engage even without sign_up.
+  const eventCount = record.length;
+  if (eventCount >= 20) delete meta.profile._drop;
+}
+```
+
+`_drop` is the ONE engine-recognized flag a hook may set/clear on a
+profile — every other property must be declared in `userProps` first per
+the anti-flag-stamping rule below.
+
 When a dungeon uses funnel `attempts`, hooks can reach into individual attempts
 via funnel-post meta:
 

package/CHANGELOG.md

@@ -2,6 +2,99 @@
 
 All notable changes to `@ak--47/dungeon-master`.
 
+## 1.5.3 — 2026-06-04
+
+Adds two JSON/source interop helpers to the public API. No breaking changes —
+existing exports and behavior are untouched.
+
+### Added
+
+- **`dungeonToJSON(input, options?)`** export. The inverse of `parseJSONDungeon`:
+  turns a dungeon into the `{ schema, hooks, timestamp, version }` JSON/UI wrapper
+  format. Accepts the same input flavors as the default export — a config object,
+  a `.js`/`.mjs`/`.json` file path, a raw JS source string, or an array of file
+  paths (returns an array). Output round-trips: `parseJSONDungeon(await
+  dungeonToJSON(x))` yields a runnable config. Best effort — arrow functions and
+  bound `chance.*` methods survive the round trip; detected utility calls
+  (`weighArray`, `weighNumRange`, …) are serialized by name without their
+  arguments and revive to `null` (handled gracefully by the validator). To keep
+  the field's **type** even when the generator can't be revived, every function
+  is sampled at serialization time (closures are still live) and its inferred
+  output type is recorded as `dataType` on the serialized object (e.g.
+  `{ functionName: "weighNumRange", args: [], dataType: "number" }`).
+  **Credentials (`token`, `serviceAccount`, `serviceSecret`, `projectId`,
+  `secret`) are stripped by default** so tokens never leak into JSON — pass
+  `{ includeCredentials: true }` to keep them.
+- **`DungeonJSON`, `DungeonComments`, and `SerializedFunction` types** in
+  `types.d.ts` — the JSON-representation shapes are now formally specced.
+- **`extractComments(input)`** export. Pulls the human-readable doc blocks out of
+  a dungeon's **source** — the `// ── OVERVIEW ──` and `// ── HOOK STORIES ──`
+  blocks plus every other `// ── LABEL ──` header that is immediately followed by
+  a block comment. Returns `{ overview, hookStories, sections }` with the comment
+  scaffolding (`// ──`, `/* */`, leading ` * `) stripped to readable prose.
+  Operates on a file path or raw source string — it never imports the dungeon,
+  since importing discards comments. Best effort: relies on the canonical
+  header + block-comment convention emitted by the `create-dungeon` /
+  `write-hooks` skills.
+
+### Changed
+
+- **`scripts/dungeon-to-json.mjs`** is now a thin CLI wrapper over the exported
+  `dungeonToJSON` (passing `includeCredentials: true` to preserve its legacy
+  full-config UI round-trip output). The inline `convertToJSON` /
+  `convertFunctionToObject` logic moved into `lib/core/dungeon-to-json.js`.
+
+### Why
+
+The package could ingest JSON dungeons (`parseJSONDungeon`, `loadFromFile`,
+`loadFromText`) but had no exported way to go the other direction, and no way to
+programmatically read a dungeon's OVERVIEW / HOOK STORIES documentation. Both
+existed only as un-importable script internals. Exporting them completes
+best-effort JSON interop and lets tools (UIs, LLM pipelines) read dungeon docs
+directly.
+
+## 1.5.2 — 2026-05-21
+
+Docs-only patch. Aligns the `.claude/skills/` authoring + verification
+guides with the 1.5.1 engine + config API. No runtime changes.
+
+### Changed
+
+- **`create-dungeon` skill** now emits the canonical dungeon layout
+  (IMPORTS / OVERVIEW / SCALE / DATA ARRAYS / CONFIG sections) and the
+  sub-object config API (`credentials` / `switches` / `identity`).
+  Removed the old `// ── TWEAK THESE ──` template + flat-key example.
+- **`create-dungeon` skill** documents `hasAnonIds` as deprecated; nudges
+  authors to write `identity.avgDevicePerUser: 1` directly.
+- **`create-dungeon` skill** adds sections for `retentionCurve`,
+  `userSeed`, anonymous-non-converter `_drop: true` semantics, and
+  flags the touchpoint-sampling generator/verifier asymmetry.
+- **`write-hooks` skill** documents the `meta.profile._drop` rescue
+  pattern (the one engine-recognized flag a hook may set/clear on a
+  profile). Expanded `meta` interface listing for the `everything` hook.
+- **`verify-dungeon/references/counting-semantics.md`** notes known
+  divergences from Mixpanel C++ (calendar vs rolling distinct-period
+  default, COMPOUNDED retention not implemented, touchpoint sampling
+  asymmetry, list-typed AVG/SUM no auto-flatten). All references to
+  `hasAnonIds: true` updated to the new `identity.avgDevicePerUser` shape.
+- **`verify-dungeon/references/sql-recipes.md`** drops `Platform` from
+  the expected device-keys table (removed in 1.5.1; `os` covers the
+  signal). Updates casing check to drop `Platform`-vs-`platform` rule.
+  Adds an anonymous-non-converter `_drop` audit query as standard check
+  #0 for identity-model dungeons. Updates "Advanced feature verification"
+  to list only currently-supported features (`personas`, `worldEvents`,
+  `engagementDecay`, `dataQuality`); calls out the deprecated config
+  blocks (`subscription`, `attribution`, `geo`, `features`, `anomalies`)
+  the validator silently strips.
+
+### Why
+
+Skills are how most dungeons get authored. Drifting between skill-emitted
+output and 1.5.1 engine behavior would silently produce stale-shape
+dungeons + missed coverage of new features (`retentionCurve`, `userSeed`,
+`_drop` semantics, sub-object API). Patch keeps skill output and engine
+behavior synchronized.
+
 ## 1.5.1 — 2026-05-20
 
 Quality + ergonomics release. No new analytical capabilities — fixes accumulated rough edges around concurrency, accuracy, profiles, and config ergonomics that surfaced after 1.5.0 shipped. Adds a generator-side retention shaper, exposes a config sub-object API for cleaner dungeon files, and restructures all 48 shipped dungeons to a canonical layout. Top-level keys keep working for back-compat.

package/README.md

@@ -155,6 +155,32 @@ import { createTextGenerator, generateBatch } from '@ak--47/dungeon-master/text'
 
 these are the same functions used internally. `pickAWinner` creates weighted distributions, `weighNumRange` generates realistic numeric ranges with configurable skew, and the text generators produce organic-looking strings with sentiment analysis and keyword injection.
 
+### named exports
+
+alongside the default `DUNGEON_MASTER` export, the package root exports loader + interop helpers:
+
+```javascript
+import DUNGEON_MASTER, {
+    loadFromFile,          // (path)            → Promise<Dungeon>   load+validate a .js/.mjs/.json dungeon
+    loadFromText,          // (code)            → Promise<Dungeon>   load+validate a raw JS source string
+    parseJSONDungeon,      // (json)            → Dungeon            revive a JSON dungeon into a runnable config
+    validateDungeonShape,  // (config)          → void               throw if config isn't dungeon-shaped
+    dungeonToJSON,         // (input, options?) → Promise<DungeonJSON>     serialize a dungeon → JSON (inverse of parseJSONDungeon)
+    extractComments,       // (input)           → DungeonComments    pull OVERVIEW / HOOK STORIES doc blocks from source
+} from '@ak--47/dungeon-master';
+```
+
+`dungeonToJSON` accepts a config object, a file path, raw JS source, or an array of paths, and returns the `{ schema, hooks, timestamp, version }` wrapper format. it round-trips with `parseJSONDungeon`:
+
+```javascript
+const json   = await dungeonToJSON('./dungeons/vertical/ecommerce.js');  // creds stripped by default
+const config = parseJSONDungeon(json);                                   // back to a runnable dungeon
+```
+
+it's best effort — arrow functions and `chance.*` methods survive the round trip; detected utility calls (`weighArray`, `weighNumRange`, …) serialize by name without their args. pass `{ includeCredentials: true }` to keep `token` / `serviceAccount` / etc. in the output (stripped by default).
+
+`extractComments` reads a dungeon's **source** (file path or raw text — never the imported module, since importing discards comments) and returns `{ overview, hookStories, sections }` with the comment scaffolding stripped to readable prose.
+
 ## how it works
 
 one call to `DUNGEON_MASTER(config)` runs through these phases in order:

package/index.js

@@ -15,6 +15,8 @@ import { createContext, updateContextWithStorage } from './lib/core/context.js';
 import { validateDungeonConfig } from './lib/core/config-validator.js';
 import { StorageManager } from './lib/core/storage.js';
 import { detectInputType, loadFromFile, loadFromText, parseJSONDungeon, validateDungeonShape } from './lib/core/dungeon-loader.js';
+import { dungeonToJSON } from './lib/core/dungeon-to-json.js';
+import { extractComments } from './lib/core/extract-comments.js';
 
 // Orchestrators
 import { userLoop } from './lib/orchestrators/user-loop.js';
@@ -597,5 +599,5 @@ function extractStorageData(storage) {
 
 // ES Module exports
 export default DUNGEON_MASTER;
-export { parseJSONDungeon, validateDungeonShape, loadFromFile, loadFromText };
+export { parseJSONDungeon, validateDungeonShape, loadFromFile, loadFromText, dungeonToJSON, extractComments };
 

package/lib/core/dungeon-to-json.js

@@ -0,0 +1,220 @@
+/**
+ * dungeon → JSON serialization.
+ *
+ * The inverse of `parseJSONDungeon` (lib/core/dungeon-loader.js): turns a runnable
+ * dungeon into the UI/JSON wrapper format `{ schema, hooks, timestamp, version }`.
+ * Functions in the schema are serialized to `{ functionName, body }` / `{ functionName, args }`
+ * objects that `reviveJSONConfig` knows how to revive — so the output round-trips:
+ *
+ *   parseJSONDungeon(await dungeonToJSON(cfg))  →  runnable config
+ *
+ * This is BEST EFFORT. Arrow functions and bound `chance.*` methods round-trip cleanly;
+ * detected utility calls (weighArray, weighNumRange, …) are serialized without their
+ * arguments and revive to null, which the config validator handles gracefully.
+ *
+ * To preserve the field's TYPE even when the generator can't be revived, every function
+ * is sampled at serialization time (when its closure is still live) and the inferred
+ * output type is recorded as `dataType` (e.g. "number", "string", "boolean", "number[]").
+ * So a field that loses its `weighNumRange(1,10)` generator still records `dataType: "number"`.
+ */
+
+import { detectInputType, loadFromFile, loadFromText } from './dungeon-loader.js';
+
+/** Credential keys stripped from JSON output unless `includeCredentials` is set. */
+const CREDENTIAL_KEYS = ['token', 'serviceAccount', 'serviceSecret', 'projectId', 'secret'];
+
+/**
+ * Convert a dungeon into its JSON representation.
+ *
+ * Accepts the same input flavors as the default export: a config object, a path to a
+ * `.js`/`.mjs`/`.json` dungeon file, a raw JS source string (must `export default`), or
+ * an array of file paths (returns an array of results).
+ *
+ * @param {import('../../types').Dungeon | string | string[]} input
+ * @param {{ includeCredentials?: boolean }} [options]
+ * @returns {Promise<import('../../types').DungeonJSON | import('../../types').DungeonJSON[]>}
+ */
+export async function dungeonToJSON(input, options = {}) {
+	const { includeCredentials = false } = options;
+	const { type, value } = detectInputType(input);
+
+	switch (type) {
+		case 'object':
+			return serializeConfig(value, includeCredentials);
+		case 'file':
+			return serializeConfig(await loadFromFile(value), includeCredentials);
+		case 'text':
+			return serializeConfig(await loadFromText(value), includeCredentials);
+		case 'files':
+			return Promise.all(
+				value.map(async (p) => serializeConfig(await loadFromFile(p), includeCredentials))
+			);
+		default:
+			throw new Error(`dungeon-master: dungeonToJSON cannot handle input type "${type}".`);
+	}
+}
+
+/**
+ * Build the `{ schema, hooks, timestamp, version }` wrapper from a runnable config.
+ * @param {import('../../types').Dungeon} config
+ * @param {boolean} includeCredentials
+ * @returns {import('../../types').DungeonJSON}
+ */
+function serializeConfig(config, includeCredentials) {
+	// Hook may be a live function (from .js/text/object) or already a string (from .json).
+	const hook = config.hook;
+	const hooks = typeof hook === 'function'
+		? hook.toString()
+		: (typeof hook === 'string' ? hook : null);
+
+	// Strip the hook (serialized separately) and, by default, credentials (don't leak tokens).
+	const cleanConfig = { ...config };
+	delete cleanConfig.hook;
+	if (!includeCredentials) {
+		for (const key of CREDENTIAL_KEYS) delete cleanConfig[key];
+	}
+
+	return {
+		schema: convertToJSON(cleanConfig),
+		hooks,
+		timestamp: new Date().toISOString(),
+		version: '4.0'
+	};
+}
+
+/**
+ * Convert a JavaScript value to a JSON-serializable form, turning functions into
+ * `{ functionName, body | args }` objects that `reviveJSONConfig` can revive.
+ * @param {any} value
+ * @returns {any}
+ */
+export function convertToJSON(value) {
+	// Null/undefined
+	if (value === null || value === undefined) {
+		return null;
+	}
+
+	// Primitives
+	if (typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string') {
+		return value;
+	}
+
+	// Functions - convert to object representation
+	if (typeof value === 'function') {
+		return convertFunctionToObject(value);
+	}
+
+	// Arrays
+	if (Array.isArray(value)) {
+		return value.map(item => convertToJSON(item));
+	}
+
+	// Objects
+	if (typeof value === 'object') {
+		const result = {};
+		for (const [key, val] of Object.entries(value)) {
+			result[key] = convertToJSON(val);
+		}
+		return result;
+	}
+
+	// Fallback
+	return null;
+}
+
+/**
+ * Convert a function to its object representation.
+ * Arrow functions and bound `chance.*` methods round-trip cleanly; detected utility
+ * functions are stored by name without args (best effort). Every form also carries a
+ * sampled `dataType` so the field's output type survives even when the generator can't.
+ * @param {Function} func
+ * @returns {import('../../types').SerializedFunction}
+ */
+function convertFunctionToObject(func) {
+	const funcString = func.toString();
+	// Sample now, while the closure is still live — the only reliable time to learn the type.
+	const dataType = inferDataType(func);
+
+	// Arrow function
+	if (funcString.startsWith('(') || funcString.startsWith('_') || funcString.includes('=>')) {
+		return withDataType({ functionName: 'arrow', body: funcString }, dataType);
+	}
+
+	// Bound chance methods (e.g., chance.name.bind(chance))
+	if (funcString.includes('.bind(')) {
+		const match = funcString.match(/chance\.(\w+)\.bind/);
+		if (match) {
+			return withDataType({ functionName: `chance.${match[1]}`, args: [] }, dataType);
+		}
+	}
+
+	// Try to detect common utility functions
+	// This is a best-effort approach - some complex functions might not be detected
+	const commonFunctions = [
+		'weighNumRange',
+		'weighArray',
+		'weighChoices',
+		'pickAWinner',
+		'date',
+		'integer',
+		'uid',
+		'comma'
+	];
+
+	for (const fnName of commonFunctions) {
+		if (funcString.includes(fnName)) {
+			// Args can't be recovered from a stringified function, but dataType is captured.
+			return withDataType({ functionName: fnName, args: [] }, dataType);
+		}
+	}
+
+	// Generic function - just store as arrow function
+	return withDataType({ functionName: 'arrow', body: funcString }, dataType);
+}
+
+/**
+ * Attach a `dataType` field if one was inferred (omitted otherwise).
+ * @param {import('../../types').SerializedFunction} obj
+ * @param {string | undefined} dataType
+ * @returns {import('../../types').SerializedFunction}
+ */
+function withDataType(obj, dataType) {
+	if (dataType) obj.dataType = dataType;
+	return obj;
+}
+
+/**
+ * Sample a function (no args) and classify its return type. Best effort — returns
+ * undefined if the call throws or yields an indeterminate value.
+ * @param {Function} func
+ * @returns {string | undefined}
+ */
+function inferDataType(func) {
+	let value;
+	try {
+		value = func();
+	} catch {
+		return undefined;
+	}
+	return classifyValue(value);
+}
+
+/**
+ * Map a sampled value to a type label: "number" | "string" | "boolean" | "date" |
+ * "object" | "<elementType>[]" | "array". Returns undefined for null/undefined/functions.
+ * @param {any} value
+ * @returns {string | undefined}
+ */
+function classifyValue(value) {
+	if (value === null || value === undefined) return undefined;
+	if (Array.isArray(value)) {
+		const el = value.find((v) => v !== null && v !== undefined);
+		const elType = el === undefined ? undefined : classifyValue(el);
+		return elType ? `${elType}[]` : 'array';
+	}
+	if (value instanceof Date) return 'date';
+	const t = typeof value;
+	if (t === 'number' || t === 'string' || t === 'boolean') return t;
+	if (t === 'object') return 'object';
+	return undefined;
+}

package/lib/core/extract-comments.js

@@ -0,0 +1,120 @@
+/**
+ * Best-effort extraction of the human-readable doc blocks from a dungeon's SOURCE.
+ *
+ * Generated/authored dungeons separate sections with box-drawing headers followed by a
+ * block comment, e.g.:
+ *
+ *   // ── OVERVIEW ──
+ *   /* ... *\/
+ *   // ── HOOK STORIES ──
+ *   /* ... *\/
+ *
+ * This pulls those blocks out as cleaned prose. It operates on RAW SOURCE TEXT — it never
+ * imports the dungeon, because importing a module discards its comments.
+ *
+ * Returns `{ overview, hookStories, sections }`:
+ *   - `overview`    — cleaned text of the OVERVIEW block (or null)
+ *   - `hookStories` — cleaned text of the HOOK STORIES block (or null)
+ *   - `sections`    — every `// ── LABEL ──` header that is immediately followed by a
+ *                     block comment, keyed by the exact label as written.
+ */
+
+import { readFileSync } from 'fs';
+import { detectInputType } from './dungeon-loader.js';
+
+// A `// ── LABEL ──` header line. Anchored to `//` at line start so that the inner
+// ` * ───────` dividers inside a block comment are NOT mistaken for section headers.
+const HEADER_RE = /^[ \t]*\/\/[ \t]*─+[ \t]*(.+?)[ \t]*─+[ \t]*$/gm;
+
+/**
+ * @param {string | string[]} input - A dungeon file path, raw dungeon source, or array of paths.
+ * @returns {import('../../types').DungeonComments | import('../../types').DungeonComments[]}
+ */
+export function extractComments(input) {
+	const { type, value } = detectInputType(input);
+
+	switch (type) {
+		case 'file':
+			return parseSource(readFileSync(value, 'utf-8'));
+		case 'text':
+			return parseSource(value);
+		case 'files':
+			return value.map((p) => parseSource(readFileSync(p, 'utf-8')));
+		case 'object':
+			throw new Error(
+				'dungeon-master: extractComments needs source text or a file path, not a config object (comments are lost once a dungeon is imported).'
+			);
+		default:
+			throw new Error(`dungeon-master: extractComments cannot handle input type "${type}".`);
+	}
+}
+
+/**
+ * Parse a single source string into `{ overview, hookStories, sections }`.
+ * @param {string} source
+ * @returns {import('../../types').DungeonComments}
+ */
+function parseSource(source) {
+	/** @type {Record<string, string>} */
+	const sections = {};
+
+	// Collect every header with its label and the position right after its line.
+	const headers = [];
+	HEADER_RE.lastIndex = 0;
+	let m;
+	while ((m = HEADER_RE.exec(source)) !== null) {
+		headers.push({ label: m[1].trim(), end: HEADER_RE.lastIndex });
+	}
+
+	for (let i = 0; i < headers.length; i++) {
+		const { label, end } = headers[i];
+		// Only look between this header and the next one.
+		const sliceEnd = i + 1 < headers.length ? headers[i + 1].end : source.length;
+		const slice = source.slice(end, sliceEnd);
+
+		// Accept the block only if a `/* ... */` comment is the first non-whitespace content
+		// after the header (so headers followed by code — IMPORTS, SCALE — are skipped).
+		const block = slice.match(/^\s*\/\*([\s\S]*?)\*\//);
+		if (block) {
+			sections[label] = cleanBlock(block[1]);
+		}
+	}
+
+	return {
+		overview: findSection(sections, ['OVERVIEW']),
+		hookStories: findSection(sections, ['HOOK STORIES', 'HOOK STORY']),
+		sections
+	};
+}
+
+/**
+ * Strip block-comment scaffolding (` * `) and trim blank edges, leaving readable prose.
+ * @param {string} inner - The text between `/*` and `*\/`.
+ * @returns {string}
+ */
+function cleanBlock(inner) {
+	const lines = inner
+		.split('\n')
+		// Drop a leading ` * ` (or bare ` *`) from each line; preserve content indentation.
+		.map((line) => line.replace(/^[ \t]*\*[ \t]?/, '').replace(/\s+$/, ''));
+
+	// Trim leading/trailing blank lines.
+	while (lines.length && lines[0] === '') lines.shift();
+	while (lines.length && lines[lines.length - 1] === '') lines.pop();
+
+	return lines.join('\n');
+}
+
+/**
+ * Case-insensitive lookup of the first matching label.
+ * @param {Record<string, string>} sections
+ * @param {string[]} candidates
+ * @returns {string | null}
+ */
+function findSection(sections, candidates) {
+	const wanted = candidates.map((c) => c.toUpperCase());
+	for (const [label, text] of Object.entries(sections)) {
+		if (wanted.includes(label.toUpperCase())) return text;
+	}
+	return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ak--47/dungeon-master",
-	"version": "1.5.1",
+	"version": "1.5.3",
 	"description": "generate fancy datasets",
 	"type": "module",
 	"main": "index.js",
@@ -107,4 +107,4 @@
 			"tmp/"
 		]
 	}
-}
+}