@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/docs/content/services/gif-encoder.md

@@ -0,0 +1,56 @@
+# GIF Recorder
+
+Captures a sequence of image frames from the pipeline and encodes them into an animated GIF.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/gif-encoder` |
+
+---
+
+## What it does
+
+GIF Recorder buffers incoming image frames while in recording mode. Each frame (provided as a `Blob` containing image data) is drawn onto an off-screen canvas and quantised to a fixed 256-colour 3-3-2 RGB palette. When recording is stopped, the buffered frames are encoded into a valid GIF89a binary stream and emitted as a `Blob` downstream.
+
+The encoder is implemented entirely in the browser with no server round-trip.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `recording` | `boolean` | `false` | `true` to start recording; `false` to stop and emit the GIF |
+| `delayMs` | `number` | `100` | Inter-frame delay in milliseconds (controls playback speed) |
+| `maxFrames` | `number` | `100` | Maximum number of frames to buffer before stopping automatically |
+
+Toggling `recording` from `true` to `false` triggers encoding and emits the GIF.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | `Blob` — an image frame (JPEG, PNG, or any browser-decodable format) |
+| **Output** | `Blob` — an animated GIF, emitted once when recording stops |
+
+---
+
+## Colour depth
+
+The encoder uses a fixed 3-3-2 RGB palette (256 colours). This gives fast encoding without per-frame palette computation, at the cost of colour fidelity. It is well-suited for simple animations, game renders, and camera captures.
+
+---
+
+## Typical pipeline
+
+```
+Camera → GIF Recorder → Monitor
+```
+
+Start recording, wave at the camera, stop recording. Monitor receives the GIF blob which can then be uploaded, displayed, or forwarded.

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

@@ -0,0 +1,85 @@
+# GitHub
+
+Read content from (GitHub Source) or write content to (GitHub Sink) a GitHub repository.
+
+---
+
+## Available in
+
+| Runtime | Service IDs |
+|---|---|
+| Browser | `hookup.to/service/github-source`, `hookup.to/service/github-sink` |
+
+---
+
+## GitHub Source
+
+### What it does
+
+Fetches content from a GitHub repository on each pipeline trigger —
+files, directory listings, issues, pull requests, or raw API responses —
+and emits the result downstream.
+
+### Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `token` | `string` | `""` | GitHub Personal Access Token (PAT) or OAuth token |
+| `owner` | `string` | `""` | Repository owner (user or organisation) |
+| `repo` | `string` | `""` | Repository name |
+| `path` | `string` | `""` | File or directory path within the repo |
+| `ref` | `string` | `"main"` | Branch, tag, or commit SHA to read from |
+
+### Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value — used as a trigger |
+| **Output** | File content (decoded from Base64), directory listing, or GitHub API response object |
+
+---
+
+## GitHub Sink
+
+### What it does
+
+Writes content to a file in a GitHub repository. Each pipeline trigger
+commits the current pipeline value (or a configured payload) to the
+specified path, creating or updating the file.
+
+### Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `token` | `string` | `""` | GitHub Personal Access Token or OAuth token |
+| `owner` | `string` | `""` | Repository owner |
+| `repo` | `string` | `""` | Repository name |
+| `path` | `string` | `""` | Target file path within the repo |
+| `branch` | `string` | `"main"` | Branch to commit to |
+| `message` | `string` | `"Update via hkp"` | Commit message |
+
+### Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | String or JSON object — written as the file content |
+| **Output** | GitHub API commit response |
+
+---
+
+## Typical use
+
+### Read a config file on every board load
+
+```
+Injector (trigger) → GitHub Source → Map → configure downstream service
+```
+
+### Write board output to a repository
+
+```
+Timer → process → Map → GitHub Sink
+```
+
+Each timer tick writes the current result to a file in the repo,
+creating a timestamped log.

package/bundle/docs/content/services/group-by.md

@@ -0,0 +1,54 @@
+# Group By
+
+Groups or aggregates an array of objects by a named property, producing either a histogram or a sum.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/group-by` |
+
+---
+
+## What it does
+
+Group By receives an array of objects and reduces it along a single property. Two modes are available:
+
+| Mode | Output |
+|---|---|
+| `histogram` | An object mapping each distinct value of `property` to its count, e.g. `{ "cat": 5, "dog": 3 }` |
+| `sum` | The sum of the `property` values across all items in the array |
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `property` | `string` | `""` | Name of the key to group by or sum |
+| `mode` | `"histogram"` \| `"sum"` | `"histogram"` | Aggregation mode |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Array of objects |
+| **Output (histogram)** | `{ [value]: count }` |
+| **Output (sum)** | `number` |
+
+Non-array inputs are returned as-is (with a console warning in `sum` mode).
+
+---
+
+## Example: count label occurrences
+
+```json
+{ "property": "label", "mode": "histogram" }
+```
+
+Input: `[{ "label": "cat" }, { "label": "dog" }, { "label": "cat" }]`
+Output: `{ "cat": 2, "dog": 1 }`

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

@@ -0,0 +1,79 @@
+# Hacker
+
+Evaluates a single sandboxed expression against the current pipeline value.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/hacker/considered` |
+
+---
+
+## What it does
+
+Hacker holds one expression, written in the same dialect
+[Map](./map.md) uses for its dynamic terms, and evaluates it on every
+pipeline value. The result of the expression becomes the next pipeline
+value. It is the escape hatch for a computation that does not fit a
+declarative service, while staying inside a sandbox: the expression is
+parsed into an AST and evaluated against a fixed scope, so it cannot
+reach `window`, `document`, `fetch` or any other browser global.
+
+The service is named "Considered Hacker" in the service list.
+
+---
+
+## Writing an expression
+
+The incoming pipeline value is bound to `params`, and the built-in
+functions listed in [Map's expression scope](./map.md#expression-scope)
+are in scope:
+
+```
+round(sin(params.triggerCount * 0.05) * 220 + 300)
+```
+
+```
+concat('hsl(', (params.triggerCount * 37) % 360, ',70%,60%)')
+```
+
+An expression is a single expression — not a function body. There are no
+statements, no variable declarations, and no object or array literals. To
+build an object, follow Hacker with a [Map](./map.md) whose template
+holds the structure and whose dynamic terms hold the computation —
+`boards/hacker-demo-board.json` does exactly that.
+
+Returning `null` stops the pipeline. When the expression throws or fails
+to parse, the service reports the error on its health indicator and
+emits `null`.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `buffer` | `string` | `""` | The expression to evaluate |
+| `size` | `[number, number]` | — | Editor size in pixels |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value, bound to `params` inside the expression |
+| **Output** | The expression's value, or `null` on error or to stop the pipeline |
+
+---
+
+## Notes
+
+- Side effects are limited to what the scope offers — `toVault` writes a
+  value to the user vault, `print` logs to the console.
+- For straightforward reshaping prefer [Map](./map.md), and for
+  predicates prefer [Filter](./filter.md); Hacker is for the computation
+  in between.

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

@@ -0,0 +1,59 @@
+# Hash
+
+Computes a cryptographic hash of any pipeline value using the Web Crypto API.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/hash` |
+
+---
+
+## What it does
+
+Hash stringifies the incoming value (or uses it directly if it is a `Uint8Array`/`ArrayBuffer`) and computes its hash using the SubtleCrypto API. The result is returned as a hex or base64 string.
+
+A **progressive mode** (`sha-256p`) allows incremental hashing: successive inputs are buffered as chunks, and the final hash over all accumulated data is produced when `configure({ finalize: true })` is called.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `method` | `string` | `"sha-256"` | Hash algorithm. One of `"sha-256"`, `"sha-384"`, `"sha-512"`, `"sha-1"`, `"sha-256p"` |
+| `encoding` | `"hex"` \| `"base64"` | `"hex"` | Output encoding for the hash digest |
+| `finalize` | `boolean` | — | **Progressive mode only** — when `true`, computes and emits the hash over all buffered chunks via `app.next()` |
+
+### Progressive mode (`sha-256p`)
+
+1. Set `method: "sha-256p"`.
+2. Send successive values through `process()` — each is buffered.
+3. Call `configure({ finalize: true })` to compute the SHA-256 over all buffered data and emit the result.
+
+Changing `method` while in progressive mode clears the chunk buffer.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value — stringified with `JSON.stringify` before hashing; `Uint8Array`/`ArrayBuffer` are hashed directly |
+| **Output** | Hex or base64 string of the hash digest |
+
+In `sha-256p` mode, `process()` returns `null` and the final hash is emitted asynchronously after `finalize`.
+
+---
+
+## Example: SHA-256 of a string
+
+```json
+{ "method": "sha-256", "encoding": "hex" }
+```
+
+Input: `"hello world"`
+Output: `"b94d27b9934d3e08a52e52d7da7dabfac484efe04294e576f0f7f28e4b2b5a2f"` (truncated for illustration)

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

@@ -0,0 +1,182 @@
+# Hold
+
+Keeps the latest value one side of a pipeline produced, and replays it to the other side.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/hold` |
+| hkp-node | `hold` |
+| hkp-python | `hold` |
+| hkp-rt | `hold` |
+
+---
+
+## What it does
+
+A pipeline is one ordered list, but it can be entered from more than one side. A timer
+inside an [`http-server-subservices`](./http.md) drives it on its own schedule; an HTTP
+request arriving at the same service drives it whenever the caller shows up. The two are
+unrelated in time, so the value the producer made is gone by the time the consumer asks
+for it.
+
+Hold keeps it. **Which side is calling can be said two ways**, and a board picks one.
+
+### By declaring the role
+
+With a `slot`, the board says outright which end each Hold is: `op` is `"write"` or
+`"read"`, and two Holds naming one slot are the two ends of it.
+
+- A **write** stores its input and **emits it unchanged**, so the pass it belongs to
+  carries on as though the Hold were not there.
+- A **read** emits what is held, **raw** — not wrapped in anything — so it can be the
+  whole of what a pipeline answers with. While nothing is held it returns `null` and the
+  pipeline stops there.
+
+Nothing inspects the value, so anything can be held: bytes, a rendered document, an audio
+buffer. And the two ends may sit in **pipelines that never meet**, which is what an
+endpoint's [entry points](./http.md#the-two-ways-in) are:
+
+```json
+{
+  "onProcess": [ { "serviceId": "hold", "state": { "slot": "document", "op": "write" } } ],
+  "onRequest": [ { "serviceId": "hold", "state": { "slot": "document", "op": "read"  } } ]
+}
+```
+
+Where the cells live is the **host's** to decide. A service that owns several pipelines
+lends them one store of its own — so an endpoint's slot names are private to it, and two
+endpoints on a runtime may both call a slot `document`. Anything else falls through to the
+runtime's.
+
+### By what the value carries
+
+With a `property` and no slot, the input says which side called:
+
+- An input **carrying that property** is the producer. Its value replaces what is held.
+- **Every** call — that one included — emits the held value under the same property name.
+- While nothing is held, every call returns `null` and the pipeline stops there.
+
+So the services after Hold receive the same shape whichever side called, and cannot tell
+the two apart. That is the point: the ordered list itself cannot say where a call came
+from, and with Hold in front of them nothing downstream needs to.
+
+This is the only arrangement available where **both sides share one pipeline**, since
+position says nothing there and the value is all there is to go on. Its limit is the other
+side of the same coin: two sides whose values look alike cannot be told apart — a response
+envelope and a request are both `{meta, …}` — and a value with no properties at all, raw
+bytes, always reads.
+
+Everything but the held property is dropped. A producer emitting
+`{ triggerCount: 5, note: "x" }` with `property: "triggerCount"` leaves Hold as
+`{ triggerCount: 5 }`, and so does a request that carries no `triggerCount` at all.
+
+An input that cannot carry a property — a string, a number, an array — is a read. So is one
+carrying the property as `null`: a null held value is an empty one, the way null is nothing
+to pass on everywhere else, so a producer cannot hold null. Holding non-JSON values is not
+supported yet.
+
+While `property` is unset, Hold holds nothing and passes its input through unchanged.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `slot` | `string` | `""` | The cell to hold in. Set, `op` says which end this Hold is and the value is not inspected. |
+| `op` | `"read"` \| `"write"` | `"read"` | Which end. Only read with a `slot`. |
+| `property` | `string` | `""` | The property to hold, when there is no slot. An input carrying it writes; every call reads. |
+| `value` | any | — | **Browser only.** On a writing end (`slot` + `op: "write"`), written into the slot when configured, as though it had arrived as input. The board keeps it, so the slot holds it again after a reload. How a board sets a value nothing in its pipelines produces — a tempo, a limit — and how a facade control changes it. Ignored on a reading end. |
+| `action` | `"clear"` | — | Forgets the held value and resets the counts. |
+
+State reports the arrangement in use and not the other one, so a board keeps only the
+fields it acts on.
+
+Changing `property` does the same, since the held value belonged to the old name. The counts
+go with the value either way: they say how often each side has called for what is held now.
+
+Reported state also carries `held` — `null` while nothing is held — along with `readCount`
+and `writeCount`, so a producer that has stopped writing shows up as reads without writes.
+A held value that is bytes, or simply large, is **described** in `held` rather than sent
+(`"[4096 bytes]"`): state is read back into the board and sent to everyone watching, so
+what goes in it has to be worth carrying. The value itself is untouched.
+
+Destroying a Hold empties only what it held itself. A slot belongs to the host and the
+other end of it outlives this one — a pipeline rebuilt while a board is running destroys
+the services in it, and that must not empty a cell the other side is still answering from.
+
+Bypassing Hold in hkp-rt passes the input straight through without holding or replaying —
+the base class does not call the service at all.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any. With a `slot`, `op` decides; otherwise an object carrying the configured property writes and anything else reads. |
+| **Output** | With a `slot`: a write emits its input unchanged, a read emits the held value raw. Otherwise `{ <property>: <held value> }`. `null` while nothing is held. |
+
+---
+
+## Typical uses
+
+**An endpoint that publishes a document.** The board builds it, the endpoint serves it,
+and neither pipeline looks at what it is:
+
+```
+sql → map → HttpServerSubservices
+              ├─ onProcess: Hold (slot: document, op: write)
+              └─ onRequest: Hold (slot: document, op: read)
+```
+
+An endpoint that answers with whatever a producer last made. The timer drives
+`Timer → Hold → Map` on its own; a request enters the same pipeline at the head, the timer
+passes it through, and Hold turns it into the last tick so the Map formats the answer:
+
+```
+HttpServerSubservices
+  └─ onRequest: Timer → Hold (property: triggerCount) → Map
+```
+
+Here the two sides share one pipeline — the timer drives it, and a request enters it at the
+head — so the property is what tells them apart. The same board with the producer outside
+the endpoint, using [`pipeline`](./http.md#the-two-ways-in) so a pass of the chain runs the
+same list a request does:
+
+```
+Timer → Map → HttpServerSubservices
+                └─ pipeline: Hold (property: triggerCount)
+```
+
+Put Hold **before** the services that reshape the value, not after — those services are
+exactly what should not have to know which side called.
+
+
+---
+
+## Where its cells live
+
+A slot is a name, not a store. Which cells that name reaches is decided by whatever holds
+the pipelines — never by Hold itself, which is what lets the same board mean the same thing
+wherever it runs.
+
+| Holding it | Which cells |
+|---|---|
+| The runtime | Every service in it shares one set, so two Holds naming `document` meet. |
+| An endpoint ([`http-server-subservices`](./http.md)) | Its own, shared by its two entry pipelines — so two endpoints on a runtime may both call a slot `document` without meeting. |
+| A [scope](../concepts/scopes.md) (`sub-service`) | Its own by default, or with `scope: { slots: "inherit" }` those of whatever holds the scope — the enclosing scope, or the runtime. A chain of inheriting scopes reaches outward one level at a time. |
+| Nothing | A Hold that reaches no store still holds, for itself alone, rather than dropping what it was given. |
+
+The default is worth saying plainly: **a scope keeps its cells to itself**. A reusable
+sub-pipeline whose slot names leaked into its surroundings would collide with a second copy
+of itself, so two Holds that must meet across a scope boundary need that boundary to say
+`inherit` — which the **Hold across scopes** demo board
+(`boards/hold-scopes-demo-board.json`) does on both of its scopes.
+
+The demo board linked from this page is the other arrangement: one endpoint
+whose two entry pipelines share the cells it owns.

package/bundle/docs/content/services/http-relay-client.md

@@ -0,0 +1,48 @@
+# HTTP Relay Client
+
+Polls a server-side relay endpoint and serves responses to incoming HTTP requests by running them through a configurable inner pipeline.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/http-relay-client` |
+
+---
+
+## What it does
+
+HTTP Relay Client bridges a server-side HTTP relay (a PHP script that buffers requests) with browser-side pipeline processing. It polls the relay endpoint every 500 ms. When a pending request arrives (with its query parameters), those parameters are piped through an inner pipeline (a `BrowserRuntimeScope`). The pipeline's result is then POSTed back to the relay as the HTTP response body.
+
+This pattern lets a browser act as an HTTP server without requiring a persistent server connection — the relay stores incoming requests until the browser polls for them.
+
+The polling loop stops when the service is bypassed and resumes when bypass is removed.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `pollUrl` | `string` | `""` | URL to poll for pending requests |
+| `respondUrl` | `string` | `""` | URL to POST the pipeline result back to |
+| `authVaultKey` | `string` | `""` | Vault key for an optional bearer token injected into poll/respond requests |
+| `bypassAfterNumberOfPolls` | `number \| null` | `100` | Auto-bypass after this many polls; `null` to disable |
+| `pipeline` | `PipelineEntry[]` | `[]` | Inner pipeline applied to each incoming request's query params |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Pass-through (relay is driven by the polling loop, not by pipeline input) |
+| **Output** | Pass-through |
+
+---
+
+## Typical use
+
+Deploy a lightweight PHP relay on a server. Configure HTTP Relay Client with the relay's `pollUrl` and `respondUrl` and an inner pipeline that processes each query string object. The browser becomes a headless HTTP responder.

package/bundle/docs/content/services/http-uploader.md

@@ -0,0 +1,62 @@
+# HTTP Uploader
+
+POSTs file chunks from a [Chunked File Provider](./chunked-file-provider.md) to a server endpoint.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/http-uploader` |
+
+---
+
+## What it does
+
+HTTP Uploader consumes `ChunkPayload` objects emitted by [Chunked File Provider](./chunked-file-provider.md) and uploads each chunk to the configured `url` as a raw HTTP POST. Metadata about the chunk is sent as request headers so the server can reassemble the file.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `url` | `string` | `""` | Server endpoint that receives each chunk |
+
+---
+
+## Request format
+
+Each chunk is posted with the raw `ArrayBuffer` as the body and the following headers:
+
+| Header | Value |
+|---|---|
+| `Content-Disposition` | `attachment; filename="<filename>"` |
+| `Content-Type` | MIME type of the original file |
+| `X-Upload-Id` | UUID shared across all chunks of the same upload |
+| `X-Chunk-Index` | 0-based index of this chunk |
+| `X-Total-Chunks` | Total number of chunks for this file |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | `ChunkPayload` from Chunked File Provider |
+| **Output** | The original `ChunkPayload` (pass-through) |
+
+---
+
+## Status reporting
+
+The UI panel shows the current upload progress (e.g. "Uploading chunk 2 / 5"). On success the status is cleared; on error the HTTP status or error message is displayed.
+
+---
+
+## Typical pipeline
+
+```
+Chunked File Provider → HTTP Uploader
+```