@readymadeit/mcp 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,101 @@
+# Detect
+
+Finds faces in an image, on the device, and reports where they are on every frame — none included.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/detect` |
+
+---
+
+## What it does
+
+Detect looks at the image in its input and reports what it finds. It runs
+Google's [MediaPipe Tasks Vision](https://ai.google.dev/edge/mediapipe/solutions/vision/face_detector)
+in the page, with the model and its WebAssembly runtime shipped with the app:
+nothing is sent anywhere, and it works offline in the native apps.
+
+It is a reporter. Every frame produces a report — `count: 0` when nothing is
+there — so the pipeline after it can see absence as well as presence. Deciding
+what a finding *means* is the pipeline's job: [Changes](changes.md) turns "a
+face is there" into "a face appeared", [Filter](filter.md) keeps frames with
+more than one, [Debounce](debounce.md) spaces out what follows.
+
+### Modes
+
+| Mode | Finds | Model |
+|---|---|---|
+| `face` | Faces, with a bounding box and six keypoints (eyes, ears, nose, mouth) | BlazeFace short-range — faces within about two metres of the camera |
+
+The service is scoped by what it does — finding things in an image — so further
+modes (objects, hands) belong here, each reporting under its own key.
+
+### Loading
+
+The model is loaded when the service is first configured — which a board does
+when it opens — so the first frame usually does not wait. The panel says
+whether it is loading, ready or failed. A board without a Detect service never
+downloads any of it: the runtime (about 11.8 MB, 3.5 MB compressed) and the
+model (230 KB) are separate files, fetched on first use.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `mode` | `"face"` | `"face"` | What to look for |
+| `minConfidence` | `number` | `0.5` | Detections scoring below this (0–1) are left out |
+
+The panel shows the last frame with each finding outlined, so the threshold can
+be set by eye. A facade shows the same view with a `detect` widget:
+
+```json
+{ "type": "detect", "serviceUuid": "detect-svc", "width": 320 }
+```
+
+Pair it with the camera widget's `"preview": false`, which still captures but
+draws nothing, so the frame appears once — as the board sees it.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | An image: a `Blob`, an object with an `image` field (what [Camera](camera.md) sends), an `ImageBitmap`, or an image, canvas or video element |
+| **Output** | The input with the findings added: `{ ...input, faces, count, frame }`. A bare image travels on as `image` |
+
+```json
+{
+  "image": "<Blob>",
+  "count": 1,
+  "frame": { "width": 640, "height": 480 },
+  "faces": [
+    {
+      "score": 0.93,
+      "box": { "x": 212, "y": 96, "width": 180, "height": 180 },
+      "keypoints": [{ "x": 260, "y": 150 }, { "x": 340, "y": 152 }]
+    }
+  ]
+}
+```
+
+Boxes and keypoints are in pixels of `frame`. An input with no image in it
+stops the pipeline and is reported in the panel.
+
+---
+
+## Typical uses
+
+Tell someone when a face appears — the [Face Alert](../boards/face-alert-board.md) board:
+
+Timer → Camera → **Detect** → [Changes](changes.md) (`params.count > 0`, rise) → Debounce → Map → ntfy block
+
+Count the people in front of a screen:
+
+Timer → Camera → **Detect** → Map `{ "people=": "params.count" }` → Monitor

package/bundle/docs/content/services/document-extract.md

@@ -0,0 +1,174 @@
+# Document Extract
+
+Turns a document into text a model can read — and says how well it went.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Node.js (hkp-node) | `document-extract` |
+
+---
+
+## What it does
+
+Document Extract takes bytes and produces text. The natural producer is
+anything that yields bytes — `http-client`, an email attachment, a `file-pick`
+widget — and the natural consumer is `text-generation`.
+
+Alongside the text it reports **how much there was to find**, which is the more
+interesting half. A PDF with a text layer gives thousands of characters a page;
+a scan of the same document gives almost none. That difference is reported as
+`sparse`, and a board branches on it.
+
+### OCR runs when it is needed
+
+A scanned page is read by an OCR engine **in this process** — no network, no
+per-page charge — so it happens by default. Leaving it off would hand back an
+empty document rather than save anything.
+
+| `ocr` | What gets read |
+|---|---|
+| `"auto"` (default) | Images always; a scanned PDF page by page; a PDF that already has a text layer, not at all |
+| `"off"` | Text layers only. A scan comes back empty |
+| `"force"` | Every page, even where a text layer exists — what a *bad* text layer needs, such as a scan wrapped in a PDF by an office suite |
+
+What stays off is the **paid** tier: a vision model reading pages an OCR engine
+could not. That one costs per page, so it is a board's decision. `sparse` is the
+signal to make it on:
+
+```
+document-extract  →  switch (sparse)  →  ┬ false: text-generation
+                                         └ true:  a vision model, or a person
+```
+
+With OCR on, `sparse` means a local engine could not read the pages either —
+which is a much stronger signal than "this PDF has no text layer".
+
+---
+
+## Backends
+
+| `backend` | Reads | Needs |
+|---|---|---|
+| `xberg` (default) | PDF, DOCX, XLSX, PPTX, archives, email, images, and ~100 more — with page counts, tables, OCR, and a confidence model | `npm install @xberg-io/xberg` |
+| `builtin` | Text, HTML, JSON, CSV, Markdown | nothing |
+
+**`@xberg-io/xberg` is not a dependency of hkp-node.** Its platform binaries run
+to about 150 MB each and most boards never read a document, so it is installed
+separately and reported as missing rather than assumed:
+
+```
+npm install @xberg-io/xberg
+```
+
+It is MIT-licensed, ships prebuilt binaries for six platforms (no Rust
+toolchain at install time), has no runtime dependencies of its own, and needs
+Node 22 or newer.
+
+### Picking an OCR engine
+
+`ocrBackend` selects one; left empty, the library picks. They differ in what
+they need on the machine:
+
+| Engine | Needs |
+|---|---|
+| `paddleocr`, `sceptre`, and the `candle-*` family | Nothing to install — model weights download from Hugging Face on first use and are cached |
+| `tesseract` | **A system install.** `brew install tesseract` / `apt-get install tesseract-ocr`, plus a language pack per language |
+
+The first document through a downloading engine pays for the download, which on
+a deployed board looks like one very slow request. Warm it with a document
+before anyone depends on the timing.
+
+`ocrLanguage` takes `"deu"`, `"deu,eng"`, or `["deu", "eng"]`.
+
+The `builtin` backend needs nothing and reads what `http-client` typically
+brings back. Asked for a PDF it says so and stops — decoding one as UTF-8 would
+look like a successful extraction of gibberish, which is worse than an error.
+
+The `backend` field exists from the first version because the library is young.
+Swapping it must not mean touching a board.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `backend` | `string` | `"xberg"` | `xberg` or `builtin` |
+| `ocr` | `string` | `"auto"` | `auto`, `off`, or `force` — see above. `true`/`false` are read as `auto`/`off` |
+| `ocrBackend` | `string` | `""` | OCR engine (`paddleocr`, `tesseract`, `sceptre`, …). Empty lets the library pick |
+| `ocrLanguage` | `string\|string[]` | `[]` | `"deu"`, `"deu,eng"`, or `["deu","eng"]`. Empty uses the library's default |
+| `tables` | `bool` | `false` | Include extracted tables in the output |
+| `metadata` | `bool` | `false` | Include document metadata (author, title, dates) |
+| `maxChars` | `number` | `0` | Cap the text handed on; `0` = no cap. Sets `truncated` when it bites |
+| `minCharsPerPage` | `number` | `100` | Below this, a page counts as having no text |
+| `minTextCoverage` | `number` | `0.6` | Below this fraction of pages carrying text, the document is sparse |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | `{ meta: { contentType, filename }, binary }` (what `http-client` produces), a `Uint8Array`, `{ meta, body }`, or a `String` |
+| **Output** | `{ text, chars, pages, charsPerPage, sparse, method, format, backend, durationMs, truncated?, textCoverage?, confidence?, metadata?, tables? }` |
+
+| Field | Means |
+|---|---|
+| `sparse` | **The one to branch on.** Too little text came back to trust, whatever was tried to get it |
+| `chars` | Characters found, before any `maxChars` cap |
+| `charsPerPage` | Density. A page-less document counts as one page |
+| `textCoverage` | Fraction of pages with a usable text layer (`xberg` only) |
+| `confidence` | The backend's own combined score, `0`–`1` (`xberg` only) |
+| `method` | `native`, `ocr`, or `mixed` |
+
+`sparse` prefers `textCoverage` where the backend reports it: density can only
+infer which pages produced text, while the backend knows. A document dense on
+two pages out of twenty is still mostly unreadable, and only coverage sees that.
+
+It reads bytes, not URLs. A document behind a link is `http-client`'s job —
+which keeps fetching, with everything that implies about what a server may be
+asked to reach, in the service that already answers for it.
+
+**The text is the service's answer.** Extraction takes long enough to matter,
+and the runtime awaits it, so the services after it run with the text once it
+exists — and a [Join](./join.md) around it comes back with the text beside what
+it already had, which is how a fetched page is read without losing the record it
+belongs to.
+
+Anything that goes wrong — an encrypted PDF, a missing backend, an empty
+document — is reported as `{ error }` and passes nothing on. A board that
+carried on here would summarise an empty string as though the document had said
+nothing.
+
+---
+
+## Status notifications
+
+| `status` | Meaning |
+|---|---|
+| `idle` | Ready; last document finished |
+| `extracting` | Reading in progress |
+| `error` | Something failed (input, backend, or document) |
+
+---
+
+## Example
+
+The attached demo board reads a document and extracts structured fields from
+it: `http-client` fetches → `document-extract` reads → `text-generation` with a
+`jsonSchema` turns it into fields → `monitor` shows them.
+
+```json
+{
+  "node": [
+    { "serviceId": "http-client", "state": { "url": "https://example.com/offer.pdf" } },
+    { "serviceId": "document-extract", "state": { "backend": "xberg" } },
+    { "serviceId": "text-generation", "state": { "jsonSchema": { "type": "object" } } },
+    { "serviceId": "monitor" }
+  ]
+}
+```

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

@@ -0,0 +1,67 @@
+# Download
+
+Saves whatever reaches it as a file, through the browser's own download, and passes it on.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/download` |
+
+---
+
+## What it does
+
+Download turns its input into a file and hands it to the browser to save, the
+way a link to a file would:
+
+| Input | Saved as | Type, unless `mimeType` says otherwise |
+|---|---|---|
+| text | the text itself | `text/plain;charset=utf-8` |
+| bytes (`Uint8Array`, `ArrayBuffer`) | the bytes | `application/octet-stream` |
+| anything else | its JSON, indented | `application/json` |
+
+The input then travels on **unchanged**, so a Download can sit in the middle of
+a pipeline — saving a copy of what passes — as well as at its end. Nothing
+arriving (`null`, `undefined`) saves nothing.
+
+Each save is reported as `{ saved, bytes }`, and a failure as `{ error }`.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `filename` | `string` | `"download.txt"` | What the file is offered as |
+| `mimeType` | `string` | `""` | The file's type; empty decides it from the input, as above |
+
+A board that saves different things configures `filename` before each one — a
+facade `repeat` can write it from the item, e.g. `"{{item.name}}.sql"`.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | text, bytes, or any JSON value |
+| **Output** | the input, unchanged |
+
+---
+
+## Typical uses
+
+- [SQL](./sql.md) (`export`) → Download: a browser database as an `.sql` file,
+  as the [SQL Explorer](../boards/sql-explorer-board.md) does.
+- Map → Download: whatever a pipeline has gathered, as JSON.
+
+---
+
+## Notes
+
+The download is the browser's: where the file lands, and whether it asks
+first, is the browser's setting. Inside the Readymade apps a webview may not
+act on a browser download at all.

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

@@ -0,0 +1,63 @@
+# Encode
+
+Encodes or decodes values using Base64 or URL encoding.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/encode` |
+
+---
+
+## What it does
+
+Encode applies a reversible text transformation to pipeline values. The operating **mode** selects the algorithm:
+
+| Mode | Description |
+|---|---|
+| `base64-encode` | UTF-8-safe Base64 encoding. Non-string inputs are JSON-stringified first. |
+| `base64-decode` | Decodes a Base64 string; the result is parsed as JSON if valid, otherwise returned as a plain string. |
+| `url-encode` | Applies `encodeURIComponent`. Non-string inputs are JSON-stringified first. |
+| `url-decode` | Applies `decodeURIComponent`. The result is parsed as JSON if valid. |
+| `hex-encode` | Encodes to lowercase hex. Non-string inputs are JSON-stringified first. |
+| `hex-decode` | Decodes a hex string back to UTF-8. The result is parsed as JSON if valid. Whitespace is ignored. |
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `mode` | `"base64-encode"` \| `"base64-decode"` \| `"url-encode"` \| `"url-decode"` \| `"hex-encode"` \| `"hex-decode"` | `"base64-encode"` | Operating mode |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input (encode modes)** | Any value — strings are encoded as-is; other values are JSON-stringified first |
+| **Output (encode modes)** | Encoded string |
+| **Input (decode modes)** | Encoded string |
+| **Output (decode modes)** | Decoded value — parsed as JSON if valid; otherwise the raw decoded string |
+
+Returns `null` (with an error notification) if a decode operation receives invalid input.
+
+---
+
+## Typical uses
+
+**Embed structured data in a URL query parameter:**
+
+```
+Map → Encode (url-encode) → QR Code
+```
+
+**Round-trip an object through a text channel:**
+
+```
+Injector → Encode (base64-encode) → ... → Encode (base64-decode) → Monitor
+```

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

@@ -0,0 +1,53 @@
+# Encrypt
+
+Encrypts any pipeline value using AES-256-GCM and emits a self-contained base64 ciphertext string.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/encrypt` |
+
+---
+
+## What it does
+
+Encrypt serialises the incoming value to JSON (or, for `Blob`/`File` inputs, encodes it to base64 first), encrypts the result with AES-256-GCM, prepends a freshly generated 12-byte random IV, and base64-encodes the whole payload.
+
+The output is a portable string that can be stored, transmitted, or embedded in a URL. Use [Decrypt](./decrypt.md) with the same secret to recover the original value.
+
+### Key derivation
+
+The secret is hashed with SHA-256 to produce a 256-bit AES-GCM key. A new random IV is generated on every `process()` call so identical inputs produce different ciphertexts.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `secret` | `string` | `""` | Shared secret used to derive the encryption key |
+| `method` | `"aes"` | `"aes"` | Encryption method (only AES-GCM is currently supported) |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any JSON-serialisable value, or a `Blob`/`File` |
+| **Output** | Base64 string — `[12-byte IV][AES-256-GCM ciphertext]` |
+
+Returns `null` and emits an error notification if `secret` is not set.
+
+---
+
+## Example pipeline: encrypt sensor data before storage
+
+```
+Timer → Map → Encrypt → LocalStorage
+```
+
+Map shapes the timer tick into `{ temperature: 21.5 }`, Encrypt produces a base64 string, LocalStorage persists it. The stored value is opaque until decrypted with the same secret.

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

@@ -0,0 +1,122 @@
+# Fetcher
+
+Makes an HTTP request on each pipeline trigger and injects the response body as the next pipeline value.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/fetcher` |
+
+---
+
+## What it does
+
+Fetcher fires an HTTP request every time data arrives from upstream. The
+response body becomes the new pipeline value passed downstream. It is
+the pull-based counterpart to [Input](./input.md) (push-based) and
+[Output](./output.md) (egress).
+
+Use Fetcher to poll an API on each Timer tick, to load remote data when
+triggered by a button press, or to chain HTTP requests with Map
+transformations.
+
+The browser also has `http-client` (see [HTTP](./http.md)), the same client the
+other runtimes provide. Fetcher keeps its own contract — expression bodies,
+`%variable%` substitution, the response body as the pipeline value — while
+`http-client` is the one to reach for when a board should read the same on
+whichever runtime makes the request, or move between them unchanged.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `url` | `string` | `""` | Request URL |
+| `method` | `string` | `"GET"` | HTTP method: `GET`, `POST`, `PUT`, `DELETE`, … |
+| `headers` | `Record<string, string>` | `{}` | Request headers (static or dynamic with `=` suffix) |
+| `body` | `string` | `""` | Request body (raw JSON string or plain text) |
+| `bodyFormat` | `"json" \| "text" \| "expression"` | `"text"` | How the request body is produced (see below) |
+| `bodyExpression` | `string` | `""` | Expression evaluated against `params` to produce the body; used when `bodyFormat` is `"expression"` |
+
+### Dynamic URLs and headers
+
+The `url` value and header values support template placeholders resolved
+from the incoming pipeline data. Keys ending with `=` are evaluated as
+expressions with `params` bound to the current input:
+
+```json
+{
+  "url": "https://api.example.com/users/{{params.userId}}",
+  "headers": {
+    "Authorization=": "\"Bearer \" + params.token"
+  }
+}
+```
+
+A reference inside a longer URL is a part of the address — an id, a search
+term — and is encoded as one, so a value holding `&` or `/` cannot change where
+the request goes. A reference that is the whole URL (`"{{params.link}}"`) is the
+whole address and is used as it is. A path the input does not have leaves
+nothing behind.
+
+### `body` and `bodyFormat`
+
+| Value | Behaviour |
+|---|---|
+| `"text"` (default) | `body` is sent as a plain string |
+| `"json"` | `body` is parsed as JSON. If the incoming data is an object, it is merged: `{ ...parsedBody, ...params }` |
+| `"expression"` | `bodyExpression` is evaluated as a Map-style expression with `params` bound to the incoming value. The result becomes the request body. |
+
+Example using `"json"` mode:
+```json
+{ "body": "{\"source\": \"hkp\"}", "bodyFormat": "json" }
+```
+
+Example using `"expression"` mode to build a dynamic body:
+```json
+{ "bodyFormat": "expression", "bodyExpression": "{ query: params.search, limit: 10 }" }
+```
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value; used to compose dynamic URL / headers / body |
+| **Output** | Response body — parsed as JSON if `Content-Type: application/json`, otherwise a string or Blob |
+
+---
+
+## Status notifications
+
+While a request is in flight the service emits UI notifications:
+
+- **`loading: true`** — request started
+- **`done: true`** — request completed successfully
+- **`error: message`** — request failed
+
+---
+
+## Example: polling a JSON API every second
+
+```json
+[
+  {
+    "serviceId": "hookup.to/service/timer",
+    "state": { "periodicValue": 1, "periodicUnit": "s", "periodic": true, "running": true }
+  },
+  {
+    "serviceId": "hookup.to/service/fetcher",
+    "state": { "url": "https://api.example.com/data", "method": "GET" }
+  },
+  {
+    "serviceId": "hookup.to/service/monitor",
+    "state": {}
+  }
+]
+```

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

@@ -0,0 +1,96 @@
+# FFT
+
+Converts a raw audio sample buffer into a frequency spectrum, or reconstructs samples from a spectrum (IFFT).
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/fft` |
+| hkp-rt | `fft` |
+| hkp-rt | `ifft` |
+
+The browser and hkp-rt FFT services have different configuration properties and input types. IFFT is hkp-rt only — see [IFFT](./ifft.md).
+
+---
+
+## Browser FFT
+
+**Service ID:** `hookup.to/service/fft`
+
+### What it does
+
+Receives a `FloatRingBuffer` from upstream audio services, applies windowing, performs a Cooley–Tukey FFT, and emits a frequency spectrum array. The spectrum format is controlled by `outputFormat`.
+
+### Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `windowFunction` | `string` | `"none"` | Window function applied before the FFT. One of `"none"`, `"hann"`, `"hamming"`, `"blackman"`, `"rectangular"` |
+| `outputFormat` | `string` | `"magnitude"` | Output spectrum format. One of `"magnitude"`, `"power"`, `"db"` |
+| `fftSize` | `number \| "auto"` | `null` (auto) | Number of samples per FFT window. Must be a power of 2. `"auto"` uses the ring buffer size. |
+
+### Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | `FloatRingBuffer` from an audio source (e.g. Audio Input) |
+| **Output** | Array of `fftSize / 2` values in the format specified by `outputFormat` |
+
+### Typical pipeline
+
+```
+Audio Input → FFT → Monitor
+Audio Input → FFT → Canvas (array draw element)
+```
+
+---
+
+## hkp-rt FFT
+
+**Service ID:** `fft`
+
+### What it does
+
+Receives an audio ring-buffer (a stream of float samples), reads the most recent `windowLength` samples, applies a Fast Fourier Transform, and emits an array of values — one per frequency bin from 0 Hz up to the Nyquist frequency.
+
+### Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `windowLength` | `number` | `512` | Number of samples per FFT window. Must be a power of 2. |
+| `outputMode` | `string` | `"magnitude"` | Output format: `"magnitude"` (real array), `"complex"` (array of `{re, im}` objects) |
+
+### Input
+
+A **ring-buffer** data value produced by `core-input`. The ring-buffer must contain at least `windowLength` samples; if fewer are available the service returns `null`.
+
+### Output
+
+- `"magnitude"` mode: JSON array of `windowLength / 2` magnitude floats. Index 0 is DC, last element is Nyquist.
+- `"complex"` mode: JSON array of `windowLength` objects `{ re, im }` — preserves phase for lossless IFFT reconstruction.
+
+---
+
+## Notes
+
+- FFT window sizes must be powers of 2: `64`, `128`, `256`, `512`, `1024`, `2048`, `4096`.
+- For audio effect chains requiring IFFT reconstruction, use `outputMode: "complex"` in hkp-rt so phase information is preserved.
+
+---
+
+## Typical hkp-rt pipelines
+
+### Real-time spectrum analyser
+
+```
+core-input → fft → monitor
+```
+
+### Audio effect chain
+
+```
+core-input → fft (outputMode: "complex") → map → ifft → core-output
+```