@echelon-foundry/design-system 0.3.0 → 0.4.0

package/dist/patterns/split.html

@@ -0,0 +1,12 @@
+<div class="ef-site">
+  <div class="ef-split">
+    <div>
+      <h2>Install</h2>
+      <p>The primary region takes the available space. The supporting region wraps below it when the row runs out of room.</p>
+    </div>
+    <aside aria-label="Requirements">
+      <h3>Requirements</h3>
+      <p>Node 22 or later.</p>
+    </aside>
+  </div>
+</div>

package/dist/patterns/surface.html

@@ -0,0 +1,4 @@
+<section class="ef-surface" aria-labelledby="surface-title">
+  <h2 id="surface-title">Billing contact</h2>
+  <p>Invoices are sent to the finance team on the first business day of each month.</p>
+</section>

package/dist/patterns/text-field.html

@@ -0,0 +1,5 @@
+<div class="ef-field">
+  <label class="ef-field__label" for="text-field-email">Work email</label>
+  <span class="ef-field__description" id="text-field-email-description">We send sign-in links to this address.</span>
+  <input id="text-field-email" name="email" type="email" autocomplete="email" aria-describedby="text-field-email-description" required>
+</div>

package/dist/patterns/text-roles.html

@@ -0,0 +1,7 @@
+<div class="ef-site">
+  <p class="ef-eyebrow">Release 0.3</p>
+  <h2>Faster onboarding for new teams</h2>
+  <p class="ef-lead">A lead paragraph introduces the section in one or two sentences.</p>
+  <blockquote class="ef-statement"><p>Forma keeps behavior in the application and presentation in the design system.</p></blockquote>
+  <span class="ef-component-kicker">Component kicker</span>
+</div>

package/dist/patterns/textarea.html

@@ -0,0 +1,5 @@
+<div class="ef-field">
+  <label class="ef-field__label" for="textarea-summary">Change summary</label>
+  <span class="ef-field__description" id="textarea-summary-description">Describe what changed and why. Plain text, up to 500 characters.</span>
+  <textarea id="textarea-summary" name="summary" rows="4" maxlength="500" aria-describedby="textarea-summary-description"></textarea>
+</div>

package/dist/patterns/visually-hidden.html

@@ -0,0 +1,4 @@
+<button type="button">
+  <span aria-hidden="true">×</span>
+  <span class="ef-visually-hidden">Remove filter: Region is Europe</span>
+</button>

package/docs/MARKETING-SITES.md

@@ -314,7 +314,7 @@ Keep the `@v<version>` of the Forma actions equal to the version in
 3. Add it in Forma:
    - pattern HTML;
    - CSS in `src/marketing/` using role tokens only;
-   - metadata in `tools/component-meta.mjs`;
+   - a catalog entry in `catalog/components/<slug>.mjs` (see `docs/CATALOG-AUTHORING.md`);
    - tests (structure, browser, axe, 320 px);
    - a gap entry closed in `requirements/MARKETING-PRESENTATION.md`.
 4. Release it. The sites then upgrade (question 7) and remove any local

package/docs/workflow/EMBEDDING.md

@@ -0,0 +1,148 @@
+# Embedding the workflow renderer and editor
+
+`@echelon-foundry/forma-workflow` is the reusable workflow component. It
+provides the public `<forma-workflow>` element and runs the F# engine
+(`Forma.Workflow`) on .NET WebAssembly. It is a separate, opt-in package. The
+design-system package stays zero-runtime (ADR-0006). You do not need Forma
+Studio.
+
+A complete host application that is not Studio lives in
+[`examples/workflow-embedding/`](../../examples/workflow-embedding/). It shows
+runtime, edit, pick and isolated modes and a partner brand. Its browser tests
+are in [`tests/browser/workflow-embed.spec.mjs`](../../tests/browser/workflow-embed.spec.mjs).
+
+## Same-page embedding (no iframe)
+
+```html
+<link rel="stylesheet" href="/assets/forma/tokens.css">
+<link rel="stylesheet" href="/assets/forma/foundations.css">
+<link rel="stylesheet" href="/assets/forma/components.css">
+<link rel="stylesheet" href="/assets/forma-workflow/forma-workflow.css">
+<script type="module" src="/assets/forma-workflow/forma-workflow.js"></script>
+
+<forma-workflow id="designer" mode="edit"></forma-workflow>
+<script type="module">
+  const designer = document.getElementById("designer");
+  const workflow = await (await fetch("/forma/workflows/launch.forma-workflow.json")).json();
+  await designer.load(workflow);
+  designer.addEventListener("forma-workflow-change", (e) => save(e.detail.workflow));
+</script>
+```
+
+You can also put the document inline as an inert data block. The element then
+loads it on start, and the static figure inside the element is the
+no-script fallback:
+
+```html
+<forma-workflow mode="view">
+  <script type="application/json" class="forma-workflow-source">{ "format": "forma-workflow", … }</script>
+  <figure class="ef-diagram">…static rendering…</figure>
+</forma-workflow>
+```
+
+The element inherits Forma tokens, brands (`data-ef-brand` on any ancestor),
+themes, forced colours, reduced motion and responsive behaviour from the host
+page.
+
+## Host modes
+
+| `mode` | What people can do |
+|---|---|
+| `view` | Read. Zoom. Activate declared intents. |
+| `inspect` | Select objects and read their metadata, references, status and extensions. |
+| `edit` | Create, connect, reconnect, move, resize, rename and recolour. Set status, ports, groups and lanes, metadata, references, interactions and accessibility. Arrange. Undo and redo. |
+| `pick` | Choose one or more objects; the host receives them on "Use selection". |
+| `runtime` | Read. The host projects live state with `setRuntimeState`. The document is never changed. |
+
+## Host contract `forma-workflow-host/1`
+
+The contract is small and versioned. Hosts never see the engine's internal state.
+
+**Attributes:** `mode`, `instance` (optional stable id), `engine` (optional URL of the engine directory).
+
+**Methods** (each returns a promise):
+
+| Method | Effect |
+|---|---|
+| `load(workflow)` | Load a document (object or JSON text). Emits `forma-workflow-load`. |
+| `getWorkflow()` | The current document, canonical JSON. |
+| `execute(command)` | Run a validated command, for example `{ name: "addNode", kind: "task", label: "Review" }`, `{ name: "connect", source: { node: "a" }, target: { node: "b" } }`, `{ name: "setLabel", object: "node:a", value: "…" }`, `{ name: "setMetadata", object: "node:a", key: "owner", value: "Ops" }`, `{ name: "setStatus", object: "node:a", status: { state: "active" } }`, `{ name: "setColor", object: "node:a", property: "fill", value: "#e8f0ff" }`, `{ name: "move", nodes: ["a"], dx: 8, dy: 0 }`, `{ name: "delete", objects: ["edge:e1"] }`, `{ name: "autoLayout" }`. |
+| `undo()`, `redo()` | History. |
+| `select(objects)` | `["node:a", { type: "edge", id: "e1" }]`. |
+| `focusObject(object)` | Move keyboard focus to an object. |
+| `setRuntimeState(states)` | `{ "nodeId": { state: "active", label: "In progress" }, "other": null }`. |
+| `validate(workflow)` | The validation report, without loading. |
+
+**Events** (bubbling `CustomEvent`s; `detail` is JSON):
+
+| Event | `detail` |
+|---|---|
+| `forma-workflow-ready` | Engine started. |
+| `forma-workflow-load` | `valid`, `class`, `findings`, `workflow`. |
+| `forma-workflow-change` | `description`, `workflow` (the new document), `valid`, `class`, `findings`. Only legal, validated changes arrive. |
+| `forma-workflow-selection` | `objects: [{ type, id }]`. |
+| `forma-workflow-focus` | `object`. |
+| `forma-workflow-intent` | `object`, `action`, `target`, `command`, `label`, `parameters`. The host decides what to do. |
+| `forma-workflow-pick` | `objects`. |
+| `forma-workflow-refused` | `message`. A command was refused and nothing changed. |
+| `forma-workflow-error` | `message` (the engine failed to start). |
+
+A command that would introduce a new validation error is refused. Examples are a
+dangling connection, a port over its limit, or a blank name. Unknown metadata
+and extensions survive every edit.
+
+## Interaction model
+
+- **Keyboard.** Every object is a button in the Objects list. Arrow keys move the selected steps (Shift moves further). Delete removes them. Escape cancels. All inspector fields are native form controls.
+- **Pointer.** Click selects. Ctrl, Cmd or Shift-click adds to the selection. Drag a selected step to move it; it is one change when released. Drag the corner handle to resize. Drag the round handle onto another step to connect.
+- **Touch and mobile.** Tap selects. No operation needs dragging: "Connect" then tap a target, the Connect form, the Move buttons and the Position and size fields all work without it. Handles have a 44px hit area. Below 64rem the layout stacks, with the canvas first, and the canvas scrolls inside its own region.
+- **Zoom and pan.** Use the zoom buttons. Pan by scrolling the canvas. Zoom is view state and is never saved.
+- **Announcements.** A polite live region reports each change, refusal and selection.
+
+## .NET hosts
+
+A host that already runs .NET, such as Forma Studio, links `Forma.Workflow`.
+It supplies the element's transport itself instead of loading a second runtime:
+
+```js
+element.transport = {
+  async dispatch(json) { return myExports.WorkflowDispatch(json); }, // backed by EmbedHost.dispatch
+  async document(id) { return myExports.WorkflowDocument(id); },
+  async dispose(id) { myExports.WorkflowDispose(id); },
+  async validate(text) { return JSON.parse(myExports.WorkflowValidate(text)); }
+};
+```
+
+## Isolated mode (iframe)
+
+Use isolated mode only when you need stronger separation. It carries the same
+portable document over the same `forma-workflow-host/1` contract, through
+`postMessage`:
+
+```html
+<iframe src="/assets/forma-workflow/frame.html?parent=https://app.example.org&forma=https://app.example.org/assets/forma/&brand=echelon"></iframe>
+```
+
+| From the parent | Fields |
+|---|---|
+| `{ protocol, id, type: "load", document }` | |
+| `{ protocol, id, type: "mode", mode }` | |
+| `{ protocol, id, type: "command", command }` | |
+| `{ protocol, id, type: "select", objects }`, `"focus"`, `"runtime"`, `"undo"`, `"redo"`, `"get"` | |
+
+| From the frame | Fields |
+|---|---|
+| `{ protocol, type: "frame-ready" }` | |
+| `{ protocol, type: "reply", id, ok, workflow?, error? }` | |
+| `{ protocol, type: "event", event: { type, … } }` | the same events as above |
+
+The frame accepts messages only from the origin in `?parent=`, and only from
+`window.parent`. It posts only to that origin.
+
+## Security
+
+Workflow files are data. The engine builds every view from a typed HTML tree
+that escapes all text and attributes. It never emits event-handler attributes
+or `javascript:` URLs. Intents are reported, never executed. The host element
+has no `eval`, no `new Function` and no decision logic; a package test checks
+this.

package/docs/workflow/EXTERNAL-PRODUCERS.md

@@ -0,0 +1,34 @@
+# Producing workflows outside Forma
+
+Any system can create a valid workflow from the published schema alone.
+[`examples/external-producer/produce.mjs`](../../examples/external-producer/produce.mjs)
+does it with plain Node.js and no Forma code at all.
+[`consume.mjs`](../../examples/external-producer/consume.mjs) reads the file
+back after other tools have edited it.
+
+## Rules for producers
+
+1. Write `format`, `formatVersion: "1.0.0"`, `id`, `title`, `forma.version` and `nodes`.
+2. Give every node, edge and group a stable id. Never reuse array positions as ids.
+3. Leave out coordinates unless you mean them. Forma lays out a workflow with no layout deterministically.
+4. Put meaning in core fields: `kind`, `status`, `color`, `references`, group `members`. Put your own data in `metadata` or in `extensions["your.namespace"]`.
+5. Validate before publishing: `forma-workflow validate --json your.forma-workflow.json`.
+6. Save to `forma/workflows/<id>.forma-workflow.json`.
+
+## Rules for consumers
+
+- Read the core fields you understand. Keep everything else, including unknown extensions and metadata, and write it back unchanged.
+- Check `formatVersion` and the validation class before relying on a document.
+
+## The round-trip proof
+
+1. An external producer writes a `.forma-workflow.json` file.
+2. Forma validates it.
+3. Forma Studio opens it and edits it.
+4. Forma Studio saves it.
+5. An external consumer reads it.
+
+`npm run proof:external` in kemiller2002/forma-studio runs all five steps. It
+checks that stable ids, nodes, edges, semantics, colours, metadata, unknown
+namespaced extensions and domain references survive. The evidence is recorded
+in that repository under `docs/evidence/`.

package/docs/workflow/FORMAT.md

@@ -0,0 +1,196 @@
+# Forma portable workflow format 1.0
+
+Status: **normative**. Requirement: [`requirements/PORTABLE-WORKFLOW-INTERCHANGE.md`](../../requirements/PORTABLE-WORKFLOW-INTERCHANGE.md).
+Decision: [ADR-0006](../decisions/ADR-0006-portable-workflow-capability.md).
+
+A Forma workflow is a JSON document. Any system can write one: an application,
+an agent, a backend service, a CLI or Forma Studio. Forma validates it, lays it
+out, renders it to HTML and edits it. You do not need Forma Studio for any of
+these.
+
+| Item | Value |
+|---|---|
+| File suffix | `.forma-workflow.json` |
+| Repository convention | `forma/workflows/<workflow-id>.forma-workflow.json` |
+| Format identifier | `"format": "forma-workflow"` |
+| Format version | `"formatVersion": "1.0.0"` (semantic versioning) |
+| JSON Schema (repository) | [`schemas/workflow/1.0/forma-workflow.schema.json`](../../schemas/workflow/1.0/forma-workflow.schema.json) |
+| JSON Schema (package) | `@echelon-foundry/design-system/workflow/forma-workflow.schema.json` |
+| JSON Schema (`$id`) | `https://forma.echelonfoundry.com/schemas/workflow/1.0/forma-workflow.schema.json` |
+| Capability contract | `@echelon-foundry/design-system/contracts/workflow-capabilities.json` |
+| Reference fixtures | [`examples/workflows/forma/workflows/`](../../examples/workflows/forma/workflows/) with [`fixtures.json`](../../examples/workflows/fixtures.json) |
+
+## The smallest workflow
+
+```json
+{
+  "format": "forma-workflow",
+  "formatVersion": "1.0.0",
+  "id": "minimal",
+  "title": "Minimal workflow",
+  "forma": { "version": "0.4.0" },
+  "nodes": [ { "id": "start", "kind": "start", "label": "Start" } ]
+}
+```
+
+## A realistic workflow
+
+```json
+{
+  "$schema": "https://forma.echelonfoundry.com/schemas/workflow/1.0/forma-workflow.schema.json",
+  "format": "forma-workflow",
+  "formatVersion": "1.0.0",
+  "id": "launch-readiness",
+  "title": "Launch readiness poll",
+  "forma": { "version": "0.4.0" },
+  "metadata": { "program": "Example mission", "revision": 3 },
+  "nodes": [
+    { "id": "poll", "kind": "start", "label": "Begin readiness poll" },
+    { "id": "go", "kind": "decision", "label": "All stations go?",
+      "metadata": { "owner": "Launch director" } },
+    { "id": "hold", "kind": "task", "label": "Call a hold",
+      "status": { "state": "pending" },
+      "color": { "fill": "#fff1d6", "foreground": "#1d1d1b" } },
+    { "id": "launch", "kind": "end", "label": "Proceed to launch",
+      "references": [ { "id": "count", "system": "gov.nasa.example.range", "type": "Countdown", "key": "CD-77" } ],
+      "extensions": { "com.example.console": { "panel": 4 } } }
+  ],
+  "edges": [
+    { "id": "e1", "source": { "node": "poll" }, "target": { "node": "go" } },
+    { "id": "e2", "source": { "node": "go" }, "target": { "node": "launch" }, "kind": "conditional", "label": "Go" },
+    { "id": "e3", "source": { "node": "go" }, "target": { "node": "hold" }, "kind": "conditional", "label": "No go", "line": "dashed",
+      "metadata": { "logged": true } }
+  ]
+}
+```
+
+No coordinates appear anywhere. Forma places the nodes with its deterministic
+default layout.
+
+## Top-level properties
+
+| Property | Required | Meaning |
+|---|---|---|
+| `format`, `formatVersion` | yes | Identify the format and its version. |
+| `id` | yes | Stable workflow id: lowercase letters, digits and hyphens. It is also the file stem. |
+| `title` | yes | Human name. It becomes the accessible name of the rendered diagram. |
+| `description`, `language`, `direction` | no | Description, BCP 47 language and base text direction (`ltr`, `rtl`, `auto`). |
+| `forma` | yes | `{ "version": "0.4.0", "requires": ["workflow.ports"] }`: the target Forma release and, optionally, the capabilities it requires. |
+| `metadata` | no | Arbitrary JSON object. It is preserved and never interpreted. |
+| `palette` | no | Named colour slots, `{ "finance": "token:accent-primary" }`. |
+| `nodes` | yes | Steps or items. |
+| `edges` | no | Connections. |
+| `groups` | no | Groups, containers, swimlanes and phases. |
+| `layout` | no | Workflow layout settings: `direction` (`right` or `down`), `mode` (`authored` or `auto`) and `canvas`. |
+| `presentation` | no | `density` and a `legend` that explains colour and line meaning in text. |
+| `extensions` | no | Producer data by namespace. |
+| `provenance` | no | `producer`, `createdAt`, `modifiedAt`, `source` and `modifiedBy`. |
+
+## Identity
+
+Every addressable object has a stable `id`. Nodes, edges and groups share one id
+namespace per workflow. Ports are unique within their node. References are
+unique within their owner. Legend entries are unique within the legend.
+
+Connections and memberships always point at ids. They never use array
+positions, DOM identity or editor-only ids. Ids survive editing, re-layout and
+saving.
+
+## Nodes
+
+| Property | Meaning |
+|---|---|
+| `kind` | `start`, `end`, `task`, `decision`, `merge`, `event`, `subprocess`, `data`, `note` or `external`. A producer kind is `<namespace>:<name>`, such as `com.example.erp:approval`, and must carry `kindLabel`. |
+| `kindLabel` | Display text for the kind. Optional for core kinds. |
+| `label`, `description` | Visible text. |
+| `variant` | Forma shape: `rectangle`, `rounded`, `pill`, `ellipse` or `diamond`. Presentation only; a shape never implies a kind. |
+| `color` | `fill`, `stroke`, `accent` and `foreground`. Each is a `#rrggbb` literal, a Forma token (`token:accent-primary`) or a palette slot (`palette:finance`). |
+| `status` | `{ "state": "active", "label": "In progress", "detail": "...", "updatedAt": "..." }`. Core states are `none`, `pending`, `ready`, `active`, `waiting`, `complete`, `blocked`, `failed`, `skipped`, `cancelled` and `unknown`. A namespaced state needs a `label`. |
+| `ports` | Connection points: `id`, `side` (`top`, `right`, `bottom`, `left`), `direction` (`in`, `out`, `inout`), `label`, `maxConnections`. |
+| `references` | Domain references: `id`, `system` (a namespace), `type`, `key`, `label` and `href`. Forma displays them and never dereferences them. |
+| `metadata` | Arbitrary JSON object. It is preserved unchanged. |
+| `accessibility` | `name` and `description` for assistive technology, when they should differ from the visible text. |
+| `interaction` | A declarative intent (see below). |
+| `layout` | Optional geometry and layout intent: `x`/`y` (together or not at all), `width`, `height`, `rank`, `order` and `size` (`compact`, `standard`, `wide`). |
+| `extensions` | Producer data by namespace. |
+
+## Edges
+
+`id`, `source` and `target` are required. `source` and `target` are
+`{ "node": "...", "port": "..." }`. Edges also accept these properties:
+
+- `direction`: `forward` (the default), `backward`, `both` or `none`.
+- `kind`: `sequence` (the default), `conditional`, `default`, `exception`, `message`, `association`, `data` or a namespaced kind with `kindLabel`.
+- `label`, `description`, `line` (`solid`, `dashed`, `dotted`), `width` (1 to 8) and `color.stroke`.
+- `status`, `references`, `metadata`, `accessibility`, `interaction`.
+- `layout`: `routing` (`straight` or `orthogonal`), `waypoints` and the label position.
+- `extensions`.
+
+## Groups, containers, swimlanes and phases
+
+`kind` is one of `group`, `container`, `swimlane` or `phase`. A group lists its
+`members` (node ids) explicitly. Nesting uses `parent`. Canvas overlap never
+implies membership. A node belongs to at most one swimlane. A phase may cut
+across swimlanes.
+
+## Interactions are intents, not code
+
+```json
+{ "action": "command", "command": "com.example.lab:open-review", "label": "Open review",
+  "parameters": { "queue": "peer" } }
+```
+
+`action` is one of the following:
+
+- `none`, `select`, `inspect`.
+- `navigate` or `open`, each with a `target` naming exactly one destination: `workflow`, `node`, `edge`, `group`, `reference` or `url`.
+- `command`, which needs a namespaced `command` and a `label`.
+
+A renderer or editor reports intents to the host application. The host decides
+what they do. Nothing in a workflow file ever executes.
+
+## Semantics versus layout
+
+Everything about meaning is outside `layout`. Remove every `layout` object and
+the workflow means the same thing. Layout operations only write `layout` fields.
+
+- **Default layout** (`Layout.resolve`) is deterministic. Ranks come from the
+  graph (longest path, with cycles broken in document order). Swimlanes, groups
+  and containers become nested bands, so members stay inside their boundary.
+  Authored positions are kept.
+- **Explicit layout** (`Layout.apply FillMissing` or `Layout.apply Recompute`,
+  or `forma-workflow layout [--recompute]`) writes positions into `layout`
+  fields. Tests prove it never changes ids, semantics, metadata, references or
+  extensions.
+
+## Extensions and metadata
+
+- `metadata` is the application's own descriptive data. It can be any JSON
+  object. Numbers keep their spelling (`1.50` stays `1.50`), and key order is
+  kept.
+- `extensions` are keyed by a reverse-DNS namespace (`com.example.erp`). Each
+  value is a JSON object. The `forma` and `forma.*` namespaces are reserved.
+  Unknown extensions survive load, edit and save unchanged.
+- Interoperable meaning (kinds, status, colour, references, membership) is
+  always in core fields. Never put it only in an extension.
+
+## Canonical serialization
+
+`Codec.serialize` and `forma-workflow normalize` write a fixed property order,
+two-space indentation and a final newline. Empty optional arrays are omitted.
+Canonical output is a fixed point: serializing a loaded canonical file gives the
+same bytes.
+
+## Versioning
+
+`formatVersion` follows semantic versioning. This library reads `1.0.0`.
+
+- A pre-release of the current version (`1.0.0-rc.1`) migrates automatically. It is reported as *migration required, automatic*.
+- Any other version is reported as *migration required* with the reason. The document is not decoded.
+
+The Forma release a workflow needs is declared separately in `forma.version`
+and `forma.requires`. It is checked against
+[`contracts/workflow-capabilities.json`](../../contracts/workflow-capabilities.json).
+
+See also [VALIDATION.md](VALIDATION.md), [RENDERING.md](RENDERING.md),
+[EMBEDDING.md](EMBEDDING.md) and [EXTERNAL-PRODUCERS.md](EXTERNAL-PRODUCERS.md).

package/docs/workflow/RENDERING.md

@@ -0,0 +1,90 @@
+# Rendering workflows to HTML
+
+Forma renders a workflow to standards-based HTML with its public diagram
+contract (`.ef-diagram*`, contract 2.1.0). Static output is HTML and CSS only.
+Forma Studio is never involved.
+
+## Fragment
+
+```bash
+forma-workflow render forma/workflows/launch.forma-workflow.json --out launch.html --deps launch.deps.json
+```
+
+The fragment starts with a comment that declares what it needs:
+
+```html
+<!-- Requires @echelon-foundry/design-system@0.4.0/tokens.css, @echelon-foundry/design-system@0.4.0/foundations.css, @echelon-foundry/design-system@0.4.0/components.css -->
+<figure class="ef-diagram" id="wf-static-export" aria-labelledby="wf-static-export-title">
+  <figcaption id="wf-static-export-title">Static export reference</figcaption>
+  <div class="ef-diagram__viewport" tabindex="0" role="group" aria-label="Static export reference diagram, scroll to see all items">
+    <div class="ef-diagram__canvas" style="--ef-diagram-canvas-w: 792px; --ef-diagram-canvas-h: 136px;">
+      <svg class="ef-diagram__wires" viewBox="0 0 792 136" aria-hidden="true" focusable="false">…</svg>
+      <article class="ef-diagram-node" id="wf-static-export-n-a" data-ef-shape="pill" aria-labelledby="wf-static-export-n-a-label" style="…">
+        <p class="ef-diagram-node__kind">Start</p>
+        <h3 class="ef-diagram-node__label" id="wf-static-export-n-a-label">Request</h3>
+      </article>
+      …
+    </div>
+  </div>
+  <ol class="ef-diagram__relations" aria-label="Relationships">
+    <li>Request leads to Review.</li>
+    <li>Review leads to Done: “Approved”.</li>
+  </ol>
+</figure>
+```
+
+The complete reference outputs are in
+[`examples/workflows/exports/`](../../examples/workflows/exports/). Tests
+check them byte for byte.
+
+## Complete document
+
+```bash
+forma-workflow render launch.forma-workflow.json --document --forma-base /assets/forma/ --brand example-harbor --out launch.html
+```
+
+The document contains a doctype, `lang` and `dir`, charset, viewport, title,
+description and generator metadata. It links exactly the declared stylesheets,
+applies an optional public brand (`data-ef-brand`) and theme, and puts the
+figure in `<main>`.
+
+## Interactive output
+
+```bash
+forma-workflow render launch.forma-workflow.json --document --interactive view \
+  --runtime-base /assets/forma-workflow/ --out launch.html
+```
+
+This wraps the same static figure in the public `<forma-workflow>` element. It
+adds the workflow source as an inert `<script type="application/json">` data
+block and one module script from `@echelon-foundry/forma-workflow`. The
+dependency list names that runtime. Without script, the static figure still
+renders. Nothing private to Studio is ever emitted.
+
+## What the output guarantees
+
+Each guarantee is tested in `tests/workflow` and `tests/browser/workflow-static.spec.mjs`.
+
+- **Deterministic.** The same workflow and options give byte-identical HTML.
+- **Public contracts only.** Every class is a public Forma class that exists in Forma CSS. There are no Studio or editor classes and no editor-only ids.
+- **No script unless asked.** Static output has no `<script>`, no event-handler attributes and no `javascript:` URLs.
+- **Safe.** Every label, description, metadata value, reference and extension value is escaped. Unsafe URLs are dropped even if a host skips validation. The JSON data block cannot close its `<script>` element.
+- **Accessible.** The figure is named by the title. Each node is named by its label (or its accessible name). Kind and status are text. Every connector has a sentence in `ol.ef-diagram__relations`, so relationships never depend on lines alone. Groups and lanes list their members in `dl.ef-diagram__membership`. A legend explains colour. Reading order follows the flow, not the paint order.
+- **Responsive.** There is no page-level overflow at 320px. The canvas scrolls inside its focusable, named viewport. The relationship and membership lists reflow.
+- **Forced colours, print and grayscale.** These follow the diagram contract fallbacks.
+
+## Metadata in output
+
+Metadata stays in the workflow file. It is not rendered unless the host names
+fields to show (`--metadata owner,requirements` or
+`RenderOptions.VisibleMetadata`). This follows FMD-META-006/007 and the
+disclosure rules.
+
+## .NET
+
+```fsharp
+let w = (Validation.load text).Workflow.Value
+let fragment = WorkflowDocument.fragment DocumentOptions.defaults w
+let page = WorkflowDocument.document { DocumentOptions.defaults with FormaBase = "/assets/forma/"; Brand = Some "echelon" } w
+// fragment.Html, page.Html, page.Dependencies
+```

package/docs/workflow/REQUIREMENTS-AUDIT-2026-10-01.md

@@ -0,0 +1,55 @@
+# Requirements-to-evidence audit: portable workflows, embedding and HTML export
+
+Date: 2026-10-01. Scope: kemiller2002/forma PR #95 (FORMA-GH-93, FORMA-GH-94)
+and kemiller2002/forma-studio PR #17 (STUDIO-GH-14, STUDIO-GH-15).
+
+**Paths.** "Forma" paths are in kemiller2002/forma; "Studio" paths are in
+kemiller2002/forma-studio.
+
+**Test counts** are local results from Chromium 1194. Forma has 58 F# workflow
+tests and 25 workflow browser tests. Studio has 68 engine tests and 46 browser
+tests. CI also runs Firefox and WebKit for Forma.
+
+| # | Requirement | Implementation | Evidence |
+|---|---|---|---|
+| 3 | Forma owns the format: `.forma-workflow.json`, `forma/workflows/<id>`, versioned schema at a stable package path; all listed top-level, node and edge fields | Forma: `schemas/workflow/1.0/forma-workflow.schema.json`; package export `./workflow/forma-workflow.schema.json`; `src/workflow/Forma.Workflow/Model.fs` | Forma: `CoreTests` (fixture classes, round trip, paths); `tests/workflow-package.test.mjs` |
+| 3 | Unknown metadata and namespaced extensions round-trip | `Codec` keeps metadata as ordered JSON with number spelling preserved | Forma: `CoreTests` "Unknown metadata …", "Namespaced extensions …"; `EditorTests`. Studio: `WorkflowStudioTests` |
+| 4 | Semantics separate from layout; valid without coordinates; deterministic default layout; layout never changes semantics | Forma: `Layout.resolve`, `Layout.apply`, `Layout.strip` | Forma: `CoreTests` layout invariance, determinism, no overlap, lanes contain members |
+| 5 | Validation independent of Studio; six classes; schema, ids, references, ports, groups, extensions, compatibility, static accessibility | Forma: `Validation.fs`, `JsonSchema.fs` (runs the published schema), `forma-workflow validate` | Forma: `CoreTests`, `AdversarialTests`, `tests/workflow-external.test.mjs`; `docs/workflow/VALIDATION.md` |
+| 6 | Reusable renderer and editor in Forma: view, inspect, edit, pick and runtime; small versioned host boundary | Forma: `Editor.fs`, `Embed.fs`, `EmbedView.fs`, `EmbedProtocol.fs` (`forma-workflow-host/1`); `packages/workflow` | Forma: `EditorTests`; `tests/browser/workflow-embed.spec.mjs` |
+| 7 | Embedding without an iframe; optional iframe with a versioned message contract; styling, brand, accessibility, keyboard, responsive, touch and reduced motion preserved; example outside Studio | Forma: `<forma-workflow>`, `frame.html`/`frame.js`, `examples/workflow-embedding` | Forma: `workflow-embed.spec.mjs` (no iframe, isolated mode, keyboard, pointer, touch at 390px, axe, forced colours and reduced motion, runtime, pick, intents) |
+| 8 | Studio workflow editor uses the public component (dogfooding); selection, multi-selection, drag, move, resize, nodes, connections, ports, groups, lanes, metadata, colour, states, references, interactions, zoom, pan, keyboard, touch, validation, responsive | Studio: `src/kernel/workflows.js`, `StudioWorkflowInterop`, `WorkflowLibrary`; the component's capabilities | Studio: `tests/browser/workflow.spec.mjs`. Forma: `workflow-embed.spec.mjs` |
+| 9 | Metadata is first-class, editable, and preserved when unknown | Inspector metadata editor (typed); extensions displayed and preserved | Forma: `EditorTests` metadata test, embed browser metadata test. Studio: lifecycle test |
+| 10 | HTML fragment and complete document for a page, composition, component hierarchy or workflow; no Studio runtime, plugin or format | Studio: `HtmlExport.page`, `componentTree`, `workflow`; export panel; CLI `html`/`workflow-html` | Studio: `WorkflowStudioTests` export tests; `html-consumer.spec.mjs` |
+| 11 | Static stays static; runtime only from the public contract, declared | Static by default; opt-in interactive output declares `@echelon-foundry/forma-workflow` | Studio: interactive export tests. Forma: `RenderTests` "Static output has no script", interactive golden |
+| 12 | Maintainable, deterministic, public-contract HTML | Forma `Markup` tree; component-to-pattern map | Forma: `RenderTests` (public classes, determinism, goldens). Studio: `npm run html:check` |
+| 13 | Workflow fragment and document, static and interactive, with an accessible relationship representation | Forma: `Render.figure`, `WorkflowDocument`; `ol.ef-diagram__relations`, `dl.ef-diagram__membership` | Forma: `RenderTests`, `workflow-static.spec.mjs` (axe, 320px, forced colours, brand) |
+| 14 | Security: data only; escaping; no execution; adversarial tests | Typed intents; escaping Markup; URL policy; JSON depth and size limits; duplicate-key rejection | Forma: `AdversarialTests`, `RenderTests` escaping and data-block tests, `EditorTests` escaping. Studio: export escaping test |
+| 15 | 17 reference fixtures as executable compatibility fixtures | Forma: `examples/workflows/forma/workflows` (19) and `fixtures.json` | Forma: `CoreTests` (every fixture validated with its expected class; required list) |
+| 16 | External producer → validation → Studio open, edit, save → external consumer | Forma: `examples/external-producer`. Studio: the round-trip test | Studio: `docs/evidence/external-workflow-roundtrip.md` (39 preserved, 0 lost) |
+| 17 | Studio design → HTML → ordinary web project → render, for application, responsive, workflow and branded compositions, with accessibility verified | Studio: `examples/html-consumer` | Studio: `html-consumer.spec.mjs`; `docs/evidence/html-consumer.md` |
+| 18 | Forma gaps fixed in Forma, not Studio | Diagram contract 2.1.0 (ports, status, description, membership); `.ef-actions`; description contrast on surfaces | Forma: `tests/diagram-contract.test.mjs`, catalog check, commits on PR #95 |
+| 19 | F#, explicit state, minimal JavaScript, Limen where appropriate | All decisions in F#. The element and adapters are plumbing. Limen is page-scoped, so it is not used for the embeddable island (ADR-0006) | `tests/workflow-package.test.mjs` (no decision code in the element); Studio: `limen verify --strict` |
+| 20 | Unit, schema, integration, accessibility, responsive, serialization, round-trip, rendering, embedding and export tests | As listed above | As listed above |
+| 21 | Documentation | Forma: `docs/workflow/*` (format, validation, rendering, embedding, producers), README, agent usage, diagram catalog example. Studio: `docs/WORKFLOWS.md`, `docs/HTML-EXPORT.md`, README | |
+| 22 | Package surface: small, and usable without Studio | Forma core exports the schema, contract and examples; `@echelon-foundry/forma-workflow` exports the element, CSS, frame, schema and engine | Forma: `tests/workflow-package.test.mjs`, `tests/zero-runtime.test.mjs` |
+| 23 | CI and publishing | Forma: `workflow-validation.yml`; browser jobs build the package; the publish job publishes the workflow package. Studio: vendor check, export determinism, browser suite | CI on PR #95 and PR #17 |
+| 24 | Durable checkpoints | ROS work items FORMA-GH-93/94 and STUDIO-GH-14/15; HANDOFF and CURRENT-STATE entries | `./ros validate` (PR mode) passes in both repositories |
+
+## Open items (not hidden)
+
+1. **Flow convergence (forma-studio#16).** Studio's existing Flow surface, with
+   its profiles, named styles, mappings and merge, is not yet migrated onto the
+   portable format. Portable workflow authoring in Studio already uses the
+   public component. The broader Flow requirements in Studio's
+   `requirements/16` remain the Flow surface's backlog.
+2. **Release pinning.** Studio vendors Forma from PR #95 with a hash manifest.
+   The pinned npm artifacts become available when PR #95 merges and the
+   publish workflow releases Forma 0.4.0 and `@echelon-foundry/forma-workflow`
+   1.0.0.
+3. **Cross-engine browser runs.** Firefox and WebKit run in Forma CI. They were
+   not available in the implementing environment. Studio CI is Chromium only,
+   which matches its existing configuration.
+4. **Site pages.** The Forma site shows generated workflow markup in the
+   diagram catalog. The format, embedding and validation guides are repository
+   documentation (`docs/workflow/`), not separate generated site pages.