From 5e5b274e4b4baac1a439a31649e40733c20cdd5c Mon Sep 17 00:00:00 2001
From: Me Here <me@here>
Date: Tue, 26 May 2026 12:09:45 -0500
Subject: [PATCH] README: document the multi-page site, page map, and embed
 widget

Rebrand the intro to the VARASYS PolyMeter site (PE-1 editor home + concepts +
hardware mockups + embeddable widget); add a Pages map, an Embedding section
with the drop-in snippet, the live program-string note, and refresh the Build
and Files sections for all pages + embed.js.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md | 90 +++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 67 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index 996a042..19ea34d 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,37 @@
-# Stackable Metronome
+# VARASYS PolyMeter
 
-A browser **polymetric groove trainer / metronome** — a full web app, and the
-reference design for a Raspberry Pi Pico hardware build (whose play‑only device is
-mocked up at [`player.html`](player.html)). Stack as many "meter lanes" as you like;
-each is its own little metronome with a grouping, subdivision, drum voice and a
-per‑step pattern with accents. Layering lanes produces polymeter and true ratio polyrhythm.
+A small **website** built around one **polymetric groove trainer / metronome** engine.
+The home page is the **PE‑1 PolyMeter Editor** — a full web app where you stack as many
+"meter lanes" as you like; each is its own little metronome with a grouping, subdivision,
+drum voice and a per‑step pattern with accents. Layering lanes produces polymeter and true
+ratio polyrhythm. The same engine drives an ever‑expanding library of **form‑factor concepts**
+(idealized and buildable hardware mockups) and ships as an **embeddable widget** anyone can
+drop into their own page.
 
 **Live:** https://metronome.varasys.io · **Source:** https://codeberg.org/VARASYS/metronome
 
-The **deployed page is a single, self‑contained `index.html`** — **zero dependencies**:
-no framework, no CDN libraries, nothing fetched at runtime. It's assembled by a small
-build step (`build.sh`) that inlines the audio samples + brand assets (kept in `assets/`)
-into the HTML, so the source stays lean. State (set lists, the practice log, theme and
-UI preferences) lives in `localStorage`.
+Every **deployed page is a single, self‑contained `.html` file** — **zero dependencies**:
+no framework, no CDN libraries, nothing fetched at runtime. They're assembled by a small
+build step (`build.sh`) that inlines a shared engine, the seed set lists, base styling and
+the audio samples + brand assets (kept in `assets/`) into each page, so the sources stay lean.
+State (set lists, the practice log, theme and UI preferences) lives in `localStorage`.
+
+## Pages
+
+| URL | What |
+|-----|------|
+| [`/`](https://metronome.varasys.io/) `index.html` | **PE‑1 — PolyMeter Editor** (home / main app) |
+| `/concepts.html` | **PolyMeter Concepts** — the form‑factor gallery (cards → live page + info) |
+| `/player.html` | **PM‑1 Initial** — idealized concept device (full display + set‑list nav, theme, fullscreen "stage" view) |
+| `/stage.html` | **PM‑1 Stage** — pedalboard build (colour TFT, arcade buttons, 1/4″ instrument pass‑through with analog click injection) |
+| `/micro.html` | **PM‑µ Micro** — minimal home‑practice unit (one push scroll‑encoder + 7‑segment LED) |
+| `/info-editor.html`, `/info-initial.html` | purpose pages (web app / concept — no BOM) |
+| `/info-stage.html`, `/info-micro.html` | purpose **+ priced BOM** (buildable hardware only) |
+| `/embed.html` · `/embed.js` | embed docs and the drop‑in loader |
+
+Each page carries the same VARASYS header (logo + tagline, nav, theme toggle). The editor
+also shows a subtle live **program string** of what's loaded — editable, with copy/paste —
+under the app (press `Enter` or paste to apply; see [the share language](#the-share-language)).
 
 Because nothing loads from the network, you can save the page (`Ctrl`/`⌘`+`S`) and
 open it straight from disk to run fully offline. One catch from a local `file://`:
@@ -119,6 +138,27 @@ In the set‑list panel's **⋯** menu:
 - **Export all / Import file** back up your set lists and practice log as a JSON
   file (a legacy `presets` field is included for backward compatibility).
 
+## Embedding
+
+Any form factor can be embedded in another page as a self‑sizing widget. Drop in a
+container and the loader script — it builds an `<iframe>` to the chrome‑stripped
+(`?embed=1`) page, preloads your config string, and auto‑resizes to the content:
+
+```html
+<div data-varasys-metronome="micro"
+     data-patch="v1;t120;kick:4;snare:4=.X.X;hatClosed:4/2"></div>
+<script src="https://metronome.varasys.io/embed.js"></script>
+```
+
+- `data-varasys-metronome` — variant: `editor` · `initial` · `stage` · `micro`.
+- `data-patch` — a [patch string](#patch-grammar) (maps to `#p=`); or `data-setlist`
+  for a set‑list code (maps to `#sl=`).
+- `data-width` / `data-height` — optional initial size (default `100%` × `300px`;
+  height then tracks the widget, which posts `{type:'varasys-h', h}` to the parent).
+
+Prefer your own iframe? `…/<variant>.html?embed=1#p=<patch>` works directly. Our own
+[`info-*.html`](info-stage.html) pages dogfood this exact mechanism. See `/embed.html`.
+
 ## Keyboard shortcuts
 
 | Key | Action |
@@ -158,20 +198,21 @@ disturbing what's playing, then commit on a musical boundary — no audible gap.
 
 ## Build
 
-`index.html` (the editor) and `player.html` (the hardware‑player mockup) are both
-sources that share code through `@BUILD:*` markers, so the two stay in sync:
+Every page is a source that shares code through `@BUILD:*` markers, so they all stay
+in sync:
 
 - `/*@BUILD:include:src/…@*/` inlines a **shared partial** — the audio/scheduler
-  engine (`src/engine.js`), the seed set lists (`src/setlists.js`, so the player
-  ships the **same default set lists** as the editor), and base styling
-  (`src/base.css`: reset + brand palette + type).
+  engine (`src/engine.js`), the seed set lists (`src/setlists.js`, so every page ships
+  the **same default set lists** as the editor), and base styling (`src/base.css`:
+  reset + brand palette + type + the shared site header / nav / BOM table styles).
 - `@BUILD:favicon@`, `@BUILD:logo-*@`, `/*@BUILD:samples@*/{}` inline the base64
   assets from `assets/`.
 
-`./build.sh` resolves every marker into a self‑contained `dist/index.html` +
-`dist/player.html` (the editor inlines the CC0 samples; the player passes an empty
-`SAMPLES` for pure synth). `dist/` is generated, git‑ignored — don't edit it by hand.
-`deploy.sh` runs the build first, so a deploy always serves freshly assembled pages.
+`./build.sh` resolves every marker into a self‑contained page in `dist/` — the editor +
+concepts + device mockups + the `info-*.html` pages — and copies `embed.js` through as‑is
+(the editor inlines the CC0 samples; the device pages pass an empty `SAMPLES` for pure synth).
+`dist/` is generated, git‑ignored — don't edit it by hand. `deploy.sh` runs the build first,
+so a deploy always serves freshly assembled pages.
 
 ## Versioning
 
@@ -188,9 +229,12 @@ Push the tag, then deploy.
 
 | File | Purpose |
 |------|---------|
-| `index.html` | the editor app (source, with `@BUILD:*` markers) |
-| `player.html` | the play‑only hardware‑device mockup (`/player.html`) |
-| `src/` | shared partials inlined into both: `engine.js`, `setlists.js`, `base.css` |
+| `index.html` | the **PE‑1 editor** app (home page; source, with `@BUILD:*` markers) |
+| `concepts.html` | the form‑factor gallery |
+| `player.html` · `stage.html` · `micro.html` | the **PM‑1 Initial / Stage** and **PM‑µ Micro** device mockups |
+| `info-*.html` | per‑form‑factor info pages (purpose + priced BOM for buildable hardware) |
+| `embed.html` · `embed.js` | embed docs and the drop‑in widget loader |
+| `src/` | shared partials inlined into every page: `engine.js`, `setlists.js`, `base.css` |
 | `assets/` | base64 blobs inlined at build (samples, logos, favicon) |
 | `build.sh` | resolve markers → self‑contained `dist/` pages |
 | `deploy.sh` | build, then publish to the Caddy web root |