@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/docs/content/llm/howto-workflow.md

@@ -0,0 +1,369 @@
+# How to Build a Service Workflow — Circle Text Example
+
+This guide walks through building a complete workflow that renders text
+moving along a circular path in a Canvas service. It covers the pipeline
+model, how each service is configured, how data flows between them, and
+how to export and restore a board.
+
+---
+
+## Readymade architecture overview
+
+The platform uses a **pipeline model**: services within a runtime are
+ordered in a list. When the runtime processes data, each service receives
+the output of the previous service as its input. A service returning
+`null` stops the chain.
+
+```
+Timer ──► Map ──► Canvas
+```
+
+| Layer  | Role                                                             |
+| ------ | ---------------------------------------------------------------- |
+| Timer  | Emits a tick object every N ms with an incrementing counter      |
+| Map    | Transforms the tick into a canvas draw command using expressions |
+| Canvas | Receives the draw command and renders it via CanvasUI            |
+
+---
+
+## Step 1 — Add a Browser Runtime
+
+Every service needs a runtime to run in. Add a browser runtime from
+the runtime picker. It appears in the board with an empty service list.
+
+A runtime serialises as:
+
+```json
+{
+  "id": "rt-browser-1",
+  "name": "Browser Runtime",
+  "type": "browser",
+  "state": {
+    "wrapServices": false,
+    "minimized": false
+  }
+}
+```
+
+---
+
+## Step 2 — Add and configure the Timer service
+
+Add a **Timer** service (`hookup.to/service/timer`) as the first service
+in the runtime.
+
+### What it emits
+
+On every tick the Timer calls `app.next()` with:
+
+```json
+{ "triggerCount": 42 }
+```
+
+`triggerCount` is an integer that increments on every tick and resets to
+zero when the timer is restarted.
+
+### Configuration
+
+| Property        | Type    | Description                            |
+| --------------- | ------- | -------------------------------------- |
+| `periodicValue` | number  | How long between ticks                 |
+| `periodicUnit`  | string  | Unit: `"ms"`, `"s"`, `"m"`, …          |
+| `periodic`      | boolean | Enable repeating mode                  |
+| `running`       | boolean | Start the timer immediately on restore |
+
+For smooth animation at ~20 fps, use 50 ms:
+
+```json
+{
+  "periodicValue": 50,
+  "periodicUnit": "ms",
+  "periodic": true,
+  "running": true
+}
+```
+
+---
+
+## Step 3 — Add and configure the Map service
+
+Add a **Map** service (`hookup.to/service/map`) after the Timer.
+
+### What Map does
+
+Map transforms its input object into a new object according to a
+`template`. Each key in the template is either:
+
+- A **static property** — value is copied as-is.
+  ```
+  "type": "text"
+  ```
+- A **dynamic expression** — key ends with `=`, value is a JS expression
+  evaluated with `params` bound to the current pipeline input.
+  ```
+  "x=": "round(200 + 120 * sin(params.triggerCount * 0.05 + 1.5708))"
+  ```
+  The `=` suffix is stripped from the output key, so this produces `"x"`.
+
+### Available expression functions
+
+The expression evaluator exposes a safe global scope (no raw `Math`
+object). Key available names:
+
+| Name     | Equivalent to    |
+| -------- | ---------------- |
+| `sin`    | `Math.sin`       |
+| `round`  | `Math.round`     |
+| `min`    | `Math.min`       |
+| `max`    | `Math.max`       |
+| `rand`   | `Math.random`    |
+| `string` | `String(x)`      |
+| `number` | `Number(x)`      |
+| `concat` | `` `${x}${y}` `` |
+| `sum`    | sum of array     |
+| `avg`    | average of array |
+| `moment` | moment.js        |
+
+> **Note — no `cos`:** The global scope does not expose `Math.cos`.
+> Use the identity `cos(θ) = sin(θ + π/2)` instead:
+>
+> ```
+> sin(params.triggerCount * speed + 1.5708)   // ≈ cos(triggerCount * speed)
+> ```
+>
+> `1.5708` ≈ π/2.
+
+### Circular motion formula
+
+To make a point travel in a circle of radius `r` around center `(cx, cy)`:
+
+```
+x(t) = cx + r * cos(t)   →   round(cx + r * sin(t + 1.5708))
+y(t) = cy + r * sin(t)   →   round(cy + r * sin(t))
+```
+
+Where `t = triggerCount * speed`. Choose `speed` to control how fast the
+circle is traversed — a full revolution takes `2π / speed` ticks.
+
+| Speed | Ticks per revolution | Time at 50 ms/tick |
+| ----- | -------------------- | ------------------ |
+| 0.10  | ~63                  | ~3.1 s             |
+| 0.05  | ~126                 | ~6.3 s             |
+| 0.02  | ~314                 | ~15.7 s            |
+
+### Canvas text draw element
+
+The canvas `update()` function accepts objects with a `type` field.
+For text:
+
+| Field           | Type                 | Description                                                |
+| --------------- | -------------------- | ---------------------------------------------------------- |
+| `type`          | `"text"`             | Required                                                   |
+| `text`          | string               | The string to render                                       |
+| `x`             | number or `"N%"`     | Pixel offset from left (omit to horizontally center)       |
+| `y`             | number or `"N%"`     | Pixel offset from top baseline (omit to vertically center) |
+| `font`          | string or object     | CSS font string e.g. `"bold 22px Arial"`                   |
+| `color`         | string               | Fill color e.g. `"#3b82f6"`                                |
+| `contour`       | `{color, lineWidth}` | Optional text outline                                      |
+| `textTransform` | string               | `"uppercase"`, `"lowercase"`, `"lowercase-spacing-1"`, …   |
+| `onClick`       | action               | Optional click handler dispatched via `app.next`           |
+
+### Map configuration for this workflow
+
+```json
+{
+  "template": {
+    "type": "text",
+    "text": "HKP",
+    "color": "#3b82f6",
+    "font": "bold 22px Arial",
+    "x=": "round(200 + 120 * sin(params.triggerCount * 0.05 + 1.5708))",
+    "y=": "round(150 + 120 * sin(params.triggerCount * 0.05))"
+  },
+  "mode": "replace"
+}
+```
+
+On each tick this produces something like:
+
+```json
+{
+  "type": "text",
+  "text": "HKP",
+  "color": "#3b82f6",
+  "font": "bold 22px Arial",
+  "x": 320,
+  "y": 150
+}
+```
+
+with `x` and `y` changing on every tick to trace the circle.
+
+---
+
+## Step 4 — Add and configure the Canvas service
+
+Add a **Canvas** service (`hookup.to/service/canvas`) as the last service
+in the runtime.
+
+### How it works
+
+The Canvas service passes the received draw command to `CanvasUI` via
+`app.notify()`. CanvasUI calls `update()` which dispatches to the
+appropriate draw function based on the `type` field, then renders to an
+`<canvas>` element.
+
+`clearOnRedraw: true` (the default) clears the canvas with a white fill
+before each frame, preventing trails.
+
+### Configuration
+
+```json
+{
+  "size": [400, 300],
+  "clearOnRedraw": true,
+  "resizable": true
+}
+```
+
+`size` is `[width, height]` in pixels. The canvas starts at 400×300 by
+default. The user can resize it by dragging the resize handle if
+`resizable` is `true`.
+
+---
+
+## Step 5 — Run the board
+
+With all three services in order, the board is live:
+
+1. The Timer fires every 50 ms.
+2. Its output `{ triggerCount: N }` reaches the Map.
+3. Map evaluates the circle expressions and emits a `text` draw object.
+4. Canvas receives it and renders the text at the new position.
+5. The canvas is cleared before each frame so only the current position
+   is visible — the text appears to travel smoothly around the circle.
+
+---
+
+## Step 6 — Export the board configuration
+
+To export the current board state, open the board menu and choose
+**Edit Board Source**. The JSON shown is produced by `serializeBoard()`
+and has this shape:
+
+```json
+{
+  "boardName": "Circle Text",
+  "runtimes": [
+    {
+      "id": "<runtime-id>",
+      "name": "Browser Runtime",
+      "type": "browser",
+      "state": { "wrapServices": false, "minimized": false }
+    }
+  ],
+  "services": {
+    "<runtime-id>": [
+      {
+        "uuid": "<service-uuid>",
+        "serviceId": "hookup.to/service/timer",
+        "serviceName": "Timer",
+        "state": { ... }
+      }
+    ]
+  }
+}
+```
+
+Each service's `state` is whatever `getServiceConfig()` returns for that
+service — i.e. its persisted configuration.
+
+The complete board JSON for this example is saved alongside this document
+at [`circle-text-board.json`](./circle-text-board.json).
+
+---
+
+## Complete board JSON
+
+```json
+{
+  "boardName": "Circle Text",
+  "runtimes": [
+    {
+      "id": "rt-browser-1",
+      "name": "Browser Runtime",
+      "type": "browser",
+      "state": {
+        "wrapServices": false,
+        "minimized": false
+      }
+    }
+  ],
+  "services": {
+    "rt-browser-1": [
+      {
+        "uuid": "svc-timer-1",
+        "serviceId": "hookup.to/service/timer",
+        "serviceName": "Timer",
+        "state": {
+          "periodicValue": 50,
+          "periodicUnit": "ms",
+          "periodic": true,
+          "running": true
+        }
+      },
+      {
+        "uuid": "svc-map-1",
+        "serviceId": "hookup.to/service/map",
+        "serviceName": "Map",
+        "state": {
+          "template": {
+            "type": "text",
+            "text": "HKP",
+            "color": "#3b82f6",
+            "font": "bold 22px Arial",
+            "x=": "round(200 + 120 * sin(params.triggerCount * 0.05 + 1.5708))",
+            "y=": "round(150 + 120 * sin(params.triggerCount * 0.05))"
+          },
+          "mode": "replace"
+        }
+      },
+      {
+        "uuid": "svc-canvas-1",
+        "serviceId": "hookup.to/service/canvas",
+        "serviceName": "Canvas",
+        "state": {
+          "size": [400, 300],
+          "clearOnRedraw": true,
+          "resizable": true
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Adapting this workflow
+
+**Different text:** Change `"text"` in the Map template to any string.
+Use `"●"` for a dot, `"★"` for a star, or multi-character labels.
+
+**Different speed:** Change the `0.05` multiplier in both expressions.
+Double it (`0.10`) for twice the speed; halve it (`0.025`) for half.
+
+**Different radius:** Change `120` in both expressions. Values up to
+~140 keep the text inside the 400×300 canvas.
+
+**Different centre:** Change `200` (horizontal) and `150` (vertical) to
+any pixel position within the canvas.
+
+**Multiple draw elements:** Change the `process` flow so the Map outputs
+an array — or chain a second Map that wraps the single object in an array
+— to draw additional elements (e.g. a static circle outline with
+`type: "circle"`) alongside the moving text.
+
+**Slower ticks:** Increase `periodicValue` (e.g. to `100` for 10 fps)
+to reduce CPU usage; the motion becomes choppier but the pipeline
+overhead drops.

package/bundle/docs/content/repository.md

@@ -0,0 +1,161 @@
+# Repository
+
+How the code is laid out: one superproject, five submodules, and a rule about which is which.
+
+The source is at **[github.com/cbastuck/readymade](https://github.com/cbastuck/readymade)**.
+
+---
+
+## Two kinds of directory
+
+Everything lives under one checkout, but not everything lives in one
+*repository*. Some directories are ordinary folders with their history in the
+superproject; five are **git submodules** with histories of their own.
+
+The distinction is invisible in a file listing and decides how a change is
+committed, so it is worth knowing before the first commit rather than after.
+
+| Directory | Repository | What it is |
+|---|---|---|
+| `hkp-frontend/` | superproject | React app: playground UI, board engine, every browser service |
+| `hkp-rt/` | superproject | C++ runtime — audio, high performance, embedded in the apps |
+| `meander/` | superproject | The Readymade desktop app: a saucer webview shell (`backend/`) around the frontend (`frontend/`) |
+| `readymade-mcp/` | superproject | Read-only MCP knowledge server over `docs/content`, `boards/` and the runtimes' service source — Board Assist's optional richer knowledge |
+| `docs/` | superproject | These pages, and the small site that serves them |
+| `boards/` | superproject | Every board the repo ships — the demo board behind each service page, the worked examples, and `runtime-configs/` for hkp-rt |
+| `plans/` | superproject | Working documents for changes that span sessions: what was decided, why, and what is still open — deleted once a plan lands and its conclusions move into these pages |
+| `3rdparty/`, `scripts/`, `deployments/` | superproject | Vendored dependencies, tooling, packaging |
+| `hkp-node/` | **submodule** | Node.js runtime server, published as its own package |
+| `hkp-python/` | **submodule** | Python runtime server, installed into its own virtualenv |
+| `hkp-website/` | **submodule** | readymadeit.com — deployed on its own, to its own host |
+| `meander-ios/` | **submodule** | SwiftUI shell embedding the mobile playground and an in-process `hkp-rt` |
+| `meander-android/` | **submodule** | Android shell doing the same through a `WebView` |
+
+---
+
+## Why the split falls where it does
+
+A submodule is not a way of tidying up a large tree — it is a separate release.
+Each of the five is something a person can obtain **without this repository**:
+
+- `hkp-node` is run with `npx hkp-node`, installed globally, or pulled as a
+  container. Someone running a board's server half never clones the superproject.
+- `hkp-python` is installed into a virtualenv, with optional extras for the heavy
+  model dependencies.
+- `hkp-website` is deployed to a web host on its own schedule, and its history is
+  full of copy changes that mean nothing to the engine.
+- `meander-ios` and `meander-android` are built by platform toolchains — Xcode
+  and Gradle — with their own signing, store metadata and release cadence.
+
+Whereas `hkp-frontend`, `hkp-rt` and `meander` are **one build and one release**:
+the desktop app compiles the C++ runtime and embeds the frontend, and a change
+that spans the three is one change. Splitting them would mean a version dance
+between parts that are always shipped together.
+
+The rule, stated once: **a submodule is a thing with its own release; a folder is
+a thing released with everything else.**
+
+---
+
+## What the superproject records
+
+Not the submodule's files — a **commit id** per submodule, saying which revision
+of it this revision of the superproject expects. Two consequences follow, and
+both surprise people once:
+
+- **A change spanning both is two commits**, in order: commit inside the
+  submodule, then commit the moved pointer in the superproject. Stopping after
+  the first leaves a superproject that still names the old revision, which is how
+  a fix that "is definitely committed" fails to arrive for somebody else.
+- **`git status` in the superproject reports the submodule, not the file.** A
+  line reading `M hkp-node` means that submodule's worktree differs from the
+  recorded pointer — edited, or on a different commit — and says nothing about
+  which files inside changed. `git status` inside the submodule, or
+  `git submodule status`, answers that.
+
+The submodules are addressed by **relative URLs** (`../hkp-node.git`) except the
+website, which is on a different host entirely. A relative URL resolves against
+wherever the superproject itself was cloned from, so the same `.gitmodules` works
+for a clone over SSH and one over HTTPS without a per-user edit.
+
+---
+
+## Building
+
+There is no build that builds everything, because the parts do not share a
+toolchain:
+
+| Part | Built with | Entry point |
+|---|---|---|
+| `hkp-rt` + `meander` (desktop) | CMake + vcpkg | `CMakeLists.txt` at the root — it adds `3rdparty`, `hkp-rt` and `meander`, and nothing else |
+| `hkp-frontend`, `docs`, `hkp-website`, `hkp-node` | npm + Vite / tsc | `package.json` in each |
+| `hkp-python` | hatchling, in a virtualenv | `pyproject.toml` |
+| `meander-ios` | CMake + Xcode | `build-ios.sh` at the root, which builds the mobile web app first |
+| `meander-android` | Gradle + NDK | `build.gradle.kts`, and `README-android.md` at the root |
+
+The root scripts — `build.sh`, `build-ios.sh`, `build-linux.sh`,
+`build-windows.ps1` — are the per-platform entry points, and each README at the
+root (`README-macos.md`, `README-ios.md`, `README-android.md`, …) covers one
+platform's prerequisites.
+
+---
+
+## Testing
+
+`run-all-tests.sh` at the root runs every area's suite in one go; the end-to-end
+suite in `e2e/` is separate, and drives the assembled app in a real browser.
+**CI is narrower than either**: `.github/workflows/run-all-tests.yml` checks out
+with `submodules: false` and runs hkp-rt and hkp-frontend only.
+
+That is not an oversight, it is this same split again — the submodules answer
+for themselves, and a superproject workflow that cloned them would be testing
+whichever commit they happened to be on. What that means in practice — which
+suite answers which question, and what is left outside the green tick — is in
+[Testing](./testing.md).
+
+---
+
+## What this costs, and where it shows up
+
+A tool that reasons about "what changed" cannot ask one repository, because a
+change genuinely spanning the tree is several diffs with nothing joining them.
+The vocabulary checker is the worked example: `scripts/vocabulary.mjs` takes the
+superproject's diff *and* each submodule's, because the paths it verifies live on
+both sides of the boundary and a diff from the superproject alone reports
+`hkp-node` as one changed path rather than the file inside it that moved.
+
+Anything else that walks the tree — a search, a release script, a review — has
+the same problem, and the same answer: iterate the list in `.gitmodules`.
+
+Guarding an invariant that spans the boundary costs the same. The app version is
+stated twice — `version` in `hkp-frontend/package.json`, which the superproject
+holds, and `APP_VERSION_STRING` in `hkp-website/src/pages/constants.ts`, which
+the website submodule holds — so a commit on either side alone can break the
+pair, and a hook in one repository would never see the other's commit.
+`scripts/check-version-sync.mjs` compares the two working trees and takes
+`package.json` as the source of truth (`--fix` rewrites the website string).
+`.githooks/pre-commit` runs it, and `scripts/install-hooks.sh` points
+`core.hooksPath` at that directory in **both** repositories — hooks are not
+carried by a clone, so this is a step each checkout takes once.
+
+---
+
+## Rough index into the source
+
+| Concern | Where |
+|---|---|
+| The repository itself | [github.com/cbastuck/readymade](https://github.com/cbastuck/readymade) |
+| Which directories are submodules | `.gitmodules` |
+| What the desktop build compiles | `CMakeLists.txt` |
+| Running every suite | `run-all-tests.sh`, `run-all-cpp-tests.sh` |
+| What CI covers | `.github/workflows/run-all-tests.yml` |
+| Per-platform prerequisites | `README-macos.md`, `README-ios.md`, `README-android.md`, `README-linux.md`, `README-windows.md`, `README-web.md` |
+| Iterating submodules in a script | `scripts/vocabulary.mjs` |
+| What each suite covers, and what CI does not | [Testing](./testing.md) |
+
+---
+
+See also: [Testing](./testing.md) for what runs where and why CI covers only
+part of it, [Runtime](./concepts/runtime.md) for what each of these parts *is*
+in a running board, and [Vocabulary](./vocabulary.md) for the word-to-file
+lookup across all of them.

package/bundle/docs/content/services/aggregator.md

@@ -0,0 +1,76 @@
+# Aggregator
+
+Counts occurrences of values in a named property and periodically emits the most frequent value seen.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/aggregator` |
+
+---
+
+## What it does
+
+Aggregator is a frequency-based smoother. On every pipeline trigger it
+records the value of a configured property in a histogram. At a fixed
+time interval it emits the **mode** (most frequently seen value) and
+resets the histogram. This smooths out noisy or rapidly changing
+categorical signals — for example, a classifier that oscillates between
+two labels will resolve to whichever label appeared more often in the
+window.
+
+Unlike most services, Aggregator does **not** return a value from its
+`process()` call. Instead it emits independently on its own timer via
+`app.next()`. The output therefore arrives at the next service on a
+schedule, not in response to upstream triggers.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `property` | `string` | `"unset"` | Name of the key to aggregate across incoming objects |
+| `interval` | `number` | `100` | Emission interval in milliseconds |
+
+### How aggregation works
+
+1. Each incoming value's `property` field is recorded in an internal
+   histogram: `{ value → count }`.
+2. Every `interval` ms the histogram is examined and the value with the
+   highest count is selected.
+3. That value is emitted as `{ [property]: winnerValue }`.
+4. The histogram is cleared.
+
+When the input is an array, all elements are aggregated in the same
+window.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Object (or array of objects) with the configured `property` key |
+| **process() return** | Always `null` — no synchronous downstream emission |
+| **Timer emission** | `{ [property]: mostFrequentValue }` |
+
+---
+
+## Example
+
+Smooth a noisy label signal arriving at 20 Hz, emitting the winner
+every 500 ms:
+
+```json
+{
+  "property": "label",
+  "interval": 500
+}
+```
+
+Input over 500 ms: `cat, cat, dog, cat, dog, dog, dog, cat, cat, cat`
+Output: `{ "label": "cat" }` (6 vs 4)

package/bundle/docs/content/services/analyzer.md

@@ -0,0 +1,44 @@
+# Analyzer
+
+Forwards pipeline data unchanged while notifying the UI of each value as it passes through.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/analyzer` |
+
+---
+
+## What it does
+
+Analyzer is a transparent inspection service. It passes every incoming value through to the next service unmodified, and simultaneously emits a notification to its UI panel via `app.notify`. The UI can observe and visualise the raw data without affecting the pipeline.
+
+Use Analyzer when you need a programmable observation point that is distinct from Monitor — for example, when you want custom visualisation logic wired into the service's UI rather than a generic JSON log.
+
+---
+
+## Configuration
+
+None. Analyzer has no configuration properties.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value |
+| **Output** | Identical to input — passes through unchanged |
+
+---
+
+## Differences from Monitor
+
+| | Analyzer | Monitor |
+|---|---|---|
+| UI | Custom / programmable | Generic scrolling JSON log |
+| Pass-through | Yes | Yes |
+| Notification payload | `{ onProcess: <value> }` | Rendered in the log directly |