@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/docs/content/services/ascii-art.md

@@ -0,0 +1,58 @@
+# ASCII Art
+
+Converts an image (Blob) into a text grid of ASCII characters representing its luminance.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/ascii-art` |
+
+---
+
+## What it does
+
+ASCII Art receives an image `Blob` from the pipeline, draws it onto an off-screen canvas scaled to the configured grid dimensions, samples the luminance of each pixel, and maps each luminance value to a character from the configured character set. The resulting string grid is emitted downstream as `ascii` on the incoming object; the `Blob` itself is dropped, since it cannot be serialised and is not needed further down.
+
+A typical use is to pipe Camera output through ASCII Art to produce a live ASCII-art webcam feed.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `cols` | `number` | `100` | Number of character columns in the output grid |
+| `rows` | `number` | `60` | Number of character rows in the output grid |
+| `charset` | `string` | `" .:-=+*#%@"` | Ordered character ramp from lightest to darkest |
+| `invert` | `boolean` | `false` | When `true`, reverses the luminance mapping (dark → light characters) |
+| `imageKey` | `string` | `"image"` | Key on the incoming object that holds the `Blob` |
+
+### Character set
+
+Characters are indexed by normalised luminance: the first character in the string is used for the lightest pixels, the last for the darkest. Any string of two or more characters works; a ten-character ramp (`" .:-=+*#%@"`) is a good starting point.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Object with a `Blob` at the key specified by `imageKey`, e.g. `{ image: <Blob> }` |
+| **Output** | The incoming object minus the `Blob`, plus `ascii` — a string with each row of characters joined by newlines |
+
+If the input does not contain a `Blob` at `imageKey`, the original value is passed through unchanged.
+
+A consumer that wants the characters on their own — rather than an object carrying them — can follow ASCII Art with a Map whose template is `{ "=": "params.ascii" }`.
+
+---
+
+## Example pipeline
+
+```
+Camera → ASCII Art → Monitor
+```
+
+Configure Camera to emit `{ image: <Blob> }`, then ASCII Art converts it and Monitor displays it. Monitor in `ascii` mode reads the `ascii` key itself, so nothing is needed between the two; `boards/ascii-cam-board.json` is that pipeline with a Timer driving it.

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

@@ -0,0 +1,88 @@
+# Asset
+
+Puts one of the board's assets into the pipeline.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `asset` |
+| Node.js (hkp-node) | `asset` |
+| Python (hkp-python) | `asset` |
+| C++ (hkp-rt) | `asset` |
+
+---
+
+## What it does
+
+A board declares content once as an [asset](../concepts/assets.md) and services
+name it as `hkp-asset://<id>`. A service that serves, plays or loads content
+resolves a reference itself. **Asset** is for everything else: it emits the
+asset's content so any service after it can use it.
+
+The asset is **resolved on every pass**, from the runtime's asset store — in the
+browser, the board's own `assets` — so editing the asset changes what the next
+pass carries without reconfiguring anything.
+
+Not meant for large content: a model does not belong in a pipeline frame.
+
+---
+
+## Configuration
+
+| Property | Type | Description |
+|---|---|---|
+| `asset` | `string` | The reference emitted when the input names none, e.g. `"hkp-asset://card"` |
+
+It also reports `mediaType` and `size` from the last pass, and `error` when the
+last pass could not resolve its asset.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Anything — it only triggers the pass. A bare `hkp-asset://…` string, or an object whose `asset` field is one, names the asset for that pass instead of the configured one |
+| **Output** | `{ meta, body }` for text, `{ meta, binary }` otherwise |
+
+On hkp-rt a binary asset leaves as MixedData, `meta` beside the bytes.
+
+`meta` is `{ status: 200, contentType, asset, size }` — shaped like an HTTP
+response, as [`filesystem`](./filesystem.md)'s answers are, so an endpoint can
+hand it straight back.
+
+An asset that does not resolve is answered with an error status and the reason
+(`{ meta: { status: 404 }, body: { error } }`) and reported on the service. The
+reference itself is never passed on as though it were the content.
+
+---
+
+## Typical use
+
+### Serve whichever asset a request names
+
+```
+http-server-subservices
+  onRequest: map (path → hkp-asset://…) → asset
+```
+
+A Map turns the request into a reference and Asset answers with its content. For
+a single page, an endpoint can name the asset as its response `body` directly and
+needs no Asset service at all.
+
+### Feed a template or a prompt to a service with no asset support
+
+```
+injector → asset (hkp-asset://prompt) → map (body → prompt) → text-generation
+```
+
+---
+
+## Demo
+
+The demo board injects `hkp-asset://greeting` to show an input naming the asset,
+and is otherwise configured with `hkp-asset://card`. Open the asset view, edit
+either and press **Apply**: the next run carries the new content.

package/bundle/docs/content/services/audio-editor.md

@@ -0,0 +1,57 @@
+# Audio Editor
+
+Accumulates a rolling window of incoming audio and provides playback and editing of the recorded audio.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/audioeditor` |
+
+---
+
+## What it does
+
+Audio Editor sits in an audio pipeline and accumulates every `FloatRingBuffer` that arrives into a single flat `Float32Array`. When the accumulated length exceeds `maxLength`, the oldest samples are discarded in ring-buffer fashion so the buffer always holds the most recent audio up to the configured limit.
+
+The service does not pass the audio downstream — it accumulates and notifies its UI, which renders a waveform and allows the user to select a region and trigger playback.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `maxLength` | `number` | `2880000` | Maximum number of samples to retain (default = 60 s at 48 kHz) |
+| `action` | `string` | — | `"clear"` resets the buffer; `"play"` triggers playback of a selection |
+| `action: "play"` params | `{ startSample, endSample }` | — | Sample range to play back |
+
+### Commands
+
+| Command | Effect |
+|---|---|
+| `{ action: "clear" }` | Discards all accumulated audio |
+| `{ action: "play", params: { startSample, endSample } }` | Plays back samples in the specified range |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | `FloatRingBuffer` — passes through unchanged if not audio |
+| **Output** | The original `FloatRingBuffer` (pass-through) |
+
+---
+
+## Typical use
+
+Connect Audio Editor after an audio input service in a pipeline to create a live recorder with waveform display:
+
+```
+AudioInput → Audio Editor
+```
+
+The UI shows the accumulated waveform and lets the user trim and replay regions.

package/bundle/docs/content/services/audio-encode.md

@@ -0,0 +1,115 @@
+# Audio Encode
+
+Turns the samples a board made into a file a board can keep.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Python (hkp-python) | `audio-encode` |
+| C++ (hkp-rt) | `audio-encode` |
+
+---
+
+## What it does
+
+Services that produce sound produce **samples**: a `FloatRingBuffer` is what
+[Text To Speech](./text-to-speech.md), a microphone and a synthesiser all hand
+on, and what Audio Output plays. Samples are not a file — nothing stores them,
+serves them, or hands them to a player. This encodes them.
+
+It emits **bare bytes**: not bytes with a name, not bytes with a content type.
+What they are called belongs to whatever keeps them — [Storage](./storage.md)
+reads the file extension, and an endpoint reads what Storage says. An encoder
+that also decided names would have to be told about both.
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `format` | `"mp3" \| "wav"` | `mp3` | What to write |
+| `bitrate` | `number` | `64` | kbit/s, mp3 only |
+| `quality` | `number` | `5` | LAME quality, 0 (best) to 9 |
+| `sampleRate` | `number` | `24000` | What the incoming samples are |
+| `channels` | `1 \| 2` | `1` | How to read them |
+| `stream` | `boolean` | `false` | One recording across all passes rather than one per pass — hkp-rt, mp3 only |
+
+`wav` needs nothing beyond the standard library and is always available. `mp3`
+is an optional extra on hkp-python:
+
+```
+uv sync --extra mp3    # in hkp-python
+```
+
+and compiled into hkp-rt with LAME (`HKP_MP3_ENABLED`, on for macOS builds). A
+runtime without it lists only `wav` in `availableFormats`.
+
+A board that only plays audio back has no reason to carry an encoder, which is
+why it is an extra; the two formats are one service because choosing between
+them is a decision about size against fidelity, not a different job.
+
+### The sample rate is configuration
+
+A `FloatRingBuffer` carries floats and does not say how fast they were meant to
+be played, so the same samples are a different length of audio depending on what
+a board says they are. Kokoro synthesises at 24 kHz, which is why that is the
+default here and in Audio Output.
+
+### Streaming
+
+Without `stream`, each pass is a whole recording: the input is encoded and the
+encoder flushed, and what comes out is a complete file.
+
+With it, the passes are **one recording that never ends**. A single encoder lives
+across all of them; each pass hands it whatever samples arrived since the last
+and emits the frames that finished — often none, in which case the pass stops
+there. Nothing is flushed until a setting changes, which starts a new stream.
+
+That is what MP3 needs. Frames are not independent: each overlaps its neighbours,
+and may spend bits its predecessors saved, so the encoder keeps back the samples
+its model still needs. Encoding chunk by chunk with a fresh encoder would put a
+seam, and the encoder's start-up delay, into every chunk.
+
+Every chunk a stream emits is **whole frames**, so each is a place a decoder can
+find its footing — which is what lets an [endpoint's stream](./http.md#streaming)
+take listeners at any moment. It is not always a place the audio is complete: a
+frame that spends bits its predecessors saved needs bytes a listener joining
+there never received, and a decoder plays such a frame as silence. Joining
+therefore costs up to a few frames — tens of milliseconds — before sound starts,
+the same as on any MP3 radio stream. State adds `streamedBytes` and `streamedSeconds`, and is
+notified about once a second rather than on every pass.
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | `FloatRingBuffer` |
+| **Output** | the encoded bytes |
+
+Samples outside -1..1 are clipped rather than the clip being quietened to
+accommodate them: a sample that loud was already wrong when it was made, and
+scaling would change audio that was correct.
+
+Anything that is not audio comes back as `{ error }` and is reported in the
+service's state, rather than being encoded into noise.
+
+## Example
+
+Reading text aloud and keeping the result, as the Radio boards do:
+
+```
+map (the words) → text-to-speech → audio-encode → … → storage
+```
+
+## Demo board
+
+`audio-encode-demo-board.json` — type a line, hear what it costs as an mp3.
+
+`live-radio-demo-board.json` — the microphone streamed live as MP3 from hkp-rt.
+
+## See also
+
+- [Text To Speech](./text-to-speech.md) — where the samples usually come from
+- [Storage](./storage.md) — where the bytes usually go

package/bundle/docs/content/services/audio-io.md

@@ -0,0 +1,173 @@
+# Audio IO
+
+Records audio from a microphone and plays it back through the speakers, in both the browser and the hkp-rt native runtime.
+
+---
+
+## Available in
+
+| Runtime | Service ID | Platform |
+|---|---|---|
+| Browser | `hookup.to/service/audio-input` | All |
+| Browser | `hookup.to/service/audio-output` | All |
+| hkp-rt | `core-input` | macOS only |
+| hkp-rt | `core-output` | macOS only |
+
+---
+
+## Browser — Audio Input
+
+**Service ID:** `hookup.to/service/audio-input`
+
+Requests microphone access and records audio in one of two output formats:
+
+- **`blob`** (default) — records with the browser's `MediaRecorder` API and
+  emits compressed audio `Blob` chunks (webm/opus on Chrome, mp4/aac on
+  Safari) downstream on a configurable interval.
+- **`pcm`** — captures raw samples with an `AudioWorklet`, accumulates them
+  while recording, and on stop emits a single `FloatRingBuffer` of
+  **16 kHz mono float32** samples — the contract expected by the Python
+  [Speech To Text](./speech-to-text.md) service.
+
+### Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `timeslice` | `number` | `1000` | Recording chunk interval in milliseconds (`blob` format) |
+| `format` | `string` | `"blob"` | Output format: `"blob"` or `"pcm"` |
+| `device` | `MediaDeviceInfo` | system default | Audio input device to use |
+
+### Commands
+
+| Action | Params | Description |
+|---|---|---|
+| `"start-recording"` | `{ timeslice? }` | Start capturing audio |
+| `"stop-recording"` | — | Stop capturing; in `pcm` format this emits the recording |
+
+### Output
+
+`blob`: compressed audio `Blob` chunks while recording.
+`pcm`: one `FloatRingBuffer` (16 kHz mono float32) emitted when recording stops.
+
+---
+
+## Browser — Audio Output
+
+**Service ID:** `hookup.to/service/audio-output`
+
+Decodes and plays back audio data received from the pipeline through the Web Audio API.
+
+### Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `fadeInTime` | `number` | `0` | Fade-in duration in seconds when playback starts |
+
+### Input
+
+A `FloatRingBuffer` or decoded audio buffer, typically from Audio Input, FFT → IFFT, or an audio synthesis pipeline.
+
+---
+
+---
+
+## core-input
+
+### What it does
+
+Opens the system's default audio input device (microphone or aggregate
+device) via CoreAudio and continuously captures audio samples. Captured
+samples are written into a **ring-buffer** that is emitted downstream on
+each callback, making `core-input` the natural source for any audio
+processing pipeline.
+
+### Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `preferredInputDeviceName` | `string` | `""` | Name of the desired input device. If empty or not found, the system default is used. |
+| `preferredSampleRate` | `number` | device default | Sample rate to set the device to |
+| `preferredBufferSize` | `number` | `512` | Frames per device callback |
+| `deferPropagation` | `boolean` | `false` | Which thread the services after this one run on — see below |
+
+The `configure` response includes read-only fields populated by the
+service:
+
+| Field | Type | Description |
+|---|---|---|
+| `currentDeviceName` | `string` | Name of the device actually opened |
+| `availableDevices` | `string[]` | All input devices currently visible to CoreAudio |
+| `sampleRate` | `number` | The rate the device actually runs at |
+| `channels` | `number` | How many channels the samples are interleaved across — what a service reading them, such as [Audio Encode](./audio-encode.md), is configured to match |
+| `error` | `string` | Why the device is not delivering what was asked for, or empty. Set when the device runs at a rate other than `preferredSampleRate` — capture goes ahead at the device's rate, and whatever reads the samples under the preferred one plays them at the wrong speed — and when the device's format cannot be captured at all: samples that are not float, or channels in separate buffers |
+
+### Which thread runs the pipeline
+
+CoreAudio calls back on its **realtime audio thread**, and the samples go into
+the ring buffer there.
+
+- **`deferPropagation: false`** — the services after this one run right there,
+  inside the callback. Lowest latency, and only sound when everything after this
+  service is realtime-safe: no allocation, no locks, no I/O.
+- **`deferPropagation: true`** — the callback only signals, and the rest of the
+  pipeline runs on the runtime's event loop. The ring buffer carries the samples
+  across, so a pass that starts late reads everything that arrived in between;
+  signals that arrive before a pass has started count as one. Use it whenever
+  something downstream encodes, sends, or otherwise does real work.
+
+Either way the callback itself does nothing but append and signal: it never
+allocates, locks or logs.
+
+### Output
+
+A **ring-buffer** data value containing the most recent block of float32
+audio samples at the device's native sample rate. The block size is
+determined by the CoreAudio buffer size (a system constant).
+
+---
+
+## core-output
+
+### What it does
+
+Accepts a sample array or ring-buffer from upstream and plays it through
+the system's default audio output device via CoreAudio.
+
+### Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `preferredOutputDeviceName` | `string` | `""` | Name of the desired output device |
+
+### Input
+
+A float array or ring-buffer of audio samples, typically produced by
+`ifft` or a synthesis pipeline.
+
+---
+
+## Typical pipelines
+
+### Microphone monitoring (passthrough)
+
+```
+core-input → core-output
+```
+
+### Real-time spectrum analysis
+
+```
+core-input → fft → monitor
+```
+
+### Live frequency-domain effect
+
+```
+core-input → fft → map (modify spectrum) → ifft → core-output
+```
+
+### Onset/beat detection
+
+```
+core-input → transient-detector → timer (trigger) → canvas
+```

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

@@ -0,0 +1,49 @@
+# Batcher
+
+Collects incoming pipeline values and flushes them as a batch after a minimum delay between flushes.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/shared/batcher` |
+
+---
+
+## What it does
+
+Batcher accumulates values arriving via `process()` into an internal array. It schedules a flush using a timer that respects a minimum delay (`minDelayInMsec`) between consecutive flushes. If values arrive faster than the delay allows, they are held until the timer fires.
+
+When the flush timer fires, the accumulated batch is emitted downstream via `app.next()` and the buffer is cleared.
+
+Unlike [Buffer](./buffer.md), Batcher does not have a capacity limit — it is purely time-driven.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `minDelayInMsec` | `number` | `1000` | Minimum time in milliseconds between batch emissions |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value |
+| **process() return** | Always `null` — emission happens asynchronously via `app.next()` |
+| **Flush emission** | Array of all accumulated values since the last flush |
+
+---
+
+## Differences from Buffer
+
+| | Batcher | Buffer |
+|---|---|---|
+| Flush trigger | Time only | Capacity or time |
+| Capacity limit | None | Yes (`capacity`) |
+| Service ID namespace | `hookup.to/shared/` | `hookup.to/service/` |

package/bundle/docs/content/services/board-service.md

@@ -0,0 +1,48 @@
+# Board Service
+
+Runs a saved board as a sub-pipeline, forwarding incoming data through it and emitting the result.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/board-service` |
+
+---
+
+## What it does
+
+Board Service lets you embed one board inside another. When it receives a value via `process()`, it delegates it to the UI layer, which routes it through the selected board and resolves the result. This makes complex, reusable processing graphs composable without duplicating service configurations.
+
+Boards can be selected from the user's saved board library via the `selectedBoard` property.
+
+---
+
+## Configuration
+
+| Property | Type | Description |
+|---|---|---|
+| `selectedBoard` | `string` | Name or identifier of the saved board to run |
+| `result` | `any` | Internal — used by the UI to deliver a result back into the pipeline |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value — passed to the selected board's first service |
+| **Output** | Result of running the selected board on the input |
+
+---
+
+## How it works
+
+1. An upstream service emits a value.
+2. Board Service's `process()` posts a `command: { action: "process", params, promise }` notification to the UI.
+3. The UI runs the incoming data through the selected board and resolves the promise with the result.
+4. The result is emitted downstream as the next pipeline value.
+
+The board is executed synchronously from the calling pipeline's perspective (the promise resolves before the pipeline continues).

package/bundle/docs/content/services/browser-sub-service.md

@@ -0,0 +1,75 @@
+# Browser Sub-Service
+
+Runs a nested pipeline inside a browser runtime, passing incoming data through it and emitting the final result.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `sub-service` |
+
+The settings shared with the other runtimes — `pipeline`, `bypass`,
+`stopPropagation`, `scope` — are documented once in
+[SubService](./sub-service.md). What is here is the browser's own addition.
+
+---
+
+## What it does
+
+Browser Sub-Service embeds a complete inner pipeline (a `BrowserRuntimeScope`) inside a single service slot. Two modes are supported:
+
+| Mode | Behaviour |
+|---|---|
+| `pipeline` | Instantiates the nested pipeline and routes each incoming value through it. The final output of the inner pipeline is emitted downstream. Asynchronous emissions from nested services (e.g. a Timer) are also forwarded to the outer pipeline. |
+| `source` | Emits the full board descriptor JSON (runtimes + services) on `configure()` and `process()`. Used when the sub-service wraps a remote/phone runtime rather than running locally — downstream services (e.g. LZ Compress + QR Code) can embed the descriptor in a URL. |
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `mode` | `"pipeline"` \| `"source"` | `"pipeline"` | Operating mode |
+| `boardName` | `string` | `""` | Display name for the nested board |
+| `runtimeId` | `string` | `"browser-runtime"` | ID of the inner runtime |
+| `runtimeName` | `string` | `"Browser Runtime"` | Display name of the inner runtime |
+| `runtimeType` | `string` | `"browser"` | Runtime type tag |
+| `pipeline` | `PipelineEntry[]` | `[]` | Ordered list of services in the inner pipeline |
+| `stopPropagation` | `boolean` | `false` | Whether what the pipeline produced leaves this service — see [SubService](./sub-service.md) |
+| `scope` | `{ slots }` | `{ slots: "own" }` | Which cells a [`hold`](./hold.md) inside reaches |
+
+### Commands
+
+| Command | Description |
+|---|---|
+| `cancel` | Ends every pass running inside this scope and the scopes nested in it. A pass ends at the service it is in: that service finishes (a waiting [Timer](./timer.md) waits out its delay), then nothing after it runs and nothing leaves the scope. Passes started afterwards run normally, and nothing is rebuilt. It does not stop a service that emits of its own accord, such as a periodic Timer, which has its own `stop`. **Browser only.** |
+
+A board keeps a scope's pipeline as its services currently are, including changes sent straight to a service inside it by its [scoped address](../concepts/scopes.md).
+
+### Pipeline entry shape
+
+```json
+{
+  "serviceId": "hookup.to/service/map",
+  "instanceId": "map-1",
+  "serviceName": "Map",
+  "state": { "template": { "=": "params.value * 2" } }
+}
+```
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value (piped into the inner pipeline) |
+| **Output** | Result from the last service in the inner pipeline, or the board descriptor JSON in `source` mode |
+
+---
+
+## Relationship to hkp-rt sub-services
+
+The `sub-service` serviceId mirrors the same concept in hkp-rt, hkp-node, and hkp-python. In all runtimes a sub-service instantiates and runs a nested pipeline as a single processing step.