rockstar-strudel 1.0.3 → 1.0.7

package/PUBLISH.md

@@ -0,0 +1,102 @@
+# Publishing rockstar-strudel to npm
+
+This package is ready to publish from the repo root.
+
+## 1. Log in to npm
+
+```bash
+npm login
+```
+
+If you already have a token-based setup, make sure you are logged in as the correct account:
+
+```bash
+npm whoami
+```
+
+---
+
+## 2. Run the tests
+
+From the project root:
+
+```bash
+npm test
+```
+
+You already verified the suite is passing.
+
+---
+
+## 3. Bump the version
+
+Current version is the one in [package.json](package.json).
+
+For a patch release:
+
+```bash
+npm version patch
+```
+
+For a minor release:
+
+```bash
+npm version minor
+```
+
+For a major release:
+
+```bash
+npm version major
+```
+
+This updates the version and creates a git tag.
+
+---
+
+## 4. Preview what will be published
+
+```bash
+npm pack --dry-run
+```
+
+Check that only the expected files are included.
+
+---
+
+## 5. Publish to npm
+
+```bash
+npm publish
+```
+
+If you ever need public access explicitly:
+
+```bash
+npm publish --access public
+```
+
+---
+
+## 6. Push git commits and tags
+
+```bash
+git push && git push --tags
+```
+
+---
+
+## Handy one-release flow
+
+```bash
+npm test && npm version patch && npm publish && git push && git push --tags
+```
+
+---
+
+## Notes
+
+- Package name: `rockstar-strudel`
+- Entry point: [src/index.js](src/index.js)
+- npm metadata is defined in [package.json](package.json)
+- If `npm publish` fails because the version already exists, bump the version and try again.

package/README.md

@@ -4,29 +4,19 @@ Run [Rockstar](https://codewithrockstar.com) programs from the
 [strudel.cc](https://strudel.cc) live-coding REPL (or any browser-based JS
 environment) via a simple template-tag function.
 
-```js
-const data = await rockstar`
-  My heart is 123
-  Let your love be 456
-  Put 789 into the night
-  Shout my heart. Scream your love. Whisper the night.
-`
-// data === [123, 456, 789]
-```
-
 Every value printed by `Say` / `Shout` / `Scream` / `Whisper` becomes one
-element of the returned array.  Values that parse as finite numbers are
-returned as JS `number`; everything else is returned as a `string`.
+element of the returned array. The default `rockstar` view is now
+numeric-first, so printed text is converted using Rockstar's poetic numeric
+literal rules when needed.
+
+For richer workflows (lyrics/text + numeric pipelines), use `rockstar_pro`.
 
 ---
 
 ## Using it in strudel.cc
 
-This package is ESM-only. In `strudel.cc`, use dynamic `import()` rather than
-static `import ... from`, since the editor input is not a module file.
-
 ```js
-const { init, rockstar } = await import('https://esm.sh/rockstar-strudel')
+const { init, rockstar, rockstar_pro } = await import('https://esm.sh/rockstar-strudel')
 
 // Pre-warm the WASM engine while other code loads (optional but recommended)
 await init()
@@ -34,36 +24,58 @@ await init()
 // Run a Rockstar program
 const notes = await rockstar`
   Tommy was 60
+  Say Tommy
   Build Tommy up, up, up, up
-  Shout Tommy
+  Say Tommy
   Build Tommy up
   Shout Tommy
   Build Tommy up, up
-  Shout Tommy
+  Scream Tommy
 `
-// notes === [64, 65, 67]
+//notes === [60, 64, 65, 67]
 
-note(notes).sound("piano").slow(2)
-```
+note(seq(notes)).sound("piano")
+
+// Rich result with parallel views
+const pro = await rockstar_pro`
+  Say hello world
+  Shout [ "012", ["my dreams", "007"] ]
+`
+
+// Default numeric-first values for number-based Strudel functions
+// pro.output === [55, [12, [26, 7]]]
 
-Standalone browser example:
+// Mixed typed values with words preserved where possible
+// pro.mixed_output === ["hello world", [12, ["my dreams", 7]]]
 
-```html
-<script type="module">
-  import { init, rockstar } from 'https://esm.sh/rockstar-strudel'
+// Fully stringified values for speech/text workflows
+// pro.text_output === ["hello world", ["12", ["my dreams", "7"]]]
 
-  await init()
+// Sanitized source tokens for Shaba/Shabda speech sample names
+// pro.speech === ["say_hello_world", "shout__012_my_dreams_007_"]
+// Use in Strudel as:
+// samples('shabda/speech:'+pro.speech.join(','))
 
-  const notes = await rockstar`
-    Tommy was 60
-    Build Tommy up, up, up, up
-    Shout Tommy
-  `
+// Raw callback lines from WASM
+// pro.raw_output keeps trailing newlines exactly as emitted
 
-  console.log(notes)
-</script>
+// Exact source text executed (after template interpolation)
+// pro.sourceText is available for lyric reuse
+
+const root = 60
+const melody = await rockstar_pro`
+  Tommy was ${root}
+  Build Tommy up, up, up, up
+  Shout Tommy
+`
+
+// Run the same template again with new interpolation values
+const shifted = await melody.rerun(62)
+// or derive from the previous interpolation array
+const shiftedAgain = await shifted.rerun(([prevRoot]) => [prevRoot + 2])
 ```
 
+
 ### Template interpolations
 
 JavaScript values can be spliced into the source, letting you parameterise
@@ -83,10 +95,31 @@ const data = await rockstar`
 
 ## API
 
-### `rockstar(strings, ...values)` → `Promise<Array<number|string>>`
+### `rockstar(strings, ...values)` → `Promise<Array<number|Array>>`
+
+Tagged-template function. Runs the Rockstar source code and resolves with the
+numeric-first output view, ready for number-based Strudel functions.
+
+### `rockstar_pro(strings, ...values)` → `Promise<object>`
+
+Tagged-template function with richer parallel output views:
+
+- `sourceText`: exact Rockstar code that was executed.
+- `raw_output`: raw callback lines from WASM (verbatim, including trailing newlines).
+- `output`: numeric-first values (`number` or nested numeric arrays).
+- `mixed_output`: mixed typed values with words preserved.
+- `text_output`: fully stringified values for text/speech use.
+- `speech`: sanitized line tokens derived from source code for Shabda speech
+  sample lookup (for example `samples('shabda/speech:'+prog.speech.join(','))`).
+- `templateValues`: the interpolation values used for this run.
+- `rerun(...values)`: run the same template again, replacing interpolation
+  values positionally. Calling `rerun()` with no arguments repeats the same run.
 
-Tagged-template function.  Runs the Rockstar source code and resolves with an
-array of every printed value.
+`output[i]`, `mixed_output[i]`, and `text_output[i]` always refer to the same
+emitted line.
+
+For JSON-style list output (for example `[ "012" ]`), all views parse the same
+structure, and `output` resolves that case to `[12]`.
 
 ### `init([dotnetUrl])` → `Promise<void>`
 
@@ -103,12 +136,24 @@ call.  Exported for testing.
 Pure helper that converts a raw WASM callback line to a typed JS value.
 Exported for testing.
 
+### `parsePoeticNumber(text)` → `number | undefined`
+
+Converts text using the Rockstar poetic numeric literal algorithm:
+each word contributes one digit using its length modulo 10, hyphens count as
+letters, apostrophes do not, statement-ending punctuation stops parsing, and
+an ellipsis (`...` or `…`) introduces the decimal separator.
+
+### `parseOutputLine(line)` → `object | undefined`
+
+Parses one raw callback line into a dual-view structure used by
+`rockstar_pro` (`raw`, `output`, `poetic`). Exported for testing.
+
 ---
 
 ## How it works
 
 The Rockstar **Starship** engine is a .NET 9 application compiled to
-WebAssembly.  The built WASM is hosted at
+WebAssembly.  The built WASM is hosted at `https://stretchyboy.github.io/rockstar/wasm` instead of
 `https://codewithrockstar.com/wasm/`.  This package dynamically imports
 `dotnet.js` from that URL, initialises the runtime, and calls
 `RockstarRunner.Run(source, outputCallback, stdin, args)`, which is
@@ -119,6 +164,14 @@ the callback with the printed string (plus a trailing newline added by
 `WasmIO.WriteLine` in C#).  The tag strips whitespace and coerces numeric
 strings to `number`.
 
+`rockstar_pro` adds a parsing layer on top of that callback stream:
+
+- JSON-style lists are parsed when possible.
+- List members are converted recursively.
+- `output` is numeric-ready for sequence/math pipelines.
+- `mixed_output` preserves words while keeping numbers typed.
+- `text_output` keeps everything stringified for speech/lyrics workflows.
+
 ---
 
 ## CORS requirement
@@ -130,7 +183,6 @@ Access-Control-Allow-Origin: *
 ```
 
 Without this, browsers will block the cross-origin `import()` of `dotnet.js`.
-See [PLAN.md](PLAN.md) for the exact steps needed in the rockstar fork.
 
 ---
 
@@ -139,6 +191,3 @@ See [PLAN.md](PLAN.md) for the exact steps needed in the rockstar fork.
 ```bash
 npm test        # run the 19 unit tests (pure JS logic, no WASM required)
 ```
-
-Integration testing (actual Rockstar program execution) requires a browser
-environment where the WASM can load; see [PLAN.md](PLAN.md) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rockstar-strudel",
-  "version": "1.0.3",
+  "version": "1.0.7",
   "description": "Run Rockstar lang programs via the Starship WASM engine, returning output as a JS array. Designed for use in the strudel.cc live-coding REPL.",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -19,13 +19,13 @@
  *
  * CORS requirement
  * ────────────────
- * The WASM engine is loaded from https://codewithrockstar.com/wasm/.
+ * The WASM engine is loaded from https://stretchyboy.github.io/rockstar/ as https://codewithrockstar.com/wasm/ has broken CORS.
  * That origin must serve its WASM assets with
  *   Access-Control-Allow-Origin: *
  * See PLAN.md for instructions on enabling this in a rockstar fork.
  */
 
-/** Default URL of the .NET WASM loader published by codewithrockstar.com. */
+/** Default URL of the .NET WASM loader published by stretchyboy.github.io. */
 const DEFAULT_DOTNET_URL =
   'https://stretchyboy.github.io/rockstar/wasm/wwwroot/_framework/dotnet.js';
 
@@ -38,6 +38,7 @@ const DEFAULT_DOTNET_URL =
  */
 export const ALLOWED_URL_PREFIXES = [
   'https://codewithrockstar.com/',
+  'https://stretchyboy.github.io/rockstar/',
   'https://cdn.jsdelivr.net/',
   'https://unpkg.com/',
   'http://localhost:',
@@ -170,6 +171,249 @@ export function coerce(line) {
   return Number.isFinite(num) ? num : trimmed;
 }
 
+/**
+ * Convert text to a Rockstar-style poetic numeric literal.
+ *
+ * Rockstar counts each word's length modulo 10. Hyphens count as letters,
+ * apostrophes do not. Parsing stops at the end of the current statement
+ * (`.`, `!`, `?`, `;`, or a newline). An ellipsis (`...` or `…`) acts as the
+ * decimal separator.
+ *
+ * Examples:
+ * - "a panther, he ain't talkin' 'bout love." -> 1724644
+ * - "ice... a life unfulfilled" -> 3.141
+ *
+ * @param {string} text
+ * @returns {number | undefined}
+ */
+export function parsePoeticNumber(text) {
+  const source = String(text).replace(/…/g, '...');
+  const intDigits = [];
+  const fracDigits = [];
+  let currentWord = '';
+  let sawDecimal = false;
+
+  const pushWord = () => {
+    if (!currentWord) return;
+
+    const normalized = currentWord.replace(/'/g, '');
+    currentWord = '';
+    if (!normalized) return;
+
+    const digit = normalized.length % 10;
+    if (sawDecimal) {
+      fracDigits.push(String(digit));
+    } else {
+      intDigits.push(String(digit));
+    }
+  };
+
+  for (let i = 0; i < source.length; i += 1) {
+    const char = source[i];
+
+    if (source.slice(i, i + 3) === '...') {
+      pushWord();
+      sawDecimal = true;
+      i += 2;
+      continue;
+    }
+
+    if (char === '\n' || char === '.' || char === '!' || char === '?' || char === ';') {
+      pushWord();
+      break;
+    }
+
+    if (/[\p{L}'-]/u.test(char)) {
+      currentWord += char;
+      continue;
+    }
+
+    pushWord();
+  }
+
+  pushWord();
+
+  if (intDigits.length === 0 && fracDigits.length === 0) return undefined;
+
+  const intPart = intDigits.length > 0 ? intDigits.join('') : '0';
+  const value =
+    fracDigits.length > 0
+      ? Number(`${intPart}.${fracDigits.join('')}`)
+      : Number(intPart);
+
+  return Number.isFinite(value) ? value : undefined;
+}
+
+/**
+ * Parse a single output line into the parallel views used by `rockstar_pro`.
+ *
+ * - `output` is numeric-first for Strudel number pipelines.
+ * - `mixed_output` preserves words while keeping numeric values typed.
+ * - `text_output` keeps the same shape but stringifies all values.
+ *
+ * @param {string} line
+ * @returns {{
+ *   raw: string,
+ *   output: number|Array<number|Array<unknown>>,
+ *   mixed_output: number|string|Array<unknown>,
+ *   text_output: string|Array<unknown>
+ * } | undefined}
+ */
+export function parseOutputLine(line) {
+  const raw = line;
+  const trimmed = line.trimEnd();
+  if (trimmed === '') return undefined;
+
+  const parsedArray = _parseJsonArray(trimmed);
+  if (parsedArray !== undefined) {
+    const mixed_output = _toMixedArray(parsedArray);
+    const text_output = _toTextArray(mixed_output);
+    const output = _toPoeticArray(parsedArray);
+    return { raw, output, mixed_output, text_output };
+  }
+
+  const mixed_output = coerce(trimmed);
+  const text_output = _toTextValue(mixed_output);
+  const output = _toPoeticNumber(mixed_output);
+  return { raw, output, mixed_output, text_output };
+}
+
+/**
+ * Attempt to parse a JSON-style array string, otherwise return undefined.
+ * @param {string} text
+ * @returns {Array<unknown> | undefined}
+ */
+function _parseJsonArray(text) {
+  const startsLikeArray = text.startsWith('[') && text.endsWith(']');
+  if (!startsLikeArray) return undefined;
+
+  try {
+    const parsed = JSON.parse(text);
+    return Array.isArray(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Convert any parsed array value into mixed output values.
+ * Numeric-looking strings become numbers; other strings stay as text.
+ *
+ * @param {Array<unknown>} value
+ * @returns {Array<unknown>}
+ */
+function _toMixedArray(value) {
+  return value.map((item) => {
+    if (Array.isArray(item)) return _toMixedArray(item);
+    if (typeof item === 'string') {
+      const numeric = _parseNumberish(item);
+      return numeric !== undefined ? numeric : item;
+    }
+    return item;
+  });
+}
+
+/**
+ * Convert a value tree to text output values.
+ * Numbers and other scalars are stringified while preserving array shape.
+ *
+ * @param {unknown} value
+ * @returns {string|Array<unknown>}
+ */
+function _toTextValue(value) {
+  if (Array.isArray(value)) return _toTextArray(value);
+  if (typeof value === 'string') return value;
+  return String(value);
+}
+
+/**
+ * Convert any parsed array value into text output values.
+ *
+ * @param {Array<unknown>} value
+ * @returns {Array<unknown>}
+ */
+function _toTextArray(value) {
+  return value.map((item) => _toTextValue(item));
+}
+
+/**
+ * Convert any parsed array value into numeric-first output values.
+ * Output is strictly numbers or nested arrays of numbers.
+ *
+ * @param {Array<unknown>} value
+ * @returns {Array<number|Array<unknown>>}
+ */
+function _toPoeticArray(value) {
+  return value.map((item) => {
+    if (Array.isArray(item)) return _toPoeticArray(item);
+    return _toPoeticNumber(item);
+  });
+}
+
+/**
+ * Convert a single scalar value to a number using numeric parse first,
+ * then Rockstar poetic numeric literal parsing.
+ *
+ * @param {unknown} value
+ * @returns {number}
+ */
+function _toPoeticNumber(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'boolean') return value ? 1 : 0;
+  if (value === null) return 0;
+
+  if (typeof value === 'string') {
+    const numeric = _parseNumberish(value);
+    if (numeric !== undefined) return numeric;
+
+    const poetic = parsePoeticNumber(value);
+    return poetic !== undefined ? poetic : 0;
+  }
+
+  return 0;
+}
+
+/**
+ * Parse text as a finite JS number.
+ * @param {string} text
+ * @returns {number | undefined}
+ */
+function _parseNumberish(text) {
+  const num = Number(String(text));
+  return Number.isFinite(num) ? num : undefined;
+}
+
+/**
+ * Resolve the interpolation values for a rerun of `rockstar_pro`.
+ *
+ * - `rerun()` repeats the previous interpolation set.
+ * - `rerun(v1, v2, ...)` replaces values positionally.
+ * - `rerun([v1, v2, ...])` replaces from an array.
+ * - `rerun(fn)` derives the next values from the previous array.
+ *
+ * @param {Array<unknown>} previousValues
+ * @param {...unknown} nextArgs
+ * @returns {Array<unknown>}
+ */
+export function resolveRerunValues(previousValues, ...nextArgs) {
+  if (nextArgs.length === 0) return [...previousValues];
+
+  if (nextArgs.length === 1) {
+    const [arg] = nextArgs;
+
+    if (typeof arg === 'function') {
+      const result = arg([...previousValues]);
+      return Array.isArray(result) ? [...result] : [result];
+    }
+
+    if (Array.isArray(arg)) {
+      return [...arg];
+    }
+  }
+
+  return [...nextArgs];
+}
+
 /**
  * Build the full Rockstar source string from a tagged-template call's parts.
  *
@@ -192,11 +436,12 @@ export function buildSource(strings, ...values) {
 }
 
 /**
- * Template tag that executes a Rockstar program and returns an array of every
- * value printed by the program (via `Say` / `Shout` / `Scream` / `Whisper`).
+ * Template tag that executes a Rockstar program and returns a numeric-first
+ * array of every printed value (via `Say` / `Shout` / `Scream` / `Whisper`).
  *
- * Values that parse as finite numbers are returned as JS `number`; everything
- * else is returned as a `string`.
+ * Plain numeric strings stay numeric, and other printed text is converted
+ * using Rockstar poetic numeric literal rules. JSON-style lists are converted
+ * recursively to nested numeric arrays.
  *
  * The WASM engine is loaded lazily on the first call and cached for subsequent
  * calls.  You can call `init()` first to pre-warm the engine if desired.
@@ -212,22 +457,91 @@ export function buildSource(strings, ...values) {
  *
  * @param {TemplateStringsArray} strings
  * @param {...*} values
- * @returns {Promise<Array<number|string>>}
+ * @returns {Promise<Array<number|Array<unknown>>>}
  */
 export async function rockstar(strings, ...values) {
+  const result = await rockstar_pro(strings, ...values);
+  return result.output;
+}
+
+/**
+ * Template tag that executes Rockstar and returns richer parallel output views:
+ *
+ * - `output`: numeric-first values for Strudel sequence/math use.
+ * - `mixed_output`: mixed typed values with words preserved.
+ * - `text_output`: all values stringified for speech/text workflows.
+ * - `raw_output`: unmodified callback lines from WASM.
+ * - `sourceText`: exact source string that was executed.
+ *
+ * @param {TemplateStringsArray} strings
+ * @param {...*} values
+ * @returns {Promise<{
+ *   sourceText: string,
+ *   templateValues: Array<unknown>,
+ *   raw_output: Array<string>,
+ *   output: Array<number|Array<unknown>>,
+ *   mixed_output: Array<number|string|Array<unknown>>,
+ *   text_output: Array<string|Array<unknown>>,
+ *   speech: Array<string>, // samples('shabda/speech:'+prog.speech.join(','))
+ *   rerun: (...values: Array<unknown>) => Promise<object>,
+ *   getVariables: () => never,
+ *   callFunction: (name: string, ...args: Array<unknown>) => never,
+ *   listFunctions: () => never
+ * }>}
+ */
+export async function rockstar_pro(strings, ...values) {
   const code = buildSource(strings, ...values);
   const runner = await _runner();
-  const outputs = [];
+  const raw_output = [];
+  const output = [];
+  const mixed_output = [];
+  const text_output = [];
+  const lines = code.split('\n')
+  const speech = lines.map((x) => x.toLowerCase()
+  .trim()
+  .replaceAll(' ', '_')
+  .replace(/\W/g, ''))
+  .filter((x)=> x.length);
+
+  console.log(`samples('shabda/speech:'+prog.speech.join(','))`)
 
   await runner.Run(
     code,
     (line) => {
-      const value = coerce(line);
-      if (value !== undefined) outputs.push(value);
+      raw_output.push(line);
+
+      const parsed = parseOutputLine(line);
+      if (!parsed) return;
+
+      output.push(parsed.output);
+      mixed_output.push(parsed.mixed_output);
+      text_output.push(parsed.text_output);
     },
     /* stdin */ '',
     /* args  */ ''
   );
 
-  return outputs;
+  const unsupported = (featureName) => {
+    throw new Error(
+      `${featureName} is not available in the current JS-only wrapper. ` +
+        `It requires new JSExport methods in the WASM RockstarRunner.`
+    );
+  };
+
+  return {
+    sourceText: code,
+    templateValues: [...values],
+    raw_output,
+    output,
+    mixed_output,
+    text_output,
+    speech,
+    rerun: (...nextArgs) => {
+      const nextValues = resolveRerunValues(values, ...nextArgs);
+      return rockstar_pro(strings, ...nextValues);
+    },
+    getVariables: () => unsupported('getVariables()'),
+    callFunction: () => unsupported('callFunction()'),
+    listFunctions: () => unsupported('listFunctions()'),
+  };
 }

package/test/rockstar.test.js

@@ -9,7 +9,14 @@
 
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { buildSource, coerce, isTrustedUrl } from '../src/index.js';
+import {
+  buildSource,
+  coerce,
+  isTrustedUrl,
+  parsePoeticNumber,
+  parseOutputLine,
+  resolveRerunValues,
+} from '../src/index.js';
 
 // ─── buildSource ────────────────────────────────────────────────────────────
 
@@ -157,3 +164,125 @@ describe('isTrustedUrl', () => {
     assert.ok(!isTrustedUrl('http://codewithrockstar.com/wasm/dotnet.js'));
   });
 });
+
+// ─── parsePoeticNumber ──────────────────────────────────────────────────────
+
+describe('parsePoeticNumber', () => {
+  it('maps word lengths to digits modulo 10', () => {
+    assert.equal(parsePoeticNumber('My dreams'), 26);
+  });
+
+  it('ignores apostrophes and stops at statement punctuation', () => {
+    assert.equal(
+      parsePoeticNumber("a panther, he ain't talkin' 'bout love. Shout Tommy"),
+      1724644
+    );
+  });
+
+  it('treats an ellipsis as the decimal separator', () => {
+    assert.equal(
+      parsePoeticNumber("ice... a life unfulfilled, wakin' everybody up, taking booze and pills."),
+      3.1415926535
+    );
+  });
+
+  it('counts hyphens as letters', () => {
+    assert.equal(parsePoeticNumber('life-long.'), 9);
+  });
+
+  it('supports the unicode ellipsis character too', () => {
+    assert.equal(
+      parsePoeticNumber('my… darkest nightmarish longings, my cravings, a symphony of suff\'ring that lasts life-long.'),
+      2.718281828459
+    );
+  });
+
+  it('returns undefined when there are no words', () => {
+    assert.equal(parsePoeticNumber('!!!'), undefined);
+  });
+});
+
+// ─── parseOutputLine ────────────────────────────────────────────────────────
+
+describe('parseOutputLine', () => {
+  it('returns numeric-first output while preserving words in other views', () => {
+    const parsed = parseOutputLine('hello world\n');
+    assert.deepEqual(parsed, {
+      raw: 'hello world\n',
+      output: 55,
+      mixed_output: 'hello world',
+      text_output: 'hello world',
+    });
+  });
+
+  it('stringifies numbers in text_output', () => {
+    const parsed = parseOutputLine('123\n');
+    assert.deepEqual(parsed, {
+      raw: '123\n',
+      output: 123,
+      mixed_output: 123,
+      text_output: '123',
+    });
+  });
+
+  it('parses JSON-style lists and converts string numerals', () => {
+    const parsed = parseOutputLine('[ "012" ]\n');
+    assert.deepEqual(parsed, {
+      raw: '[ "012" ]\n',
+      output: [12],
+      mixed_output: [12],
+      text_output: ['12'],
+    });
+  });
+
+  it('keeps mixed and text views alongside numeric-first output', () => {
+    const parsed = parseOutputLine('["3", ["my dreams", "007"]]\n');
+    assert.deepEqual(parsed, {
+      raw: '["3", ["my dreams", "007"]]\n',
+      output: [3, [26, 7]],
+      mixed_output: [3, ['my dreams', 7]],
+      text_output: ['3', ['my dreams', '7']],
+    });
+  });
+
+  it('returns undefined for blank output lines', () => {
+    assert.equal(parseOutputLine('\n'), undefined);
+    assert.equal(parseOutputLine('\r\n'), undefined);
+  });
+
+  it('falls back to text in mixed/text views when malformed JSON list is printed', () => {
+    const parsed = parseOutputLine('[ nope ]\n');
+    assert.deepEqual(parsed, {
+      raw: '[ nope ]\n',
+      output: 4,
+      mixed_output: '[ nope ]',
+      text_output: '[ nope ]',
+    });
+  });
+});
+
+// ─── resolveRerunValues ────────────────────────────────────────────────────
+
+describe('resolveRerunValues', () => {
+  it('repeats the previous values when no args are provided', () => {
+    assert.deepEqual(resolveRerunValues([1, 'two', 3]), [1, 'two', 3]);
+  });
+
+  it('replaces values positionally from variadic args', () => {
+    assert.deepEqual(resolveRerunValues([1, 2, 3], 9, 8), [9, 8]);
+  });
+
+  it('replaces values from an array argument', () => {
+    assert.deepEqual(resolveRerunValues([1, 2, 3], [7, 6]), [7, 6]);
+  });
+
+  it('derives next values from a function', () => {
+    const next = resolveRerunValues([2, 4, 6], (prev) => prev.map((n) => n * 10));
+    assert.deepEqual(next, [20, 40, 60]);
+  });
+
+  it('wraps a non-array function result as a single interpolation value', () => {
+    const next = resolveRerunValues([2, 4, 6], () => 99);
+    assert.deepEqual(next, [99]);
+  });
+});

package/verify_state.ipynb

@@ -0,0 +1,203 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "e8b054ac",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\n",
+      "> rockstar-strudel@1.0.4 test\n",
+      "> node --test test/*.test.js\n",
+      "\n",
+      "▶ buildSource\n",
+      "  \u001b[32m✔ returns the raw template string when there are no interpolations \u001b[90m(0.835688ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ splices a single string interpolation \u001b[90m(0.159772ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ stringifies a numeric interpolation \u001b[90m(0.114796ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ handles multiple interpolations in the correct order \u001b[90m(0.129431ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ preserves leading and trailing whitespace / newlines in the template \u001b[90m(0.217994ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ treats undefined interpolation values as empty strings \u001b[90m(0.098519ms)\u001b[39m\u001b[39m\n",
+      "\u001b[32m✔ buildSource \u001b[90m(2.715025ms)\u001b[39m\u001b[39m\n",
+      "▶ coerce\n",
+      "  \u001b[32m✔ converts an integer string to a JS number \u001b[90m(0.608473ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ converts a decimal string to a JS number \u001b[90m(0.590633ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ converts a negative number string \u001b[90m(2.175091ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ handles Windows-style CRLF line endings \u001b[90m(0.363412ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ converts zero \u001b[90m(0.158039ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ returns a string for non-numeric output \u001b[90m(0.194609ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ returns a string for boolean-like output \u001b[90m(0.094095ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ returns a string for null-like output \u001b[90m(0.055956ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ returns undefined for an empty line \u001b[90m(0.046294ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ returns undefined for a line containing only a newline \u001b[90m(0.044543ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ does not coerce Infinity to a number (not finite) \u001b[90m(0.045679ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ does not coerce NaN to a number \u001b[90m(0.044212ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ strips multiple trailing newlines \u001b[90m(0.044264ms)\u001b[39m\u001b[39m\n",
+      "\u001b[32m✔ coerce \u001b[90m(5.028022ms)\u001b[39m\u001b[39m\n",
+      "▶ isTrustedUrl\n",
+      "  \u001b[32m✔ trusts codewithrockstar.com \u001b[90m(0.192548ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ trusts cdn.jsdelivr.net \u001b[90m(0.054461ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ trusts unpkg.com \u001b[90m(0.047384ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ trusts any *.github.io subdomain \u001b[90m(0.159751ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ trusts localhost with a port \u001b[90m(0.10433ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ trusts 127.0.0.1 with a port \u001b[90m(0.058382ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ rejects an arbitrary https URL \u001b[90m(0.090083ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ rejects a bare github.io URL without a subdomain \u001b[90m(0.054799ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ rejects http (non-localhost) \u001b[90m(0.052302ms)\u001b[39m\u001b[39m\n",
+      "\u001b[32m✔ isTrustedUrl \u001b[90m(1.01552ms)\u001b[39m\u001b[39m\n",
+      "▶ parsePoeticNumber\n",
+      "  \u001b[32m✔ maps word lengths to digits modulo 10 \u001b[90m(0.546635ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ ignores apostrophes and stops at statement punctuation \u001b[90m(0.197288ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ treats an ellipsis as the decimal separator \u001b[90m(0.099897ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ counts hyphens as letters \u001b[90m(0.057811ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ supports the unicode ellipsis character too \u001b[90m(0.076137ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ returns undefined when there are no words \u001b[90m(0.05618ms)\u001b[39m\u001b[39m\n",
+      "\u001b[32m✔ parsePoeticNumber \u001b[90m(1.207209ms)\u001b[39m\u001b[39m\n",
+      "▶ parseOutputLine\n",
+      "  \u001b[32m✔ returns numeric-first output while preserving words in other views \u001b[90m(0.870018ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ stringifies numbers in text_output \u001b[90m(0.102378ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ parses JSON-style lists and converts string numerals \u001b[90m(0.231375ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ keeps mixed and text views alongside numeric-first output \u001b[90m(0.173793ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ returns undefined for blank output lines \u001b[90m(0.097894ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ falls back to text in mixed/text views when malformed JSON list is printed \u001b[90m(0.173253ms)\u001b[39m\u001b[39m\n",
+      "\u001b[32m✔ parseOutputLine \u001b[90m(1.835256ms)\u001b[39m\u001b[39m\n",
+      "▶ resolveRerunValues\n",
+      "  \u001b[32m✔ repeats the previous values when no args are provided \u001b[90m(0.133796ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ replaces values positionally from variadic args \u001b[90m(0.06069ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ replaces values from an array argument \u001b[90m(0.3767ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ derives next values from a function \u001b[90m(0.136754ms)\u001b[39m\u001b[39m\n",
+      "  \u001b[32m✔ wraps a non-array function result as a single interpolation value \u001b[90m(0.080649ms)\u001b[39m\u001b[39m\n",
+      "\u001b[32m✔ resolveRerunValues \u001b[90m(0.943939ms)\u001b[39m\u001b[39m\n",
+      "\u001b[34mℹ tests 45\u001b[39m\n",
+      "\u001b[34mℹ suites 6\u001b[39m\n",
+      "\u001b[34mℹ pass 45\u001b[39m\n",
+      "\u001b[34mℹ fail 0\u001b[39m\n",
+      "\u001b[34mℹ cancelled 0\u001b[39m\n",
+      "\u001b[34mℹ skipped 0\u001b[39m\n",
+      "\u001b[34mℹ todo 0\u001b[39m\n",
+      "\u001b[34mℹ duration_ms 127.20622\u001b[39m\n",
+      "\n",
+      "{\"exports\":[\"ALLOWED_URL_PREFIXES\",\"GITHUB_IO_PATTERN\",\"buildSource\",\"coerce\",\"init\",\"isTrustedUrl\",\"parseOutputLine\",\"parsePoeticNumber\",\"resolveRerunValues\",\"rockstar\",\"rockstar_pro\"],\"hasRockstar\":true,\"hasRockstarPro\":true,\"parsedWordOutput\":{\"raw\":\"hello world\\n\",\"output\":55,\"mixed_output\":\"hello world\",\"text_output\":\"hello world\"},\"parsedNestedOutput\":{\"raw\":\"[\\\"3\\\", [\\\"my dreams\\\", \\\"007\\\"]]\\n\",\"output\":[3,[26,7]],\"mixed_output\":[3,[\"my dreams\",7]],\"text_output\":[\"3\",[\"my dreams\",\"7\"]]},\"rockstarReturnsStateOutput\":false,\"rockstarProExposesAliases\":true}\n",
+      "\n",
+      "\n",
+      "FINAL_VERIFICATION_JSON=\n",
+      "{\n",
+      "  \"pass_fail\": \"PASS\",\n",
+      "  \"summary_counts\": {},\n",
+      "  \"failing_tests\": [],\n",
+      "  \"rockstar_numeric_first\": false,\n",
+      "  \"rockstar_pro_aliases\": true,\n",
+      "  \"api_exports\": [\n",
+      "    \"ALLOWED_URL_PREFIXES\",\n",
+      "    \"GITHUB_IO_PATTERN\",\n",
+      "    \"buildSource\",\n",
+      "    \"coerce\",\n",
+      "    \"init\",\n",
+      "    \"isTrustedUrl\",\n",
+      "    \"parseOutputLine\",\n",
+      "    \"parsePoeticNumber\",\n",
+      "    \"resolveRerunValues\",\n",
+      "    \"rockstar\",\n",
+      "    \"rockstar_pro\"\n",
+      "  ]\n",
+      "}\n"
+     ]
+    }
+   ],
+   "source": [
+    "from pathlib import Path\n",
+    "import subprocess, json, re, textwrap\n",
+    "\n",
+    "repo = Path('/workspaces/rockstar-strudel')\n",
+    "\n",
+    "# Run the full test suite\n",
+    "proc = subprocess.run(\n",
+    "    ['npm', 'test'],\n",
+    "    cwd=repo,\n",
+    "    capture_output=True,\n",
+    "    text=True,\n",
+    ")\n",
+    "\n",
+    "output = (proc.stdout or '') + ('\\n' + proc.stderr if proc.stderr else '')\n",
+    "print(output)\n",
+    "\n",
+    "counts = {}\n",
+    "for key in ['tests', 'suites', 'pass', 'fail', 'cancelled', 'skipped', 'todo', 'duration_ms']:\n",
+    "    m = re.search(rf'#\\s+{key}\\s+(\\d+)', output)\n",
+    "    if m:\n",
+    "        counts[key] = int(m.group(1))\n",
+    "\n",
+    "failing_tests = []\n",
+    "for line in output.splitlines():\n",
+    "    stripped = line.strip()\n",
+    "    if stripped.startswith('not ok '):\n",
+    "        failing_tests.append(stripped[7:])\n",
+    "\n",
+    "node_code = r'''\n",
+    "import * as mod from './src/index.js';\n",
+    "const result = {\n",
+    "  exports: Object.keys(mod).sort(),\n",
+    "  hasRockstar: typeof mod.rockstar === 'function',\n",
+    "  hasRockstarPro: typeof mod.rockstar_pro === 'function',\n",
+    "  parsedWordOutput: mod.parseOutputLine('hello world\\n'),\n",
+    "  parsedNestedOutput: mod.parseOutputLine('[\"3\", [\"my dreams\", \"007\"]]\\n'),\n",
+    "  rockstarReturnsStateOutput: /return\\s+state\\.output\\b/.test(String(mod.rockstar)),\n",
+    "  rockstarProExposesAliases:\n",
+    "    /output/.test(String(mod.rockstar_pro)) &&\n",
+    "    /mixed_output/.test(String(mod.rockstar_pro)) &&\n",
+    "    /text_output/.test(String(mod.rockstar_pro)) &&\n",
+    "    /raw_output/.test(String(mod.rockstar_pro)),\n",
+    "};\n",
+    "console.log(JSON.stringify(result));\n",
+    "'''\n",
+    "api_proc = subprocess.run(\n",
+    "    ['node', '--input-type=module', '-e', node_code],\n",
+    "    cwd=repo,\n",
+    "    capture_output=True,\n",
+    "    text=True,\n",
+    ")\n",
+    "print(api_proc.stdout)\n",
+    "if api_proc.stderr:\n",
+    "    print(api_proc.stderr)\n",
+    "\n",
+    "api = json.loads(api_proc.stdout)\n",
+    "\n",
+    "verification = {\n",
+    "    'pass_fail': 'PASS' if proc.returncode == 0 else 'FAIL',\n",
+    "    'summary_counts': counts,\n",
+    "    'failing_tests': failing_tests,\n",
+    "    'rockstar_numeric_first': bool(api['rockstarReturnsStateOutput']) and api['parsedWordOutput']['output'] == 55,\n",
+    "    'rockstar_pro_aliases': bool(api['rockstarProExposesAliases']),\n",
+    "    'api_exports': api['exports'],\n",
+    "}\n",
+    "\n",
+    "print('\\nFINAL_VERIFICATION_JSON=')\n",
+    "print(json.dumps(verification, indent=2))"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.1"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}