@readymadeit/mcp 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,47 @@
+# Limit
+
+Truncates an array to at most `n` elements.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/limit` |
+
+---
+
+## What it does
+
+Limit takes an array input and returns only the first `n` elements. Non-array values are passed through unchanged.
+
+Use Limit after services that produce variable-length arrays (such as [Filter](./filter.md), [FlatMap](./flat-map.md), or [Sort](./sort.md)) to cap the output to a known maximum size.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `n` | `number` | `10` | Maximum number of elements to keep. Must be ≥ 1. |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Array (or any value) |
+| **Output** | First `n` elements of the array; original value if not an array |
+
+---
+
+## Example
+
+```json
+{ "n": 5 }
+```
+
+Input: `[1, 2, 3, 4, 5, 6, 7, 8]`
+Output: `[1, 2, 3, 4, 5]`

package/bundle/docs/content/services/local-storage.md

@@ -0,0 +1,47 @@
+# Local Storage
+
+Reads key–value pairs from the browser's `localStorage` and emits them as an array.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/local-storage` |
+
+---
+
+## What it does
+
+Local Storage queries `window.localStorage`, optionally filtered to keys starting with a given prefix, and emits an array of `{ key, value }` objects. The cache is refreshed on each `process()` call and whenever `filter` is updated.
+
+This service is read-only — it does not write to localStorage. To write, use the vault functions available in [Map](./map.md) and [Hacker](./hacker.md) expressions (`toVault`).
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `filter` | `string` | `""` | Key prefix filter. Only keys starting with this string are included. Empty string = all keys. |
+| `process` | `boolean` | — | When `true`, immediately fires the current item list downstream via `app.next()` |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any (ignored; triggers a fresh read of localStorage) |
+| **Output** | `Array<{ key: string, value: string }>` |
+
+---
+
+## Example: read all keys with a prefix
+
+```json
+{ "filter": "board." }
+```
+
+Returns all localStorage entries whose key begins with `"board."`.

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

@@ -0,0 +1,62 @@
+# Looper
+
+Records a sequence of pipeline values and replays them at the original timing.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/looper` |
+
+---
+
+## What it does
+
+Looper captures all data values that pass through it while in **record**
+mode, preserving the timestamps between each value. When switched to
+**play** mode, it replays the recorded sequence at the same pace —
+emitting each value via `app.next()` with the same delay between events
+as the original recording.
+
+This makes Looper useful for recording live gestures, sensor streams, or
+interactive performances and replaying them deterministically.
+
+---
+
+## Modes
+
+| Mode | Behaviour |
+|---|---|
+| **Record** | Passes data through unchanged; stores each value with its arrival timestamp |
+| **Play** | Ignores incoming pipeline data; replays the recording at original timing |
+| **Stop** | Neither records nor plays; passes data through like a bypass |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input (record mode)** | Any value — stored and passed downstream |
+| **Input (play mode)** | Ignored |
+| **Output (play mode)** | Each recorded value, emitted at original inter-event timing via `app.next()` |
+
+---
+
+## Typical use
+
+- Record a live XY pad performance, then play it back in a loop while
+  adjusting other parameters.
+- Capture a data stream from an external sensor for offline development
+  without needing the sensor connected.
+- Create generative patterns by recording a short motif and looping it.
+
+```
+XYPad → Looper → Map → Canvas
+```
+
+While Looper is in record mode, XY gestures pass through to Canvas in
+real time and are stored. Switch to play mode: Looper replays the
+gesture in a loop, freeing the XY pad.

package/bundle/docs/content/services/lz-compress.md

@@ -0,0 +1,52 @@
+# LZ Compress
+
+Compresses or decompresses values using LZ-string — a URL-safe lossless text compression algorithm.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/lz-compress` |
+
+---
+
+## What it does
+
+LZ Compress uses the [lz-string](https://github.com/pieroxy/lz-string) library to apply `compressToEncodedURIComponent` / `decompressFromEncodedURIComponent` to pipeline values.
+
+In **compress** mode, non-string inputs are JSON-serialised first. The result is a URL-safe compressed string that can be embedded in a query parameter.
+
+In **decompress** mode, the compressed string is decompressed; if the result is valid JSON it is parsed before emitting, so downstream services receive the original structured value.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `mode` | `"compress"` \| `"decompress"` | `"compress"` | Operating mode |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input (compress)** | Any value — strings are compressed as-is; others are JSON-stringified first |
+| **Output (compress)** | URL-safe compressed string |
+| **Input (decompress)** | URL-safe compressed string |
+| **Output (decompress)** | Original value — parsed as JSON if valid; otherwise the raw decompressed string |
+
+Returns `null` (with no error) if decompression produces an empty string.
+
+---
+
+## Typical use: embed a board in a QR code URL
+
+```
+Browser Sub-Service (source mode) → LZ Compress → QR Code
+```
+
+The sub-service emits the board descriptor JSON, LZ Compress reduces it to a URL-safe string, and QR Code encodes it as a scannable link.

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

@@ -0,0 +1,257 @@
+# Map
+
+Transforms pipeline data by applying a declarative template to produce a new JSON object.
+
+---
+
+## Overview
+
+The Map service takes incoming data (`params`) and applies a **template** to produce a new object. Templates can mix static values with dynamic expressions evaluated against the incoming data. This makes Map the primary tool for reshaping, renaming, and computing derived values within a pipeline.
+
+**Available in:**
+- Browser Runtime — service ID `hookup.to/service/map`
+- hkp-rt — service ID `map`
+- hkp-node — service ID `map`
+- hkp-python — service ID `map`
+
+All four share the same template dialect — flat, nested and array templates — the
+same modes, the same inject command and the same UI, and they say the same things
+about a pass (see [Errors and warnings](#errors-and-warnings)). What each runtime
+adds is listed where it applies: [Inja templates](#hkp-rt-inja-templates) on hkp-rt,
+[mount addresses](#an-address-a-board-mentions) on hkp-node and hkp-python, and the
+built-in functions only a browser can offer.
+
+---
+
+## Template Syntax
+
+A template is a JSON object. Keys and values follow specific conventions to distinguish static from dynamic content.
+
+### Static Properties
+
+A key without a trailing `=` is copied verbatim into the output:
+
+```json
+{ "label": "hello", "version": 2 }
+```
+
+### Dynamic Expressions
+
+A key ending with `=` marks a **dynamic term**. The `=` suffix is stripped from the key name in the output, and the value is evaluated as an expression against the incoming data:
+
+```json
+{ "angle=": "params.triggerCount * 0.1" }
+```
+
+This produces `{ "angle": <computed value> }` in the output.
+
+A read of something that is not there is not an error: `params.a.b` with no `a`
+is empty, as if written `params.a?.b`, and the term's key is kept with the value
+`null`. So `{ "title=": "params.titel" }` produces `{ "title": null }` — and the
+Map warns about it (see [Errors and warnings](#errors-and-warnings)).
+
+### Scalar Output
+
+When the template contains a single key equal to `"="` (empty string after stripping `=`), the result is a **scalar value** rather than an object:
+
+```json
+{ "=": "params.value * 2" }
+```
+
+The pipeline receives the raw computed value, not a wrapper object — whatever the
+`mode`, since there is no object to merge into the input. A value that is `null`,
+including a read that found nothing, has nothing to pass on: the flow stops there.
+
+### Nested Keys (Dot Notation)
+
+A dot in a key name creates a nested structure in the output:
+
+```json
+{ "position.x=": "params.triggerCount", "position.y": 0 }
+```
+
+Produces:
+
+```json
+{ "position": { "x": <value>, "y": 0 } }
+```
+
+### Array Input
+
+If the incoming `params` is an array, the template is applied independently to each element and the output is an array of mapped objects. Set `arrayMode` to `"single"` to map the array as one value instead.
+
+### Nested and Array Templates
+
+A template that nests objects or contains arrays keeps its shape; every level is evaluated with the same rules, so a dynamic term can sit anywhere in the structure:
+
+```json
+[{ "role": "user" }, { "text=": "params.message" }]
+```
+
+---
+
+## Expression Scope
+
+Expressions have access to the incoming data via `params` and to a set of built-in functions:
+
+| Function | Signature | Description |
+|---|---|---|
+| `sin` | `sin(n)` | `Math.sin` |
+| `round` | `round(n)` | `Math.round` |
+| `min` | `min(a, b)` | `Math.min` |
+| `max` | `max(a, b)` | `Math.max` |
+| `rand` | `rand()` | `Math.random` — returns a float in [0, 1) |
+| `number` | `number(x)` | Converts a string to a number |
+| `string` | `string(x)` | Converts a value to a string |
+| `concat` | `concat(a, b)` | Concatenates two strings |
+| `join` | `join(arr, sep)` | An array's elements as one string, `sep` between them (none by default) |
+| `stringify` | `stringify(x)` | `JSON.stringify` |
+| `parse` | `parse(s)` | `JSON.parse` |
+| `sum` | `sum(arr)` | Sum of a numeric array |
+| `avg` | `avg(arr)` | Average of a numeric array |
+| `slice` | `slice(arr, offset, step, end)` | Slices and downsamples an array |
+| `moment` | `moment(...)` | [moment.js](https://momentjs.com/) date/time library |
+| `uuid.v4` | `uuid.v4()` | Generates a random UUID v4 |
+| `uuid.v7` | `uuid.v7()` | Generates a time-ordered UUID v7 |
+| `fromVault` | `fromVault(globalId)` | Reads a value from the user vault |
+| `toVault` | `toVault(globalId, value)` | Writes a value to the user vault |
+| `encodeURI` | `encodeURI(s)` | Standard `encodeURI` |
+| `reformatDate` | `reformatDate(date, inputFmt, outputFmt)` | Reformats a date string using moment.js |
+| `fromQueryParam` | `fromQueryParam(name)` | Reads a URL query parameter from `window.location` |
+| `fromStorage` | `fromStorage(name)` | Reads a value from `localStorage` |
+| `print` / `log` | `print(x)` | `console.log` (useful for debugging) |
+| `find` | `find(arr, 'item.x > 1')` | First element matching an expression-string predicate (`item`, `index` in scope) |
+| `filter` | `filter(arr, 'item.x > 1')` | All elements matching the predicate |
+| `isFuture` / `isPast` | `isFuture(ts)` | Timestamp checks for anything `Date` accepts |
+| `formatNow` | `formatNow('YYYY-MM-DD')` | Current time formatted with moment tokens |
+| `flatSum` | `flatSum(arr)` | Sum of a nested numeric array |
+| `at` | `at(arr, i)` | Element at a wrapped index |
+| `range` | `range(n)` | `[0, 1, … n-1]` |
+| `slug` | `slug(s)` | Lowercases and strips everything outside `[a-z0-9_-]` |
+| `now` | `now()` | Epoch milliseconds |
+| `withoutUrls` | `withoutUrls(s)` | Text with the web addresses removed, and the label that introduced one |
+
+`withoutUrls` is for text on its way to something that **speaks or summarises**
+it. A feed summary is often written for programs as much as for people — "Article
+URL: https://… Comments URL: https://… Points: 48" — which is a link to a reader
+and a minute of punctuation to a listener. The label goes with the address it
+introduced, since "Article URL:" with nothing after it says less than nothing.
+Never use it on what a board stores or publishes: there the address is the
+useful part.
+
+**Note:** `Math.cos` is not directly available. To compute cosine, use the identity `sin(θ + 1.5708)` (i.e. sin(θ + π/2)).
+
+**Runtime differences:** `moment`, `fromVault`, `toVault`, `fromQueryParam` and `fromStorage` exist only in the browser runtime — they need a browser or the user vault. hkp-rt, hkp-node and hkp-python provide everything else, including `reformatDate`/`formatNow` over the moment token subset `YYYY YY MMMM MMM MM M DD D dddd ddd HH H hh h mm m ss s A a` and `[escaped literals]` — except `withoutUrls`, which hkp-rt does not have yet.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `template` | `object` \| `array` | `{}` | The mapping template. See Template Syntax above. |
+| `mode` | `"replace"` \| `"add"` \| `"overwrite"` | `"replace"` | Controls how the output is merged with the input. |
+| `arrayMode` | `"array"` \| `"single"` | `"array"` | Whether an array input is mapped element by element or as one value. |
+| `sensingMode` | `boolean` | `false` | When `true`, the Map auto-learns the template from the first input then disables itself. |
+
+### `mode` Values
+
+| Value | Behaviour |
+|---|---|
+| `replace` | Output contains only the properties defined in the template. Input properties not in the template are discarded. |
+| `add` | Template properties are merged into the input, but existing input keys are **not** overwritten by template values — even when the input's value is `0`, `""`, `false` or `null`. |
+| `overwrite` | Input properties are merged first, then template properties overwrite them. |
+
+### `sensingMode`
+
+When `sensingMode: true`, the first input object that arrives is used to automatically construct a template (flattened key structure, static values). After this first input the service sets `sensingMode` back to `false` and returns `null` for that first item. Subsequent items are processed normally using the learned template.
+
+What is sensed is data, never something that runs: the input decides the shape of the
+template, not what the runtime evaluates. A field whose name ends in `=` is learned
+without the suffix — as the static field `pwned`, not as the expression `pwned=` —
+and on hkp-rt a key or text carrying an Inja marker is kept as that text rather than
+rendered.
+
+### `command.inject`
+
+Sending `{ command: { action: "inject", params: { ... } } }` causes the Map to immediately process the provided `params` through the template and emit the result downstream, without waiting for an external trigger.
+
+---
+
+## Errors and warnings
+
+What a pass says about itself is shown in the Map's panel and notified, so a facade
+[notice](../concepts/board.md) can read it too. While there is something to say it is
+also part of the Map's state, so a panel opened later shows it; configuring it does
+nothing. A pass that fails is [logged](../concepts/logging.md) as `service.failed`, for
+the board nobody is watching. Every runtime's Map behaves the same way.
+
+| Notified | When | The flow |
+|---|---|---|
+| `error` | A term does not parse — said as soon as the template is configured — or fails to evaluate, such as a call to a function that does not exist. Named by where the term sits: `x: nope is not a function`. Cleared (`""`) by the next pass that works. | **Stops**: the Map returns `null`, since a mapping that could not be made has nothing to pass on. With an array input, one failing element stops the whole pass. |
+| `warnings` | A term's value is empty because what it read was not there: `title: params.titel not found`. A read through a field that is there but `null` is one too: `name: params.author.name not found` for `{ "author": null }`. A read that a fallback covered (`params.id \|\| params.link` with only `link` present), or a field read directly that is present but `null` (`params.author`), is not a warning. | **Goes on**: an absent field is often legitimate, and a typo in a field name is only visible this way. |
+
+Both are `error: string` and `warnings: string[]` in the notification, and each is
+notified only when it changes.
+
+---
+
+## Example: Circle Animation
+
+Map a timer tick to a circle draw command using trigonometric functions:
+
+```json
+{
+  "type": "circle",
+  "x=": "sin(params.triggerCount * 0.05) * 40 + 50",
+  "y=": "sin(params.triggerCount * 0.05 + 1.5708) * 40 + 50",
+  "radius": 10,
+  "color": "#3498db"
+}
+```
+
+This produces a `circle` draw object whose `x` and `y` trace a circular path as `triggerCount` increments. Connect this Map to a Canvas service to animate the circle.
+
+---
+
+## hkp-rt: Inja Templates
+
+Alongside the `=`-suffix convention, the hkp-rt Map also renders **Inja** (a C++ Jinja2-like template engine) strings, so templates written before the shared dialect keep working. A string value — or a key — carrying `{{` or `{%` is rendered by Inja against the incoming data rather than evaluated as an expression:
+
+```json
+{ "angle": "{{ value }}" }
+```
+
+Note the difference in scope: an Inja template addresses the incoming data directly (`{{ value }}`), while an expression addresses it through `params` (`"angle=": "params.value * 0.1"`). Inja's own filters and functions apply inside `{{ }}`; the built-in table above applies inside expressions.
+
+`{% include %}` is not available: it would read the file it names past the
+[files guard](../concepts/runtime.md#where-a-board-may-read-and-write-files), so a template that includes one renders as a
+failure and is kept as its text.
+
+---
+
+## An address a board mentions
+
+A `hkp-mount://<runtimeId>/<serviceUuid>` value anywhere in what a template
+produces becomes the address it names, once the board's coordinator has
+resolved it:
+
+```json
+{ "template": { "audioBase": "hkp-mount://library.files/listen" } }
+```
+
+This is for a board that has to **mention** an endpoint — an enclosure URL in a
+feed, a link somebody is handed, an address written into a document — as against
+dialling one, which `http-client` does with the same reference in the field it
+calls. The address is assigned when the board loads, so it cannot be written
+down in advance.
+
+It applies to what the template *produced*, so a reference an expression
+returned is covered as well as one written as a static value.
+
+An unresolved reference is **left as it stands**: the owner has not published
+yet, and a value that still says `hkp-mount://…` is visibly not an address,
+where an empty string would look like a field nobody filled in. One address per
+service, so one reference per Map.
+
+Available on hkp-node and hkp-python.

package/bundle/docs/content/services/match-filter.md

@@ -0,0 +1,38 @@
+# Match Filter
+
+Drops string values that contain any of the configured filter terms, passing all others through.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/match-filter` |
+
+---
+
+## What it does
+
+Match Filter checks whether the incoming string contains any of the strings in `filterByTerms` (substring match). If a match is found, the value is suppressed (returns `null`). If no match is found, the value is forwarded unchanged.
+
+Use Match Filter as a content blocker — for example, to suppress log lines containing specific keywords, or to filter chat messages that include banned phrases.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `filterByTerms` | `string[]` | `undefined` | List of substrings to block. Any input containing one of these strings is dropped. |
+
+If `filterByTerms` is not set, all values pass through.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value — matched using `String.indexOf` |
+| **Output** | The original input if no filter term matches; `null` if any term matches |

package/bundle/docs/content/services/microphone-monitor.md

@@ -0,0 +1,66 @@
+# Microphone Monitor
+
+Measures the current microphone input level at a configurable interval and emits the result into the pipeline.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/microphone-monitor` |
+
+---
+
+## What it does
+
+Microphone Monitor requests access to the user's microphone via `navigator.mediaDevices.getUserMedia`, connects the stream to a Web Audio `AnalyserNode`, and samples the RMS amplitude at a configurable interval. Each sample is emitted downstream as `{ level, levelDb }`.
+
+The service is independent of the pipeline trigger — it fires on its own timer, not in response to upstream values.
+
+---
+
+## Prerequisites
+
+- Must run on HTTPS or `localhost` (requires a secure context).
+- The browser will prompt the user for microphone permission the first time the service starts.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `interval` | `number` | `500` | Sampling interval in milliseconds |
+| `running` | `boolean` | `false` | `true` to start capturing; `false` to stop |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Ignored — Microphone Monitor emits independently on its own timer |
+| **Output** | `{ level: number, levelDb: number }` — linear amplitude (0–1) and dB value |
+
+---
+
+## Status values
+
+The UI panel shows a `status` string that transitions through:
+
+| Status | Meaning |
+|---|---|
+| `"requesting mic..."` | Waiting for permission |
+| `"active"` | Capturing and emitting |
+| `"error: <message>"` | Permission denied or capture failed |
+
+---
+
+## Typical pipeline
+
+```
+Microphone Monitor → Map → Canvas
+```
+
+Map the `levelDb` value to a bar height and draw it on a Canvas to build a simple VU meter.

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

@@ -0,0 +1,67 @@
+# Monitor
+
+Displays the current pipeline value in a scrolling log; passes data through unchanged.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/monitor` |
+| hkp-rt | `monitor` |
+
+---
+
+## What it does
+
+Monitor is a purely observational service — it shows what is currently
+flowing through the pipeline without modifying it. Every value that
+arrives is displayed in the service's UI panel and the original value is
+passed to the next service unmodified.
+
+Use Monitor anywhere in a pipeline to inspect intermediate values while
+building or debugging a board.
+
+---
+
+## Configuration
+
+### Browser
+
+The browser Monitor has no required configuration. The UI panel shows
+each incoming value as formatted JSON in a scrolling list.
+
+### hkp-rt
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `logToConsole` | `boolean` | `true` | Print each value to the server's stdout |
+| `fileLogPath` | `string` | `""` | Append each value to this file, inside the folders boards are given ([Filesystem](./filesystem.md#where-the-files-are)); a relative path is taken from the default one |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value |
+| **Output** | Identical to input — passes through unchanged |
+
+Monitor never returns `null`; it always forwards whatever it receives.
+
+---
+
+## Typical use
+
+Place a Monitor at any point in a pipeline to see what data is at that stage:
+
+```
+Timer → Map → Monitor → Canvas
+                ↑
+         inspect here
+```
+
+In production boards a Monitor with `bypass: true` can be left in place
+as a zero-cost debug tap that can be re-enabled without editing the board
+configuration.