rockstar-strudel 1.0.0

package/PLAN.md

@@ -0,0 +1,227 @@
+# Plan: shipping `rockstar-strudel` from a RockstarLang/rockstar fork
+
+This document describes every step needed to wire the existing Starship WASM
+engine up to the `rockstar` template-tag module in this repo so that
+strudel.cc users can simply write:
+
+```js
+import { init, rockstar } from 'https://esm.sh/rockstar-strudel'
+await init('https://<your-username>.github.io/rockstar/wasm/wwwroot/_framework/dotnet.js')
+const data = await rockstar`Shout 42`
+// data === [42]
+```
+
+---
+
+## Background: why anything needs to change
+
+The Starship engine is already built and running at
+`https://codewithrockstar.com/wasm/`.  The issue is that browsers enforce the
+**Same-Origin Policy**: a page on `strudel.cc` cannot load a JS/WASM module
+from `codewithrockstar.com` unless that server explicitly opts in via a CORS
+header (`Access-Control-Allow-Origin: *`).
+
+`codewithrockstar.com` uses a **custom domain**, which means CORS headers must
+be configured at the CDN/DNS level (e.g. Cloudflare) by the site owner — a
+change that can't be made via a GitHub PR to the repo.
+
+However, **GitHub Pages on `*.github.io` domains serves all static assets with
+`Access-Control-Allow-Origin: *` built in**, at no extra configuration cost.
+This means a fork of the repo deployed to GitHub Pages at its default
+`<you>.github.io/rockstar` URL has CORS working immediately, with no CDN
+setup needed.
+
+The complete build pipeline (`.NET` WASM compile → Jekyll site build →
+GitHub Pages deploy) is already automated in the repo's GitHub Actions
+workflows, so enabling it on a fork is a matter of enabling Pages in the
+fork's settings.
+
+---
+
+## Option A — Fork and host on GitHub Pages (unblocked today)
+
+This is the fastest path. No CDN, no Cloudflare, no extra accounts needed.
+
+### Step 1 — Fork `RockstarLang/rockstar`
+
+Fork it on GitHub (keep it **public** so the free GitHub Pages tier is
+available).
+
+### Step 2 — Enable GitHub Pages on the fork
+
+1. Go to your fork → **Settings → Pages**
+2. Under *Build and deployment*, set Source to **GitHub Actions**
+   (not a branch — the workflow handles deployment itself)
+3. Save.
+
+### Step 3 — Trigger the first build
+
+The build pipeline is three chained workflows:
+
+```
+build-rockstar-2.0
+  └─► release-rockstar-engine
+        └─► build-and-deploy-codewithrockstar.com  →  GitHub Pages
+```
+
+Trigger the first one manually:
+- Go to **Actions → build-rockstar-2.0 → Run workflow** (pick `main`)
+
+This will:
+1. Build the Starship .NET engine and run its tests
+2. Compile the WASM with `dotnet publish Starship/Rockstar.Wasm -c Release`
+3. Copy the WASM into the Jekyll site and deploy it to GitHub Pages
+
+After a few minutes your site will be live at:
+```
+https://<your-username>.github.io/rockstar/
+```
+
+And the WASM loader will be at:
+```
+https://<your-username>.github.io/rockstar/wasm/wwwroot/_framework/dotnet.js
+```
+
+### Step 4 — Point `rockstar-strudel` at your fork
+
+Update `DEFAULT_DOTNET_URL` in `src/index.js`:
+
+```js
+const DEFAULT_DOTNET_URL =
+  'https://<your-username>.github.io/rockstar/wasm/wwwroot/_framework/dotnet.js';
+```
+
+Or leave the default pointing at `codewithrockstar.com` and let users pass
+their own URL via `init()`:
+
+```js
+await init('https://<your-username>.github.io/rockstar/wasm/wwwroot/_framework/dotnet.js')
+```
+
+### Step 5 — Publish the npm package
+
+```bash
+cd rockstar-strudel
+npm publish --access public
+```
+
+Users can then import from `https://esm.sh/rockstar-strudel`.
+
+---
+
+## Option B — PR / issue to `RockstarLang/rockstar` (long-term fix)
+
+A PR to the repo **cannot** fix CORS for the custom domain by itself — that
+change must be made in the Cloudflare (or equivalent CDN) dashboard by the
+site owner.  The most useful thing you can do is:
+
+1. **Open an issue** explaining the strudel.cc use case and asking them to add
+   `Access-Control-Allow-Origin: *` to the `/wasm/` path in their CDN config.
+   A single Cloudflare Transform Rule would fix it permanently for all users.
+
+2. Optionally include a **PR that adds a `_headers` file** as a signal of
+   intent (it has no effect on a custom domain, but documents the desired
+   config):
+
+   ```
+   # codewithrockstar.com/_headers
+   /wasm/*
+     Access-Control-Allow-Origin: *
+   ```
+
+Once the upstream site adds the header, update `DEFAULT_DOTNET_URL` back to
+`https://codewithrockstar.com/wasm/wwwroot/_framework/dotnet.js` so users
+get the canonical URL by default.
+
+---
+
+## Summary
+
+| Path | Works today? | Effort |
+|---|---|---|
+| Fork → GitHub Pages (Option A) | ✅ Yes, ~20 min | Fork + enable Pages + trigger build |
+| PR/issue to upstream (Option B) | ⏳ Depends on maintainer | Low effort, uncertain timeline |
+
+**Do both**: use Option A to unblock yourself right now, open an upstream
+issue (Option B) so the permanent fix lands in `codewithrockstar.com`.
+
+---
+
+## Local smoke-test (optional but recommended)
+
+To verify `src/index.js` against a local WASM build before publishing:
+
+### Build the WASM locally
+
+You need the **.NET 9 SDK** (`dotnet --version` should show `9.x`).
+
+```bash
+cd Starship
+dotnet workload install wasm-tools
+dotnet publish Rockstar.Wasm -c Release -o ../wasm-publish
+```
+
+The output in `../wasm-publish/wwwroot/` contains:
+
+```
+_framework/
+  dotnet.js               ← the JS loader
+  dotnet.native.js
+  dotnet.runtime.js
+  dotnet.wasm             ← the .NET runtime (~7 MB, AOT-compiled in Release)
+  Rockstar.Wasm.wasm      ← the Rockstar engine
+```
+
+### Run the integration test
+
+Create a minimal HTML file in the same directory as the WASM:
+
+```html
+<!-- wasm-publish/wwwroot/test.html -->
+<script type="module">
+  import { init, rockstar } from '/path/to/rockstar-strudel/src/index.js'
+
+  // localhost is in the allowed URL list, so no allowlist update needed
+  await init('http://localhost:8080/_framework/dotnet.js')
+
+  const result = 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.
+  `
+  console.assert(JSON.stringify(result) === '[123,456,789]',
+    'Expected [123,456,789], got ' + JSON.stringify(result))
+  document.body.textContent = JSON.stringify(result)
+</script>
+```
+
+Serve from localhost (same origin as the WASM avoids CORS entirely):
+
+```bash
+cd wasm-publish/wwwroot
+npx serve -p 8080
+# open http://localhost:8080/test.html
+```
+
+---
+
+## Summary checklist
+
+- [ ] Fork `RockstarLang/rockstar` on GitHub (keep public)
+- [ ] Fork Settings → Pages → Source: **GitHub Actions**
+- [ ] Actions → `build-rockstar-2.0` → **Run workflow** (triggers the full chain)
+- [ ] Wait for Pages deployment; note your URL: `https://<you>.github.io/rockstar/`
+- [ ] Update `DEFAULT_DOTNET_URL` in `src/index.js` to your fork's WASM URL
+      (or let users pass it to `init()`)
+- [ ] `npm publish --access public` the `rockstar-strudel` package
+- [ ] Verify in strudel.cc:
+      ```js
+      import { init, rockstar } from 'https://esm.sh/rockstar-strudel'
+      await init('https://<you>.github.io/rockstar/wasm/wwwroot/_framework/dotnet.js')
+      const data = await rockstar`Shout 42`   // [42]
+      ```
+- [ ] Open an issue on `RockstarLang/rockstar` asking them to add
+      `Access-Control-Allow-Origin: *` to `/wasm/` at their CDN level, so
+      the default URL can eventually point back at `codewithrockstar.com`
+

package/README.md

@@ -0,0 +1,123 @@
+# rockstar-strudel
+
+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`.
+
+---
+
+## Using it in strudel.cc
+
+```js
+import { init, rockstar } from 'https://esm.sh/rockstar-strudel'
+
+// Pre-warm the WASM engine while other code loads (optional but recommended)
+await init()
+
+// Run a Rockstar program
+const notes = await rockstar`
+  Tommy was 60
+  Build Tommy up, up, up, up
+  Shout Tommy
+  Build Tommy up
+  Shout Tommy
+  Build Tommy up, up
+  Shout Tommy
+`
+// notes === [64, 65, 67]
+
+note(notes).sound("piano").slow(2)
+```
+
+### Template interpolations
+
+JavaScript values can be spliced into the source, letting you parameterise
+programs from strudel patterns:
+
+```js
+const root = 60
+const data = await rockstar`
+  Tommy was ${root}
+  Build Tommy up, up, up, up
+  Shout Tommy
+`
+// data === [64]
+```
+
+---
+
+## API
+
+### `rockstar(strings, ...values)` → `Promise<Array<number|string>>`
+
+Tagged-template function.  Runs the Rockstar source code and resolves with an
+array of every printed value.
+
+### `init([dotnetUrl])` → `Promise<void>`
+
+Pre-loads the WASM engine.  Optionally accepts a custom `dotnet.js` URL (see
+[PLAN.md](PLAN.md) for hosting your own copy with CORS headers).
+
+### `buildSource(strings, ...values)` → `string`
+
+Pure helper that reconstructs the full source string from a tagged-template
+call.  Exported for testing.
+
+### `coerce(line)` → `number | string | undefined`
+
+Pure helper that converts a raw WASM callback line to a typed JS value.
+Exported for testing.
+
+---
+
+## How it works
+
+The Rockstar **Starship** engine is a .NET 9 application compiled to
+WebAssembly.  The built WASM is hosted at
+`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
+`[JSExport]`'d from C#.
+
+Each call to `Say`/`Shout`/`Scream`/`Whisper` in the Rockstar program triggers
+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`.
+
+---
+
+## CORS requirement
+
+`codewithrockstar.com` must serve its `/wasm/` assets with the header
+
+```
+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.
+
+---
+
+## Development
+
+```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

@@ -0,0 +1,31 @@
+{
+  "name": "rockstar-strudel",
+  "version": "1.0.0",
+  "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",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stretchyboy/rockstar-strudel.git"
+  },
+  "keywords": [
+    "rockstar",
+    "strudel",
+    "live-coding",
+    "music",
+    "wasm",
+    "template-tag"
+  ],
+  "author": "",
+  "license": "AGPL-3.0",
+  "bugs": {
+    "url": "https://github.com/stretchyboy/rockstar-strudel/issues"
+  },
+  "homepage": "https://github.com/stretchyboy/rockstar-strudel#readme"
+}

package/src/index.js

@@ -0,0 +1,210 @@
+/**
+ * rockstar-strudel
+ *
+ * Runs Rockstar lang programs via the Starship WebAssembly engine and returns
+ * each printed value as an element of a JavaScript array, for use in the
+ * strudel.cc live-coding REPL.
+ *
+ * Quick start in strudel.cc
+ * ─────────────────────────
+ *   import { rockstar } from 'https://esm.sh/rockstar-strudel'
+ *
+ *   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]
+ *
+ * CORS requirement
+ * ────────────────
+ * The WASM engine is loaded from https://codewithrockstar.com/wasm/.
+ * 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. */
+const DEFAULT_DOTNET_URL =
+  'https://codewithrockstar.com/wasm/wwwroot/_framework/dotnet.js';
+
+/**
+ * URL prefixes that are considered safe for loading the dotnet.js WASM
+ * runtime.  Calls to `init()` with a URL that does not start with one of
+ * these prefixes (or match the github.io pattern) are rejected to prevent
+ * loading arbitrary remote code.
+ * Extend this list if you host the WASM yourself on a trusted CDN.
+ */
+export const ALLOWED_URL_PREFIXES = [
+  'https://codewithrockstar.com/',
+  'https://cdn.jsdelivr.net/',
+  'https://unpkg.com/',
+  'http://localhost:',
+  'http://127.0.0.1:',
+];
+
+/** github.io subdomains (e.g. username.github.io) are also trusted. */
+export const GITHUB_IO_PATTERN = /^https:\/\/[^.]+\.github\.io\//;
+
+/**
+ * Returns true if the given dotnetUrl is trusted for WASM loading.
+ * Exported for testing.
+ * @param {string} url
+ * @returns {boolean}
+ */
+export function isTrustedUrl(url) {
+  return (
+    ALLOWED_URL_PREFIXES.some((prefix) => url.startsWith(prefix)) ||
+    GITHUB_IO_PATTERN.test(url)
+  );
+}
+
+/**
+ * The single cached promise that resolves to the RockstarRunner export object.
+ * Kept at module scope so the WASM runtime is initialised at most once per
+ * page/worker load.
+ * @type {Promise<object> | null}
+ */
+let _runnerPromise = null;
+
+/**
+ * Pre-load the Rockstar WASM engine.
+ *
+ * Called automatically on the first use of the `rockstar` tag, but you can
+ * call it earlier to eliminate the cold-start delay on the first program run.
+ *
+ * @param {string} [dotnetUrl]
+ *   Override the dotnet.js loader URL.
+ *   Useful when you host the WASM assets yourself (e.g. after following the
+ *   steps in PLAN.md to add CORS headers to your own rockstar fork deployment).
+ *   Defaults to DEFAULT_DOTNET_URL.
+ * @returns {Promise<void>}
+ */
+export async function init(dotnetUrl) {
+  if (!_runnerPromise) {
+    _runnerPromise = _loadRunner(dotnetUrl ?? DEFAULT_DOTNET_URL);
+  }
+  await _runnerPromise;
+}
+
+/**
+ * Internal: dynamically import the dotnet.js WASM loader, initialise the
+ * .NET runtime, and return the JSExport'd RockstarRunner object.
+ *
+ * dotnet.js resolves all sibling WASM/assembly blobs relative to its own URL,
+ * so as long as the hosting origin sets CORS headers the runtime loads without
+ * any additional configuration.
+ *
+ * @param {string} dotnetUrl
+ * @returns {Promise<object>}  Resolves to `exports.Rockstar.Wasm.RockstarRunner`
+ */
+async function _loadRunner(dotnetUrl) {
+  if (!isTrustedUrl(dotnetUrl)) {
+    throw new Error(
+      `Untrusted dotnet.js URL: "${dotnetUrl}". ` +
+        `Must start with one of: ${ALLOWED_URL_PREFIXES.join(', ')} ` +
+        `or be a *.github.io URL. ` +
+        `Add your CDN prefix to ALLOWED_URL_PREFIXES in src/index.js if needed.`
+    );
+  }
+  // eslint-disable-next-line no-eval -- dynamic import from a runtime URL
+  const { dotnet } = await import(/* webpackIgnore: true */ dotnetUrl);
+  const { getAssemblyExports, getConfig } = await dotnet
+    .withDiagnosticTracing(false)
+    .create();
+  const config = getConfig();
+  const exports = await getAssemblyExports(config.mainAssemblyName);
+  return exports.Rockstar.Wasm.RockstarRunner;
+}
+
+/**
+ * Return the cached runner promise, initialising with the default URL if
+ * `init()` has not been called yet.
+ * @returns {Promise<object>}
+ */
+function _runner() {
+  if (!_runnerPromise) _runnerPromise = _loadRunner(DEFAULT_DOTNET_URL);
+  return _runnerPromise;
+}
+
+/**
+ * Coerce a single raw output line (as delivered by the WASM callback) to a
+ * typed JavaScript value.
+ *
+ * - Trailing `\r\n` / `\n` (added by `WasmIO.WriteLine` in C#) is stripped.
+ * - Blank lines after stripping are ignored (returns `undefined`).
+ * - Finite numbers are returned as JS `number`.
+ * - Everything else is returned as a `string`.
+ *
+ * @param {string} line  Raw callback argument from the WASM engine.
+ * @returns {number | string | undefined}
+ */
+export function coerce(line) {
+  const trimmed = line.trimEnd();
+  if (trimmed === '') return undefined;
+  const num = Number(trimmed);
+  return Number.isFinite(num) ? num : trimmed;
+}
+
+/**
+ * Build the full Rockstar source string from a tagged-template call's parts.
+ *
+ * Template interpolations are stringified and spliced in, so you can
+ * parameterise programs:
+ *
+ *   const n = 10;
+ *   await rockstar`Tommy was ${n}\nShout Tommy`
+ *   // equivalent to running:  Tommy was 10 \n Shout Tommy
+ *
+ * @param {TemplateStringsArray} strings
+ * @param {...*} values
+ * @returns {string}
+ */
+export function buildSource(strings, ...values) {
+  return strings.reduce((acc, str, i) => {
+    const interpolated = values[i - 1];
+    return acc + (interpolated !== undefined ? String(interpolated) : '') + str;
+  });
+}
+
+/**
+ * Template tag that executes a Rockstar program and returns an array of every
+ * value printed by the program (via `Say` / `Shout` / `Scream` / `Whisper`).
+ *
+ * Values that parse as finite numbers are returned as JS `number`; everything
+ * else is returned as a `string`.
+ *
+ * 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.
+ *
+ * @example
+ * 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]
+ *
+ * @param {TemplateStringsArray} strings
+ * @param {...*} values
+ * @returns {Promise<Array<number|string>>}
+ */
+export async function rockstar(strings, ...values) {
+  const code = buildSource(strings, ...values);
+  const runner = await _runner();
+  const outputs = [];
+
+  await runner.Run(
+    code,
+    (line) => {
+      const value = coerce(line);
+      if (value !== undefined) outputs.push(value);
+    },
+    /* stdin */ '',
+    /* args  */ ''
+  );
+
+  return outputs;
+}