@ziprack/sdk 0.1.2 → 0.2.0

package/dist/docs/studio.md

@@ -0,0 +1,425 @@
+# zipRACK Studio
+
+- [What It Is](#what-it-is)
+- [Getting Started](#getting-started)
+- [The Document](#the-document)
+- [Prop Values](#prop-values)
+- [The Block Catalog](#the-block-catalog)
+- [Theme Tokens](#theme-tokens)
+- [The Derived Manifest](#the-derived-manifest)
+- [Validation](#validation)
+- [The Editor](#the-editor)
+- [Custom Code](#custom-code)
+- [Building and Packaging](#building-and-packaging)
+- [The MCP Server](#the-mcp-server)
+- [When Not To Use It](#when-not-to-use-it)
+
+<a name="what-it-is"></a>
+## What It Is
+
+Studio is an optional visual builder for `ziprack/1` applets. A typed JSON document is the applet;
+`index.html`, `manifest.json` and the bundle are compiled from it. The same renderer draws the editor
+canvas and the built package, so what an author arranges is what a participant gets.
+
+The load-bearing idea is that **the manifest is derived, not written**. Every block declares what it
+contributes — an activity, a collection, an upload, a prompt, a capability — and the compiler walks the
+document and merges those contributions. `undeclared_capability` at runtime, the most common way an
+applet breaks, stops being possible to cause by omission: placing a question block is what declares its
+activity, and there is no second step to forget.
+
+```
+applet.json ──► block registry ──► contributes() walk ──► manifest.json
+     │                                                         │
+     ├──► @ziprack/studio-runtime ──► editor canvas            │
+     │                            └─► dist/index.html ◄────────┘
+     └──► MCP server ──► an AI assistant
+```
+
+Three packages, all installed as one dev dependency:
+
+| Package | Contents |
+|---|---|
+| `@ziprack/studio-core` | Document model, prop types, block registry, validator, manifest compiler, theme tokens. No DOM. |
+| `@ziprack/studio-runtime` | The only renderer. Mounts a document into an element and calls `@ziprack/sdk`. |
+| `@ziprack/studio` | The `ziprack-studio` CLI: editor, compiler, packager, MCP server. |
+
+<a name="getting-started"></a>
+## Getting Started
+
+```sh
+npm install --save-dev @ziprack/studio
+npx ziprack-studio init --slug team-pulse
+npx ziprack-studio edit
+```
+
+`init` writes `applet.json` — one screen with a heading, a rating question and a finish button — and a
+`.gitignore` for the generated build inputs. `edit` opens the editor and the live canvas. `package`
+produces the zip you upload:
+
+```sh
+npx ziprack-studio package     # dist-zip/team-pulse-0.1.0.zip
+```
+
+| Command | What it does |
+|---|---|
+| `init [dir]` | Start an `applet.json`. `--slug`, `--name`, `--force`. |
+| `edit` | Editor and canvas on `http://localhost:5273`. `--port`, `--host`, `--open`. |
+| `validate` | Check the document and the manifest it derives. Exits non-zero on errors, and on warnings under `--strict`. |
+| `manifest` | Print the derived `manifest.json`. |
+| `build` | Validate, derive, bundle to `dist/`. `--out`, `--keep`. |
+| `package` | Build, then write `dist-zip/{slug}-{version}.zip` with an SBOM. |
+| `mcp` | Run the stdio MCP server. |
+
+Every command takes `--project <dir>`; without it, the nearest `applet.json` in a parent directory wins.
+
+<a name="the-document"></a>
+## The Document
+
+`applet.json` is a tree of nodes. Each node names a block, holds that block's props, and holds children
+in **named slots**:
+
+```json
+{
+    "schema": "ziprack-studio/1",
+    "applet": { "slug": "team-pulse", "name": "Team Pulse", "version": "0.1.0" },
+    "theme": { "preset": "clean", "tokens": { "color": { "accent": "#2563eb" } } },
+    "settings": { "segments": [], "metrics": [], "profile": [] },
+    "screens": [{
+        "id": "screen_a1b2c3",
+        "block": "layout.screen",
+        "version": "1",
+        "props": { "title": { "$$type": "string", "value": "Welcome" } },
+        "slots": {
+            "default": [{
+                "id": "rating_d4e5f6",
+                "block": "question.rating",
+                "version": "1",
+                "props": {
+                    "activityId": { "$$type": "activity-id", "value": "confidence.pre" },
+                    "label": { "$$type": "string", "value": "How confident do you feel?" },
+                    "scale": { "$$type": "scale", "value": { "min": 1, "max": 6 } }
+                },
+                "slots": {},
+                "style": { "variant": "card", "spacing": "lg" },
+                "editor": { "label": "Confidence (pre)" }
+            }]
+        }
+    }]
+}
+```
+
+Slots, rather than one child array, are what make structure checkable without a layout engine:
+`layout.split` has `left` and `right`, and each slot declares which blocks it accepts. Ids are
+prefixed by block kind and checked against every id already in the document, so they stay readable in
+diffs and in error messages.
+
+`editor.label` renames a node in the block tree without touching anything a participant sees — the way
+you tell two rating questions apart at a glance.
+
+<a name="prop-values"></a>
+## Prop Values
+
+Every prop value is an envelope, primitives included:
+
+```json
+{ "$$type": "string", "value": "How confident do you feel?" }
+```
+
+The uniformity buys two things: one generic parser for every prop, and an unambiguous discriminator
+where a slot accepts more than one kind of value. A colour prop takes either a literal or a theme
+token, and the envelope says which without guesswork:
+
+```json
+{ "$$type": "color", "value": "#2563eb" }
+{ "$$type": "token", "value": "color.accent" }
+```
+
+Four states are distinct, because "leave it alone" and "clear it" are different instructions:
+
+| State | Written as | Means |
+|---|---|---|
+| Absent | the key is missing | Use the block's default. |
+| Null | `"scale": null` | Explicit reset back to the default. |
+| Partial null | `{ "$$type": "scale", "value": { "min": 1, "max": null } }` | Reset one leaf, keep the rest. |
+| Disabled | `{ "$$type": "string", "value": "…", "disabled": true }` | Stored, but suppressed at render. |
+
+You do not type envelopes by hand. The editor forms write them, and the MCP tools take plain values and
+wrap them for you.
+
+<a name="the-block-catalog"></a>
+## The Block Catalog
+
+Each block declares the capabilities it needs, and those are what end up in `requires.capabilities`.
+
+| Block | Capability | Contributes |
+|---|---|---|
+| `layout.screen` | — | One screen. Slot: `default`. |
+| `layout.stack`, `layout.card` | — | Grouping. Slot: `default`. |
+| `layout.split` | — | Slots: `left`, `right`. |
+| `content.heading`, `content.prose`, `content.image` | — | — |
+| `content.media` | — | `media[]` |
+| `question.rating`, `question.scale`, `question.text`, `question.choice` | `activity@1` | One `activities[]` entry each |
+| `flow.next`, `flow.complete` | `attempt@1` | Attempt state and completion |
+| `flow.progress` | — | — |
+| `data.form`, `data.list` | `db@1` | `collections[]`, with the JSON Schema and `indexed` paths |
+| `upload.dropzone` | `storage@1` | `uploads[]` |
+| `ai.analysis`, `ai.chat` | `ai@1` | `prompts[]`, with `vars` and `output_schema` |
+| `room.presence`, `room.facilitator` | `broadcast@1` | `broadcast.channels`, `facilitator_events` |
+| `room.board` | `broadcast@1`, `db@1` | Both of the above |
+| `custom.code` | whatever you declare | Whatever you declare |
+
+`ziprack-studio mcp` exposes the same list, and the editor's insert menu is generated from it, so there
+is one catalog rather than three.
+
+<a name="theme-tokens"></a>
+## Theme Tokens
+
+Styling is a token set plus a handful of per-block variants. It is deliberately not free-form CSS: the
+constraint is what keeps an author's screen legible on a phone, which is where most participants are.
+
+`theme.tokens.color.accent` compiles to `--zr-color-accent` on `.zr-root`, and a prop holding
+`{ "$$type": "token", "value": "color.accent" }` renders `var(--zr-color-accent)`. Storage references
+the path, so changing the accent is one edit rather than a document-wide find-and-replace.
+
+| Group | Tokens |
+|---|---|
+| `color` | `bg`, `surface`, `text`, `muted`, `border`, `accent`, `accent-text`, `success`, `danger` |
+| `space` | `none`, `sm`, `md`, `lg`, `xl` |
+| `font` | `body`, `heading` |
+| `size` | `text-sm` … `text-2xl`, `measure` |
+| `radius` | `sm`, `md`, `lg`, `pill` |
+
+Presets `clean` and `warm` supply the defaults; `theme.tokens` overrides only what you name. Per-node
+`style` carries `variant`, `spacing`, `align` and `width` — a small vocabulary shared by every block,
+rather than keys each block invents.
+
+<a name="the-derived-manifest"></a>
+## The Derived Manifest
+
+`manifest.json` is output. You never edit it, and there is nothing to keep in sync:
+
+```sh
+npx ziprack-studio manifest
+```
+
+Each block's `contributes()` returns manifest fragments; the compiler merges them and refuses
+contradictions. Two blocks may share a collection only if their declarations match exactly; an activity
+id used twice is an error, because ids are the column keys in the export. The compiler also records
+which node produced each entry, which is how the editor jumps from a manifest problem to the block that
+caused it.
+
+`requires.capabilities` is the union of the blocks in the document. Delete the last question and
+`activity@1` disappears on the next build — worth knowing, since a capability change is what
+[publishing](publishing.md) parks in the review queue.
+
+<a name="validation"></a>
+## Validation
+
+```sh
+npx ziprack-studio validate
+```
+
+Validation is per-key. One bad prop is reported as one bad prop; the rest of the document still
+compiles, and the editor still renders. Every error names the node, the block, the prop path, and
+**the JSON Schema that would have been valid** — the same schema the editor's form is generated from
+and the same one the MCP tools return.
+
+Two layers run. Document rules cover prop types, slot membership and structure. Manifest rules are the
+`ziprack/1` rules from [The Manifest](manifest.md), applied to the derived output: segment references,
+metric pre/post pairing, scope implies capability, the eight-indexed-path ceiling, the reserved `$room`
+channel, prompt placeholders against declared vars. Those rules also live in PHP on the Rack, so the
+two implementations are held to a shared fixture corpus that both test suites run — if they ever
+disagree, a test fails rather than an upload.
+
+<a name="the-editor"></a>
+## The Editor
+
+```sh
+npx ziprack-studio edit
+```
+
+A panel and a canvas iframe. The panel holds the screen list, the block tree, a form generated from the
+selected block's prop schemas, and the theme editor. The canvas runs the real runtime with the real
+SDK in mock mode against the derived manifest, so answers are real statements, resume really resumes,
+and two browser tabs really share a `BroadcastChannel` room. Clicking a block in the canvas selects it
+in the tree; the two halves talk only over `postMessage`.
+
+Every change — typing in a field, reordering a block, an MCP call — goes through one command bus with
+pre-commit hooks that can refuse it. Slot rules, unique activity ids, scope-implies-capability and the
+reserved channel are enforced in one place, so no entry point can get around them. Undo is a log of
+named reversible operations rather than document snapshots, and a compound edit collapses to one step.
+
+Saves are written back to `applet.json` as you work. If you edit the file directly, the editor reloads
+it.
+
+<a name="custom-code"></a>
+## Custom Code
+
+When no block fits, `custom.code` points at a module in your own project:
+
+```ts
+// src/blocks/thermometer.ts
+import { h, type RenderContext } from '@ziprack/studio-core';
+
+export default function thermometer(ctx: RenderContext) {
+    return h('div', { class: 'thermometer' }, h('button', {
+        onclick: () => void ctx.rack.answer('mood.check', 5),
+    }, 'Warm'));
+}
+```
+
+The editor shows a named, movable box; the compiler bundles the module. This is the one place
+declaration is not automatic, because the compiler cannot see inside your code. Two props carry what it
+cannot infer: `capabilities` lists what the module calls, and `declares` carries the manifest entries it
+needs, in manifest shape.
+
+```json
+{
+    "code": { "module": "./src/blocks/thermometer.ts", "export": "default" },
+    "label": "Thermometer",
+    "capabilities": ["activity@1"],
+    "declares": { "activities": [{ "id": "mood.check", "type": "rating", "label": "Mood" }] }
+}
+```
+
+Both halves are enforced. An undeclared capability call is refused at runtime, and a capability declared
+with nothing to go with it fails the build — `activity@1` with no activity is as invalid here as it
+would be in a hand-written manifest. `declares` accepts `activities`, `media`, `collections`,
+`uploads`, `prompts`, `broadcast` and `profile`, and each is checked by the same manifest rules as a
+catalog block's contribution.
+
+Because the box stays a node in the tree, an applet with hand-written blocks is still openable in the
+editor. That is the difference between an escape hatch and a one-way export.
+
+<a name="building-and-packaging"></a>
+## Building and Packaging
+
+```sh
+npx ziprack-studio build       # dist/
+npx ziprack-studio package     # dist-zip/{slug}-{version}.zip
+```
+
+`build` validates, derives and checks the manifest, then emits `dist/` through Vite with `base: './'`,
+because the Rack serves packages from a token-prefixed path and absolute URLs break there:
+
+```
+dist/
+├── index.html            the generated shell
+├── manifest.json         derived
+├── applet.json           the document, so the package can be reopened in the editor
+└── assets/…              the runtime, your custom modules, and the compiled theme
+```
+
+That is an ordinary `ziprack/1` package, subject to the same
+[installer rules](applet-packages.md) as a hand-written one.
+
+`package` adds a CycloneDX `sbom.json`, falling back to `package-lock.json` if `npm sbom` fails. Bump
+`applet.version` before every upload; a version string installs once per applet.
+
+<a name="the-mcp-server"></a>
+## The MCP Server
+
+```sh
+npx ziprack-studio mcp
+```
+
+Line-delimited JSON-RPC 2.0 over stdio. Point your assistant's MCP configuration at it with the project
+directory as the working directory:
+
+```json
+{
+    "mcpServers": {
+        "ziprack-studio": {
+            "command": "npx",
+            "args": ["ziprack-studio", "mcp", "--project", "."]
+        }
+    }
+}
+```
+
+The point is not that an assistant can write the file — it could do that anyway. The point is that it
+writes through the same registry, the same command bus and the same validator as the editor, so what it
+produces is a document a non-technical colleague can then open and edit.
+
+| Tool | Purpose |
+|---|---|
+| `ziprack_list_blocks` | The catalog: id, label, category, `requires`, slots, what it contributes. Start here. |
+| `ziprack_get_block_schema` | One block's prop schemas and defaults, `allowedParents`, each slot's `allowedBlocks`, and guidance on when to use it. |
+| `ziprack_read_document` | The tree, whole or one subtree, summarised below a given `depth`. |
+| `ziprack_compose` | Build a tree from a structure-only skeleton plus content maps. |
+| `ziprack_patch` | `create`, `delete`, `move`, `duplicate`, `props`, `style`, `label`, `settings`, `applet`, `theme`. |
+| `ziprack_validate` | Per-key errors, each with the schema that would have been valid. |
+| `ziprack_derive_manifest` | The manifest this document produces, plus a capability diff against the last build. |
+
+The SDK's docs tools (`ziprack_guidelines`, `ziprack_list_docs`, `ziprack_search_docs`,
+`ziprack_read_doc`) are served alongside these. See [the SDK's MCP server](sdk.md#the-mcp-server).
+
+`compose` separates structure from content, which is what stops a long generation from corrupting a
+tree. The skeleton is nesting only; props arrive in a map keyed by `configuration-id`:
+
+```xml
+<layout.screen configuration-id="intro">
+    <content.heading configuration-id="title" />
+    <question.rating configuration-id="confidence" />
+    <flow.next configuration-id="go" />
+</layout.screen>
+```
+
+```json
+{
+    "intro": { "title": "Welcome" },
+    "title": { "text": "How is the team feeling?" },
+    "confidence": { "activityId": "confidence.pre", "label": "How confident do you feel?", "scale": { "min": 1, "max": 6 } },
+    "go": { "label": "Start" }
+}
+```
+
+Use `slot="left"` on a child to place it in a named slot, `parent` to append inside an existing node,
+and `replace: true` to rebuild the document from scratch.
+
+Three properties hold for every mutating call:
+
+- **`dry_run` everywhere.** Same answer, same validation, nothing written.
+- **All or nothing.** One refused operation rolls the whole batch back. Half a composition is worse
+  than none.
+- **Refusals carry schemas.** A wrong prop name comes back with the names the block does have; a wrong
+  value comes back with the schema that would have been accepted. Correction takes one round trip
+  rather than a read, a guess and another write.
+
+```json
+{
+    "applied": false,
+    "dry_run": false,
+    "errors": [{
+        "message": "Expected a string.",
+        "block": "content.heading",
+        "node": "heading_ozbhbm",
+        "prop": "level",
+        "schema": {
+            "type": "object",
+            "properties": {
+                "$$type": { "type": "string", "const": "level" },
+                "value": { "type": "string", "enum": ["1", "2", "3"] },
+                "disabled": { "type": "boolean" }
+            },
+            "required": ["$$type", "value"],
+            "additionalProperties": false,
+            "default": { "$$type": "level", "value": "1" }
+        }
+    }]
+}
+```
+
+Successful mutations answer with the validation state of the whole document, not just the part that
+changed, because an edit that leaves the applet unpublishable is worth knowing about immediately.
+
+The server and the editor can be open at once. Each picks up the other's writes to `applet.json`.
+
+<a name="when-not-to-use-it"></a>
+## When Not To Use It
+
+Studio is one way to build an applet, not the way. It constrains layout and styling on purpose, and
+that is the wrong trade when the interface *is* the work — a custom visualisation, an unusual
+interaction, a design that has to match a brand exactly. For those, write the applet directly against
+[the SDK](sdk.md) and start from `starter/`. A Rack cannot tell the difference: both produce a
+`ziprack/1` package, and both are subject to the same manifest and the same installer.

package/dist/docs/versioning.md

@@ -0,0 +1,101 @@
+# Versioning
+
+- [Three Axes](#three-axes)
+- [The Format String](#the-format-string)
+- [Capability Versions](#capability-versions)
+- [Package Versions](#package-versions)
+- [Version Pinning](#version-pinning)
+- [Applet Versions](#applet-versions)
+
+<a name="three-axes"></a>
+## Three Axes
+
+There are three independent version numbers in zipRACK, and coupling any two of them is a mistake.
+
+| Axis | Example | Governs | Audience |
+|---|---|---|---|
+| **Format string** | `ziprack/1` | Manifest shape, envelope, installer rules | Applet authors and the validator |
+| **Capability version** | `db@1` | The SDK surface an applet binds to | Applet authors |
+| **Package semver** | `ziprack/db` 2.4.1 | The PHP API: classes, contracts, config keys, migrations | Whoever maintains a Rack |
+
+`ziprack/db` can reach 4.0.0 — several breaking PHP refactors — while still implementing `db@1` and
+requiring `ziprack/1`. An applet built two years ago keeps working, because none of what it binds to
+has changed.
+
+> A capability version changes **only** when the applet-facing surface changes. Package major
+> versions are free to move independently and frequently.
+
+<a name="the-format-string"></a>
+## The Format String
+
+`schema: "ziprack/1"` versions the envelope (`ns`, `v`, ack shape), the core manifest fields, and the
+installer's file rules. A Rack refuses a manifest with any other schema, naming what it speaks.
+
+`cn-sim/1` was a single monolithic schema version, which made every new surface a breaking change.
+Splitting the format from the capabilities is what allows surfaces to ship incrementally and allows
+different deployments to run different capability sets — which matters given standalone Racks per
+engagement.
+
+<a name="capability-versions"></a>
+## Capability Versions
+
+A manifest declares `id@version` references. A Rack implements a set of them, built by iterating
+installed packages:
+
+```sh
+php artisan ziprack:status
+# format: ziprack/1
+# capabilities: activity@1, ai@1, attempt@1, auth@1, broadcast@1, db@1, storage@1
+```
+
+An applet requesting something outside that set is refused at **install**, not at runtime, with a
+message naming what is implemented.
+
+A package may implement more than one version of its capability at once — `db@1` and `db@2` during a
+transition — which is what makes migrating applets across a capability break survivable. The
+versions a package implements are metadata the core reads at boot, never inferred from the package's
+own semver.
+
+<a name="package-versions"></a>
+## Package Versions
+
+Ordinary semver on the PHP API, and the thing a Rack maintainer upgrades:
+
+```sh
+composer update ziprack/core
+```
+
+The packages are authored in one monorepo and published as read-only subtree splits on tag — one
+repository per package, which nobody commits to. A change spanning `ziprack/core`'s registry and the
+`ziprack/db` package that registers into it is one PR, one test run, one tag.
+
+What a maintainer needs to know about a fix landing everywhere is covered by
+[Conformance](conformance.md) and `/ziprack/health`.
+
+<a name="version-pinning"></a>
+## Version Pinning
+
+Pinning is the one behaviour that is not a capability, because it is a policy the Rack applies *to*
+an applet rather than a surface the applet calls. Rather than declare it, zipRACK derives it:
+
+> **Requesting `attempt@1` implies pinned. Its absence implies rolling.**
+
+Attempts are the only reason pinning exists — activity ids cannot shift mid-attempt without
+corrupting the export — and apps must roll, or people are stranded on stale builds. One rule, one
+capability, nothing for an author to get wrong and no new manifest field. See
+[Attempts](attempts.md#version-pinning) for the authoring consequences.
+
+<a name="applet-versions"></a>
+## Applet Versions
+
+Your own `version` field is semver, unique per applet, and uploadable exactly once. Bump it for
+every upload, including test builds — the installer refuses a duplicate rather than overwriting,
+which is deliberate: a version is immutable, so what a participant ran is always recoverable.
+
+Between versions:
+
+- Changing an activity `id` splits an export column.
+- Changing a `label` changes only the header.
+- Adding a capability or a profile attribute blocks promotion until approved.
+- Adding or removing `attempt@1` flips the applet between pinned and rolling, and is flagged
+  prominently in the diff.