@readymadeit/mcp 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,70 @@
+# Buffer
+
+Accumulates pipeline values into an array and flushes them as a batch when a capacity or time threshold is reached.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/buffer` |
+
+---
+
+## What it does
+
+Buffer collects incoming values and holds them in an internal array. The accumulated batch is emitted downstream in two ways:
+
+- **Capacity flush** — when the number of buffered items reaches `capacity`, the batch is emitted and the buffer is cleared.
+- **Interval flush** — when `interval` is set, a timer fires every `interval` milliseconds and emits the current contents (even if not full), then clears the buffer.
+
+Both can be active simultaneously; whichever threshold is crossed first triggers the flush.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `capacity` | `number` | `100` | Maximum number of items before an automatic flush |
+| `interval` | `number` | `-1` | Flush interval in milliseconds. `-1` disables timer-based flushing |
+| `accumulatedOutput` | `boolean` | `false` | When `true`, each flush emits the full accumulated buffer since the last `clear` rather than just the current window |
+| `action: "clear"` | — | — | Discards all buffered items |
+| `command: { action: "flush" }` | — | — | Immediately flushes the current buffer |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value (arrays are concatenated into the buffer) |
+| **process() return** | Always `null` — flushing happens asynchronously via `app.next()` |
+| **Flush emission** | Array of all buffered values |
+
+---
+
+## Example: batch 20 events then process
+
+```json
+{
+  "serviceId": "hookup.to/service/buffer",
+  "config": { "capacity": 20 }
+}
+```
+
+Incoming values accumulate silently until 20 have arrived; then the array of 20 is emitted downstream.
+
+---
+
+## Example: flush every 2 seconds
+
+```json
+{
+  "serviceId": "hookup.to/service/buffer",
+  "config": { "interval": 2000, "capacity": 10000 }
+}
+```
+
+Whatever has accumulated over the past 2 seconds is emitted as a batch, regardless of count.

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

@@ -0,0 +1,92 @@
+# Cache
+
+Stores and retrieves pipeline values by key; avoids redundant downstream computation for repeated inputs.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/cache` |
+| hkp-rt | `cache` |
+
+---
+
+## What it does
+
+Cache intercepts each incoming value, checks whether a cached result for the current key already exists, and if so returns it immediately — skipping the rest of the pipeline for that input. If no cached value exists, the data is forwarded downstream; when a result comes back, it is stored under the key for future use.
+
+### Browser runtime
+
+The browser Cache is a general-purpose in-memory store that can be merged incrementally. It supports two update strategies (controlled by `updateTrigger`):
+
+- **`config`** — the cache is updated when `configure()` is called with `cache+` or `cacheProperties+`.
+- **`process`** — the cache is updated on each pipeline tick (the incoming value is merged in).
+
+Its panel shows one row per cached property — the current value beside its `initial` one, bold where they differ — and updates live as the cache changes. The board keeps only `initial` and `updateTrigger`; the gathered values start over from `initial` on every load.
+
+### hkp-rt
+
+The hkp-rt Cache caches the result of downstream pipeline processing (i.e. the return value of `next(data)`) using a string key derived from the input. Results can optionally be persisted to disk so they survive restarts.
+
+---
+
+## Configuration
+
+### Browser
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `initial` | `any` | `undefined` | Initial cache value |
+| `updateTrigger` | `"config"` \| `"process"` | `"config"` | When the cache is updated |
+| `cache+` | `object` | — | Merges the given object into the cached value |
+| `cacheProperties+` | `string[]` | — | List of property names to pluck from the config and merge |
+| `cacheMeta.triggerProcess` | `boolean` | `false` | When `true`, fires the cached value downstream after updating |
+
+### hkp-rt
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `key` | `string` | `""` | Inja template evaluated against the input to produce the cache key |
+| `outputKey` | `string` | `"path"` | Key under which the cached file path is returned |
+| `persistRoot` | `string` | `""` | Folder for on-disk persistence, inside the folders boards are given ([Filesystem](./filesystem.md#where-the-files-are)); a relative path is taken from the default one. Empty, or outside them, = memory only |
+| `persistMode` | `string` | `""` | `"sha"` (default) or `"filename"` — controls how the on-disk filename is derived |
+| `filenameTemplate` | `string` | `""` | Inja template for the filename when `persistMode` is `"filename"`. What it renders stays inside `persistRoot`, whatever the input puts in it |
+| `cacheDuration` | `string` | `""` | Max age before a cached entry is considered stale (e.g. `"24h"`, `"7d"`) |
+| `excluded` | `string[]` | `[]` | List of regex patterns; keys matching any pattern bypass the cache |
+
+---
+
+## Input / Output
+
+### Browser
+
+| | Shape |
+|---|---|
+| **Input** | Any value |
+| **Output** | Cached value (or updated cache value after merge) |
+
+### hkp-rt
+
+| | Shape |
+|---|---|
+| **Input** | Any — key template is evaluated against it |
+| **Output** | The cached downstream result (early-return), or the freshly computed result after forwarding |
+
+---
+
+## Example (hkp-rt): cache HTTP responses for 24 hours
+
+```json
+{
+  "serviceId": "cache",
+  "config": {
+    "key": "{{ params.url }}",
+    "persistRoot": "http-cache",
+    "cacheDuration": "24h"
+  }
+}
+```
+
+Place this before an `http-client` service. The first request for each URL hits the network; subsequent requests within 24 hours are served from disk.

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

@@ -0,0 +1,85 @@
+# Camera
+
+Captures frames from the device camera and emits them as image Blobs.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/camera` |
+
+---
+
+## What it does
+
+Camera connects to the device's camera (webcam or phone camera) and,
+when triggered, captures a snapshot as a Blob. The Blob can be passed
+to a Canvas service (`type: "image"`) for display, or to an Output
+service to stream frames to a server.
+
+The capture is **on-demand** — it happens when the service receives a
+pipeline trigger or when `action: "triggerSnapshot"` is sent via
+`configure`. The camera does not continuously push frames; pair it with
+a Timer to achieve periodic capture.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `captureAs` | `"image"` | `"image"` | Output format (currently `"image"` only) |
+| `captureFormat` | `string` | `"image/png"` | MIME type of the captured Blob (e.g. `"image/jpeg"`) |
+
+### Commands
+
+| `action` | Description |
+|---|---|
+| `"triggerSnapshot"` | Capture a frame immediately and fire it through the pipeline via `app.next()` |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value — receipt of any upstream data triggers a capture |
+| **Output** | `{ image: Blob }` — an object with the image `Blob` under the key set by `captureAs` (default `"image"`) |
+
+If `captureAs` is empty, the raw `Blob` is emitted directly rather than wrapped in an object.
+
+---
+
+## Permissions
+
+The browser will prompt for camera permission the first time the service
+connects. If permission is denied, the service will not capture frames.
+
+---
+
+## Example: periodic webcam snapshots to Canvas
+
+```json
+[
+  {
+    "serviceId": "hookup.to/service/timer",
+    "state": { "periodicValue": 500, "periodicUnit": "ms", "periodic": true, "running": true }
+  },
+  {
+    "serviceId": "hookup.to/service/camera",
+    "state": { "captureFormat": "image/jpeg" }
+  },
+  {
+    "serviceId": "hookup.to/service/map",
+    "state": {
+      "template": { "type": "image", "data=": "params" }
+    }
+  },
+  {
+    "serviceId": "hookup.to/service/canvas",
+    "state": { "size": [640, 480], "clearOnRedraw": true }
+  }
+]
+```

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

@@ -0,0 +1,196 @@
+# Canvas
+
+Renders 2D draw commands — text, shapes, images, and video — onto an HTML canvas element.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/canvas` |
+
+---
+
+## What it does
+
+The Canvas service receives a draw object (or array of draw objects) from
+the pipeline and renders them onto an HTML `<canvas>` element displayed
+in its service card. Each frame the canvas is optionally cleared before
+drawing, creating smooth animations.
+
+The service does not emit data downstream by default. In **capture mode**
+it encodes each rendered frame as a Blob and emits it, allowing
+downstream services to record, stream, or process frames.
+
+---
+
+## Canvas configuration
+
+Set via the service's `state` in the Board Blueprint or through the UI.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `size` | `[number, number]` | `[480, 240]` | Canvas width and height in pixels |
+| `clearOnRedraw` | `boolean` | `true` | Fill with white before each frame |
+| `resizable` | `boolean` | `true` | Allow the user to drag-resize the canvas |
+| `fullscreen` | `boolean` | `false` | Expand to fill the available viewport |
+| `capture` | `boolean` | `false` | Encode each frame as a Blob and emit downstream |
+| `captureMime` | `string` | `"image/png"` | MIME type for captured frames |
+
+---
+
+## Coordinate system
+
+All positional values (`x`, `y`, `width`, `height`, `radius`) accept:
+
+- **Numbers** — absolute pixel positions
+- **Percentage strings** — `"50%"` resolves relative to the canvas
+  dimension in that axis (`"50%"` on a 400 px wide canvas → 200 px)
+
+When `x` or `y` are omitted from a draw element, the element is
+horizontally or vertically centred.
+
+---
+
+## Draw element types
+
+Pass a single object or an **array** of objects. Each object must have a
+`type` field.
+
+### `text`
+
+Renders a text string.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `text` | `string` | — | The string to render |
+| `x` | `number \| string` | centred | Left edge of the text baseline |
+| `y` | `number \| string` | centred | Vertical text baseline position |
+| `font` | `string \| FontObject` | browser default | CSS font string or font object |
+| `color` | `string` | `"#000"` | Fill colour |
+| `contour` | `{color, lineWidth?}` | — | Optional text outline |
+| `textTransform` | `string` | — | `"uppercase"`, `"lowercase"`, `"lowercase-spacing-1"`, … |
+| `onClick` | `action` | — | Action dispatched when the text area is clicked |
+
+**Font object:**
+
+```json
+{ "style": "italic", "weight": "bold", "size": "24px", "family": "Arial" }
+```
+
+`size` may also be a percentage string (`"5%"`) relative to canvas width.
+
+### `circle`
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `x` | `number \| string` | centred | Centre X |
+| `y` | `number \| string` | centred | Centre Y |
+| `radius` | `number \| string` | — | Radius in px or `%` of canvas height |
+| `color` | `string` | — | Fill colour |
+| `contour` | `{color, lineWidth?}` | — | Stroke |
+| `gradient` | `{from, to, colors[]}` | — | Radial gradient descriptor |
+
+### `rect` / `square`
+
+`square` is an alias for `rect`.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `x` | `number \| string` | centred | Left edge |
+| `y` | `number \| string` | centred | Top edge |
+| `width` | `number \| string` | — | Width |
+| `height` | `number \| string` | — | Height |
+| `length` | `number \| string` | — | Sets both `width` and `height` (square shorthand) |
+| `color` | `string` | — | Fill colour |
+| `contour` | `{color, lineWidth?}` | — | Stroke |
+
+### `image`
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `url` | `string` | — | Remote image URL (cached after first fetch) |
+| `data` | `Blob \| HTMLImageElement` | — | Inline image data |
+| `x` | `number \| string` | centred | X position of the image centre |
+| `y` | `number \| string` | centred | Y position of the image centre |
+| `height` | `number \| string` | natural | Rendered height (aspect-ratio preserved) |
+| `opacity` | `number` | `1` | Alpha (0–1) |
+| `rotate` | `number` | `0` | Turn in degrees, about the image's own centre |
+| `scale` | `number` | `1` | Scale factor, about the image's own centre |
+| `unscaled` | `boolean` | `false` | Draw at natural pixel size |
+| `onClick` | `action` | — | Click handler |
+
+### `video`
+
+Renders a single frame from a video Blob.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `data` | `Blob` | — | Video data |
+| `x` | `number \| string` | `0` | X position |
+| `y` | `number \| string` | `0` | Y position |
+| `width` | `number \| string` | canvas width | Rendered width |
+| `height` | `number \| string` | canvas height | Rendered height |
+
+### `array`
+
+Renders a 1D numeric array as a vertical bar chart.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `data` | `number[]` | — | Array of values |
+| `color` | `string` | `"#000"` | Bar fill colour |
+
+### `array2d`
+
+Renders a 2D numeric array as a grid of coloured cells.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `data` | `number[][]` or flat `number[]` | — | Grid data |
+| `cols` | `number` | — | Number of columns (required for flat arrays) |
+| `rows` | `number` | — | Number of rows |
+
+### `explainer`
+
+Renders a pointer line with a label — useful for annotating other elements.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `pointer` | `{x, y, length}` | — | Start point and line length |
+| `direction` | `"left" \| "right"` | `"right"` | Direction the line extends |
+| `text` | `string` | — | Label text |
+| `font` | `string \| FontObject` | — | Font |
+| `color` | `string` | `"#000"` | Colour |
+| `textTransform` | `string` | — | Text transform |
+
+---
+
+## Multiple elements in one frame
+
+Pass an array to draw several elements per frame:
+
+```json
+[
+  { "type": "circle", "x": 200, "y": 150, "radius": 120, "contour": { "color": "#ccc", "lineWidth": 1 } },
+  { "type": "text",   "x": 280, "y": 150, "text": "HKP", "color": "#3b82f6", "font": "bold 22px Arial" }
+]
+```
+
+---
+
+## Capture mode
+
+When `capture: true`, after each render the canvas is encoded as a Blob
+(format controlled by `captureMime`) and emitted downstream. This allows
+you to chain a Canvas with an Output service to stream frames over a
+WebSocket, or a Buffer to batch frames.
+
+```json
+{
+  "size": [640, 480],
+  "capture": true,
+  "captureMime": "image/jpeg"
+}
+```

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

@@ -0,0 +1,87 @@
+# Changes
+
+Lets the input through only when what it watches has changed since the last input — a stream of reports becomes a stream of events.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/changes` |
+
+---
+
+## What it does
+
+Many sources report a state over and over: a detector says how many faces it
+sees on every frame, a poll returns the same status every minute, a sensor
+reads the same level for an hour. What a board usually wants to act on is the
+moment that state **changes** — a face appeared, the status went red.
+
+Changes remembers what it watched last time. Each input is compared with it:
+
+- **Any change** (`change`) passes the input when the watched value differs.
+- **Becomes true** (`rise`) passes it when the value turns truthy — `false` to
+  `true`, `0` to `3`.
+- **Becomes false** (`fall`) passes it when the value turns falsy.
+
+Otherwise it returns `null` and the pipeline stops there, like
+[Filter](filter.md). What passes is always the **input itself**, unchanged — the
+watched value only decides whether it goes on.
+
+Values are compared by what they say: an object rebuilt on every input with the
+same content is not a change, and the same object arriving with other content
+is. Binary content that cannot be read this way — a
+`Blob`, an `ArrayBuffer`, an image — counts as changed whenever it is a
+different object, on its own or as a field of the value watched.
+
+It is the change-detection half of a problem [Debounce](debounce.md) does not
+solve. Debounce limits how often something fires; a state that stays true still
+fires once per cooldown. Changes fires once per change, however long the state
+lasts — and the two combine, when a noisy source would otherwise flicker.
+
+### What it remembers
+
+Before the first input nothing has been seen, and the remembered value counts
+as `undefined`: a truthy first value is a rise, any first value is a change,
+and a falsy one is not a fall.
+
+What it remembers is **live state**, shown in its panel, and not saved with the
+board — like a Timer's `running`. A board opened again starts from nothing seen,
+so a face already in view when it opens is reported. **Forget** in the panel (or
+`reset`) clears it, and so does changing the watched expression.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | `""` | An expression over `params` — what to watch. Empty watches the whole input |
+| `emit` | `"change"` \| `"rise"` \| `"fall"` | `"change"` | Which change lets the input through |
+| `reset` | `boolean` | — | Forgets what was remembered (an action, not state) |
+
+The expression uses the same language and functions as [Map](map.md) and
+[Filter](filter.md): `params.count > 0`, `params.status`, `round(params.level)`.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Anything |
+| **Output** | The input, unchanged, when the watched value changed as `emit` asks; otherwise `null` |
+
+---
+
+## Typical uses
+
+A face appears (see the [Face Alert](../boards/face-alert-board.md) board):
+
+Timer → Camera → [Detect](detect.md) → **Changes** (`params.count > 0`, rise) → Debounce → Map → ntfy block
+
+A reading moves to another level, reported once rather than every second:
+
+Timer → Map `{ "level=": "round(rand() * 3)" }` → **Changes** (`params.level`) → Monitor

package/bundle/docs/content/services/chunked-file-provider.md

@@ -0,0 +1,63 @@
+# Chunked File Provider
+
+Splits a file selected by the user into fixed-size chunks and emits each chunk sequentially as a `ChunkPayload`.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/chunked-file-provider` |
+
+---
+
+## What it does
+
+Chunked File Provider presents a file picker in its UI panel. When the user selects a file and clicks **Process**, the service reads the file as an `ArrayBuffer`, divides it into chunks of up to `chunkSize` bytes, and emits one `ChunkPayload` object per chunk via `app.next()`.
+
+This is the source service for large file uploads. Pair it with [HTTP Uploader](./http-uploader.md) to stream a file to a server endpoint that can reassemble the chunks.
+
+---
+
+## Default chunk size
+
+3 MB (3 × 1024 × 1024 bytes) — chosen to stay under typical 4 MB API gateway payload limits.
+
+---
+
+## Output shape
+
+Each emitted value is a `ChunkPayload`:
+
+```typescript
+{
+  data: ArrayBuffer;      // raw bytes of this chunk
+  filename: string;       // original filename with a timestamp suffix appended
+  mimeType: string;       // MIME type of the file
+  chunkIndex: number;     // 0-based index of this chunk
+  totalChunks: number;    // total number of chunks for this file
+  uploadId: string;       // UUID shared across all chunks of the same file send
+}
+```
+
+The `uploadId` is a unique UUID generated per file send so the server can group chunks belonging to the same upload.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Triggered by the UI — no pipeline input consumed |
+| **Output** | `ChunkPayload` — one emission per chunk |
+
+---
+
+## Typical pipeline
+
+```
+Chunked File Provider → HTTP Uploader
+```
+
+Chunked File Provider slices the file; HTTP Uploader POSTs each chunk to a server endpoint that reassembles them.