pi-show-me 0.1.0-alpha.1

package/CONTEXT.md

@@ -0,0 +1,54 @@
+# show-me-mcp
+
+Domain vocabulary for helping agents choose and organize explanations while ensuring the quality of display artifacts.
+
+## Language
+
+**Expression intent**: What the reader needs to understand, including the relationships, order, ownership, and emphasis that must be preserved.
+
+**Display form**: The structure used to express intent: pseudocode, text trees, Mermaid, diff, or HTML.
+_Avoid_: Image type, terminal mode
+
+**Expression element**: A semantic building block that helps an agent organize content, such as an entity, step, group, relation, branch, note, comparison, or emphasis.
+_Avoid_: Coordinates, drawing controls
+
+**Expression recipe**: A reference example that combines expression elements for a particular explanation task without requiring a single display form.
+
+**Expression library**: A collection of domain-specific expression elements, recipes, and their documentation, supplied by the project or a user.
+
+**Component library**: A collection of visual components and style resources for a display form. It can represent expression elements but is distinct from their semantic definitions.
+
+**Display adaptation**: Rules mapping expression elements to a display form and its components, including supported capabilities and limitations.
+
+**Extension contract**: The shared rules expression and component libraries follow when participating in discovery, validation, display, and quality checks.
+
+**Display artifact**: The text, diagram, or page actually presented to the reader. A single display form can be delivered in different file formats.
+_Avoid_: Display form
+
+**Display environment**: The client that presents an artifact, together with constraints such as dimensions, fonts, and rendering capabilities.
+
+**Display defect**: A layout problem that impedes understanding, including occlusion, overlap, clipping, overflow, or ambiguous connector endpoints.
+
+**Automatic repair**: Adjusting layout to eliminate display defects while preserving expression intent.
+
+**Quality check**: Assessing the readability and semantic fidelity of an actual display artifact in a specified environment.
+
+**Quality boundary**: The range of input sizes and display environments in which display quality can currently be verified and guaranteed.
+
+**Template**: Reusable organization rules for a recurring explanation task; these may reference expression recipes and elements.
+
+## Existing diagram primitives
+
+**VisualSpec**: A versioned specification describing a structured diagram.
+
+**Stack**: An arrangement expressing explicit horizontal or vertical reading order without implying relationships.
+
+**Group**: A grouping that expresses ownership or containment.
+
+**Card**: An addressable entity or step in a diagram.
+
+**Note**: A non-addressable annotation expressing an explanation, risk, or constraint.
+
+**Relation**: An explicitly declared relationship between entities.
+
+**Legend**: An explanation of the symbols, states, or visual markings used in a diagram.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,74 @@
+# pi-show-me
+
+Source repository: [alchemistklk/show-me-mcp](https://github.com/alchemistklk/show-me-mcp).
+
+Help agents explain complex ideas clearly and automatically fix layout problems in the resulting artifacts.
+
+The agent chooses the display form and organizes the content. The MCP handles layout, detects and repairs occlusion, overlap, text overflow, and connector conflicts, and verifies the final artifact. The intended workflow does not require agents or users to repeatedly adjust diagrams by hand.
+
+## Project documentation
+
+- [Project specification](docs/project-spec.md): goals, responsibilities, five display forms, quality assurance, and delivery scope.
+- [Expression elements](docs/expression-elements.md): element meanings, use cases, and composition examples.
+- [Extensibility](docs/extensibility.md): separation between user expression libraries, component libraries, and the core engine.
+- [Module design](docs/module-design.md): the adopted design, seams, and incremental validation strategy.
+- [First quality slice](docs/quality-slice.md): implemented HTML layout repair, expression libraries, and MCP tools.
+- [Four built-in forms](docs/native-forms.md): input, repair, and delivery contracts for Mermaid, pseudocode, text trees, and diff.
+- [Acceptance criteria](docs/acceptance.md): quality checks, failure examples, existing evidence, and upcoming milestones.
+- [Domain glossary](CONTEXT.md): shared project terminology.
+- [Existing prototype](docs/prototype-status.md): operation and limitations.
+- [Primitive contract v0.1](docs/primitive-contract-v0.1.md): compatibility reference for the existing interface.
+
+## Goals and current status
+
+| Goal | Current implementation |
+| --- | --- |
+| Five forms: pseudocode, text trees, Mermaid, diff, and HTML | All five are available through the new interface. HTML supports declarative libraries; the other four are built-in capabilities, each with a defined support scope. |
+| Automatic layout repair inside the MCP | HTML label avoidance, Mermaid reflow and reinspection, text wrapping by display width, and diff display formatting are implemented. Arbitrarily complex diagrams are not guaranteed to be repairable. |
+| Final display quality verification | HTML and Mermaid artifacts are verified in Chromium; text forms validate width and content preservation. Evidence records the verification scope and content hashes. |
+| Public repository and Pi plugin distribution | The repository is public on GitHub. The native Pi extension is distributed as `pi-show-me` on npm. |
+
+PNG is an optional artifact format, not a core display category. The existing `terminal | image | both` options and PNG fallback belong to the legacy prototype, not the target design.
+
+## Install in Pi
+
+The native Pi entry registers `describe_display` and `render_display` directly, without an MCP adapter. The alpha package is published on npm. Install it with `pi install npm:pi-show-me@alpha`. To try this checkout:
+
+```bash
+pi install /absolute/path/to/show-me-mcp
+```
+
+Disable duplicate tools from an existing MCP adapter before enabling the native extension. Reload Pi after installation.
+
+Artifacts are saved under `.pi/artifacts/show-me` in the current project. Override this with `SHOW_ME_ARTIFACT_DIR`. Text layout uses the current terminal width, or `SHOW_ME_TERMINAL_COLUMNS` when set; supported widths are 24–240 columns. Non-interactive sessions default to 120 columns. HTML and Mermaid return file paths; text forms also return a fenced preview. Diff keeps the applicable patch separate from its wrapped preview.
+
+The npm package also exposes `show-me-mcp` as a stdio MCP command. Pi exposes only the two current tools; the MCP command retains legacy `render_visual` support.
+
+## Run locally
+
+Node.js and npm are required. Text trees, pseudocode, and diff do not need a browser. HTML, Mermaid, and the full test suite require a local Chrome or Chromium executable, which can be specified with `SHOW_ME_CHROMIUM_BIN`. The legacy image path also requires `rsvg-convert`. The project does not automatically download a browser or use your personal browser profile.
+
+```bash
+npm ci
+npm test
+npm run render:fixture
+npm run render:composition
+npm run render:quality-demo
+npm run render:native-demo
+node bin/mcp-server.mjs
+```
+
+If your machine uses the `with-env` environment wrapper, prefix the commands with it. Examples write their artifacts to `artifacts/`. Local Pi configuration, tool caches, dependencies, and generated artifacts are excluded from Git.
+
+The MCP tools `describe_display` and `render_display` map to `describe` and `render`, supporting `html | mermaid | pseudocode | tree | diff`. Query a form's schema and examples before using an unfamiliar input format. Only HTML accepts expression-library references. The legacy `render_visual` tool remains available for compatibility; see the [prototype guide](docs/prototype-status.md) for its inputs.
+
+Licensed under [Apache-2.0](LICENSE). The first npm release is `0.1.0-alpha.1` (tag: `alpha`).
+
+## Migrating from show-me-mcp
+
+The npm package has been renamed to `pi-show-me`. The repository and MCP command retain the name `show-me-mcp`. Replace the old Pi package and reload Pi:
+
+```bash
+pi remove npm:show-me-mcp
+pi install npm:pi-show-me@alpha
+```

package/bin/mcp-server.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+import { createInterface } from "node:readline";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { writeFile, mkdir } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { compositionInputSchema, renderMermaid, renderToFiles, visualSpecInputSchema, createShowMe, displayRequestSchema, catalogQuerySchema } from "../src/index.mjs";
+import { createChromiumHost } from "../src/hosts/chromium.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const defaultArtifacts = path.resolve(process.env.SHOW_ME_ARTIFACT_DIR ?? path.resolve(here, "../artifacts"));
+const textOptions = { terminalColumns: Number(process.env.SHOW_ME_TERMINAL_COLUMNS ?? 120) };
+const catalog = createShowMe(textOptions);
+let displayHost;
+let displayEngine;
+
+async function closeDisplayHost() { await displayHost?.close(); }
+process.once("SIGTERM", () => { closeDisplayHost().finally(() => process.exit(0)); });
+process.once("SIGINT", () => { closeDisplayHost().finally(() => process.exit(0)); });
+
+function send(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function result(id, value) {
+  send({ jsonrpc: "2.0", id, result: value });
+}
+
+function error(id, code, message) {
+  send({ jsonrpc: "2.0", id, error: { code, message } });
+}
+
+function fencedText(text) {
+  const longest = Math.max(0, ...[...text.matchAll(/`+/g)].map(m => m[0].length));
+  const fence = "`".repeat(Math.max(3, longest + 1));
+  return `${fence}text\n${text}\n${fence}`;
+}
+
+async function handle(request) {
+  const { id, method, params = {} } = request;
+  if (method === "initialize") {
+    result(id, {
+      protocolVersion: "2025-11-25",
+      capabilities: { tools: { listChanged: false } },
+      serverInfo: { name: "show-me-mcp", version: "0.0.0-prototype" },
+    });
+    return;
+  }
+  if (method === "notifications/initialized") return;
+  if (method === "ping") {
+    result(id, {});
+    return;
+  }
+  if (method === "tools/list") {
+    result(id, {
+      tools: [
+        {
+          name: "render_visual",
+          title: "Render structured visual",
+          description: "Legacy template/primitive renderer for terminal Mermaid and image artifacts. Prefer render_display for the verified five-form interface; this tool retains the original compatibility behavior.",
+          inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["spec"],
+            properties: {
+              spec: { anyOf: [visualSpecInputSchema, compositionInputSchema] },
+              outputName: { type: "string", description: "Safe artifact basename without an extension." },
+              presentation: {
+                type: "string",
+                enum: ["terminal", "image", "both"],
+                default: "image",
+                description: "terminal returns fenced Mermaid; image returns PNG; both returns both presentations.",
+              },
+            },
+          },
+        },
+        { name: "describe_display", description: "Discover native Mermaid flowcharts, pseudocode, text trees and diff schemas, plus extensible HTML elements. Only HTML uses expression libraries.", inputSchema: catalogQuerySchema },
+        { name: "render_display", description: "Render and verify HTML, Mermaid flowcharts, pseudocode, text trees or diff. Automatically repair layout within declared limits; preserve semantics and selected form. Text forms need no browser; HTML and Mermaid require local Chromium. Diff delivers an applicable patch separately from its wrapped display. Only HTML accepts external elements.", inputSchema: displayRequestSchema },
+      ],
+    });
+    return;
+  }
+  if (method === "tools/call") {
+    if (["describe_display", "render_display"].includes(params.name)) {
+      try {
+        let value;
+        const content = [];
+        if (params.name === "describe_display") value = await catalog.describe(params.arguments ?? {});
+        else {
+          // Input/capability errors do not require launching a browser.
+          value = await catalog.render(params.arguments);
+          if (value.reason === "environment-unavailable") {
+            try {
+              if (!displayEngine) {
+                displayHost = await createChromiumHost();
+                displayEngine = createShowMe({ host: displayHost, ...textOptions });
+              }
+              value = await displayEngine.render(params.arguments);
+            } catch (caught) {
+              value = { ...value, details: caught instanceof Error ? caught.message : String(caught) };
+            }
+          }
+          if (value.status === "ready") {
+            const base = path.join(defaultArtifacts, `display-${randomUUID()}`);
+            const extension = { html: "html", mermaid: "svg", tree: "txt", pseudocode: "txt", diff: "diff" }[value.artifact.form];
+            const artifactPath = `${base}.${extension}`;
+            await mkdir(defaultArtifacts, { recursive: true });
+            await writeFile(artifactPath, value.artifact.content, "utf8");
+            const artifact = { form: value.artifact.form, mimeType: value.artifact.mimeType, path: artifactPath };
+            if (value.artifact.source) {
+              await writeFile(`${base}.mmd`, value.artifact.source.content, "utf8");
+              artifact.source = { mimeType: value.artifact.source.mimeType, path: `${base}.mmd` };
+            }
+            if (value.artifact.presentation) {
+              await writeFile(`${base}.display.txt`, value.artifact.presentation.content, "utf8");
+              artifact.presentation = { path: `${base}.display.txt`, notice: value.artifact.presentation.notice };
+            }
+            if (["tree", "pseudocode", "diff"].includes(artifact.form)) {
+              const text = value.artifact.presentation?.content ?? value.artifact.content;
+              if (text.length <= 24000) content.push({ type: "text", text: (value.artifact.presentation?.notice ? `${value.artifact.presentation.notice}\n\n` : "") + fencedText(text) });
+            }
+            value = { ...value, artifact };
+          }
+        }
+        content.push({ type: "text", text: JSON.stringify(value) });
+        result(id, { content, structuredContent: value, isError: value.status === "not-ready" });
+      } catch (caught) {
+        result(id, { content: [{ type: "text", text: caught instanceof Error ? caught.message : String(caught) }], isError: true });
+      }
+      return;
+    }
+    if (params.name !== "render_visual") {
+      error(id, -32602, `unknown tool: ${params.name}`);
+      return;
+    }
+    try {
+      const args = params.arguments ?? {};
+      const outputName = String(args.outputName ?? `visual-${Date.now()}`)
+        .replace(/[^a-zA-Z0-9_-]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "visual";
+      const requestedPresentation = args.presentation ?? "image";
+      if (!["terminal", "image", "both"].includes(requestedPresentation)) throw new TypeError("presentation must be terminal, image, or both");
+      const rendered = await renderToFiles(args.spec, path.join(defaultArtifacts, outputName));
+      const terminal = requestedPresentation === "terminal" || requestedPresentation === "both" ? renderMermaid(args.spec) : null;
+      const fallback = terminal?.diagnostics.terminal.fallbackRecommended ?? false;
+      const presentation = fallback ? "image" : requestedPresentation;
+      const structuredContent = {
+        presentation,
+        requestedPresentation,
+        pngPath: rendered.pngPath,
+        svgPath: rendered.svgPath,
+        ...(terminal ? { mermaidDiagnostics: terminal.diagnostics } : {}),
+        ...(terminal && !fallback ? { mermaid: terminal.mermaid } : {}),
+        diagnostics: rendered.diagnostics,
+      };
+      const content = [];
+      if (terminal && !fallback) content.push({ type: "text", text: `\`\`\`mermaid\n${terminal.mermaid}\n\`\`\`` });
+      if (presentation === "image" || presentation === "both") {
+        content.push({ type: "image", data: rendered.png.toString("base64"), mimeType: "image/png" });
+      }
+      content.push({ type: "text", text: JSON.stringify(structuredContent) });
+      result(id, {
+        content,
+        structuredContent,
+        isError: false,
+      });
+    } catch (caught) {
+      result(id, {
+        content: [{ type: "text", text: caught instanceof Error ? caught.message : String(caught) }],
+        isError: true,
+      });
+    }
+    return;
+  }
+  if (id !== undefined) error(id, -32601, `method not found: ${method}`);
+}
+
+const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+try {
+  for await (const line of lines) {
+    if (!line.trim()) continue;
+    try {
+      await handle(JSON.parse(line));
+    } catch (caught) {
+      console.error(caught);
+      error(null, -32700, "parse error");
+    }
+  }
+} finally { await closeDisplayHost(); }

package/bin/render-visual.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { renderToFiles } from "../src/index.mjs";
+
+const [inputPath, outputBase] = process.argv.slice(2);
+if (!inputPath || !outputBase) {
+  console.error("usage: node bin/render-visual.mjs <visual-spec.json> <output-base>");
+  process.exit(2);
+}
+
+const spec = JSON.parse(await readFile(path.resolve(inputPath), "utf8"));
+const result = await renderToFiles(spec, outputBase);
+console.log(JSON.stringify({ svgPath: result.svgPath, pngPath: result.pngPath, diagnostics: result.diagnostics }, null, 2));

package/docs/acceptance.md

@@ -0,0 +1,64 @@
+# Quality and acceptance criteria
+
+Status: target acceptance specification, 2026-09-08. All five forms have limited-scope implementations and tests; this does not establish quality guarantees for arbitrary inputs or every client.
+
+## Common gates
+
+- Semantic fidelity: preserve identities, endpoints, relation types and directions, groups, and reading order; do not silently omit or truncate content.
+- Complete text: no container clipping or unreadable overlap; measure long text and mixed English/Chinese content for the display environment.
+- Clear graphics: labels must not obscure arrows, connectors must not cross unrelated nodes, and endpoints must be identifiable. Necessary crossings should be distinguishable; do not promise zero crossings for arbitrary graphs.
+- Correct form: layout must not change tree hierarchy, pseudocode branch ownership, or diff addition/deletion semantics.
+- Explicit environment: record the renderer, dimensions, fonts, and other conditions affecting the result.
+- Terminating repair: the loop has a budget; distinguish passing, failing, and unsupported cases.
+- Reproducibility: identical inputs and environments produce stable results; record initial defects, repairs, and final checks.
+
+## Failure examples and existing evidence
+
+| Example | Expected result | Current evidence / gap |
+| --- | --- | --- |
+| Card ID is `note-1` or `derived-legend` | Arrows point only to the Card | Endpoint-collision regression in `test/render.test.mjs` |
+| Relation labels contain `&`, `"`, `|`, or Chinese text | No lost relations or invented nodes | Text-preservation checks for four relation kinds in `test/mermaid.test.mjs` |
+| Card/Relation IDs contain surrounding whitespace | Endpoints remain consistent after normalization | Covered by Mermaid regressions |
+| Horizontal flow between Cards of different heights | No meaningless short dogleg | `fixtures/horizontal-dogleg-regression.json` and horizontal-connector tests |
+| A Stack directly contains another Stack | Reading direction and structure are preserved | The legacy path diagnoses and falls back to PNG; automatic Mermaid repair for this input remains incomplete |
+| Complex diagrams reach 176/360 columns | Automatic repair and acceptance in the declared environment | Reproducible with the two complex fixtures; the legacy path only detects width and falls back |
+| A label covers an arrow | Automatic avoidance makes both readable | HTML sequence tests in `test/show-me.test.mjs` verify single-call repair and final HTML reinspection; general routing remains incomplete |
+| Connectors cross unrelated nodes / nodes overlap | Automatic avoidance, spacing adjustments, and reinspection | Native Mermaid has geometry checks and bounded reflow; path checks are sampled, not a guarantee for arbitrary graphs |
+| Long labels, mixed-language widths, deep trees | Full text and hierarchy survive | Text-tree tests cover Unicode grapheme wrapping, hierarchy prefixes, reconstruction, and explicit limit failures |
+| Pseudocode branches and long diff lines | No branch-ownership or addition/deletion changes | Pseudocode tests cover nested branches and loops; diff tests cover patch application and a separate wrapped view |
+| Complex HTML in narrow and wide windows | No clipping or occlusion; relationships remain clear | Simple HTML sequences are verified; complex responsive layout is not implemented |
+
+Run `npm test`. The current baseline has 31 local tests covering legacy MCP, HTML, the four built-in forms, and delivered files. The full suite requires local Chromium and runs test files serially to prevent browser/rasterizer contention from causing protocol timeouts. Test count is not a completion metric.
+
+## Record for each acceptance run
+
+1. Input fixture, selected form, and required semantic invariants.
+2. Display environment and tool versions.
+3. Initial defects and reproducible checks.
+4. Repairs actually performed and budget consumed.
+5. Final artifact, automated checks, and any necessary visual review.
+6. Whether the agent had to intervene in layout, plus remaining limitations.
+
+Mark unverified surfaces as UNKNOWN. A PNG file does not establish visual acceptance; a passing Pi parser does not establish an interactive Pi window check; local tests do not establish CI, release, or all-client acceptance.
+
+## Extension acceptance
+
+The following are extension goals. Current tests cover adding/removing the declarative example library, shared validation, discovery, duplicate identities, missing elements, and input schemas. Arbitrary UI components, resource changes, dynamic loading, and cross-client reproduction remain uncovered:
+
+- Register, discover, use, and remove an example library outside the core source without modifying the engine.
+- Default and example libraries use the same contract and quality workflow; one artifact can combine elements from both.
+- Namespaces distinguish same-named elements. Missing libraries or incompatible versions produce explicit errors rather than substitution.
+- Agents can discover custom element meanings, constraints, examples, and supported forms. Unsupported forms are not presented as supported.
+- Long labels, font loading, or dimension changes in user components trigger measurement and avoidance again; third-party components cannot bypass final checks.
+- Unmeasurable components, unsuccessful repairs, or unsupported environments cannot receive a quality pass.
+- Record library, adaptation, and core versions; results must be reproducible for fixed inputs and environments.
+
+## Implementation sequence
+
+1. Complete the failure examples and define supported input sizes and environments. Turn pending examples into checks that can fail. Validate the extension seam with an independent library rather than hard-coding the default catalog.
+2. Establish a complete detect → repair → recheck loop for the first selected defects, such as label occlusion, text overflow, or node overlap.
+3. Extend each of the five forms with recipes, checks, repair strategies, and final display evidence.
+4. Define verifiable Pi and desktop display paths and test client differences.
+5. Complete remaining license, package-release, and Pi plugin distribution work. The repository is already public on GitHub.
+
+This specification does not assume one layout engine for every form or PNG/Mermaid as the only artifact format.

package/docs/expression-elements.md

@@ -0,0 +1,57 @@
+# Expression elements and recipes
+
+Status: agreed first-batch expression references. These are semantic terms, not a newly implemented input schema, and need not map one-to-one to existing diagram primitives.
+
+This catalog provides expression references and a starting point for the default HTML library. HTML users may supply their own elements, recipes, and component mappings under the [extension contract](extensibility.md). Mermaid, pseudocode, text trees, and diff use built-in native structures only, with no external expression libraries.
+
+## Element catalog
+
+| Element | Meaning and use cases | Composition example |
+| --- | --- | --- |
+| Entity / step | A system, role, operation, or capability | Client and server; send request and handle response |
+| Group | Ownership, containment, stage, or responsibility | Group authentication and request handling under the server |
+| Relation | A call, dependency, data flow, or feedback | Client calls server; failure feeds back to a retry step |
+| Branch | An explicit condition and its outcome | Finish on success; retry on failure while below the limit |
+| Note | An explanation, constraint, risk, or conclusion | At most 3 retries; the note is not a request recipient |
+| Comparison / change | A before-and-after difference or alternative | The old flow fails immediately; the new flow adds bounded retries |
+| Emphasis | A focus, critical path, or important object | Emphasize the retry limit without treating it as a new state |
+
+Grouping creates no relationship; spatial order creates no causality; emphasis creates no business state. The agent must declare semantics explicitly.
+
+## Recipe: explain failure and retry
+
+```text
+Steps: send request → handle request
+Branch: success / failure
+Feedback: failure below the retry limit → send again
+Note: at most 3 retries
+Emphasis: retry limit
+```
+
+Use pseudocode to explain logic, Mermaid to explain interactions, or diff to explain the change that introduced retries. One recipe does not mandate a single form. The tool must retain conditions and limits rather than omit them to simplify the diagram.
+
+## Recipe: explain module responsibilities
+
+```text
+Groups: client / server
+Entities: page, request entry point, permission check
+Relations: page calls entry point; entry point depends on permission check
+Note: permission failure prevents further processing
+```
+
+Use a text tree when explaining ownership alone and Mermaid when explaining calls. A text tree should not disguise a call relationship as directory containment.
+
+## Recipe: explain a change
+
+```text
+Comparison: before / after
+Steps: save → return result
+Change: check whether content has changed before saving
+Emphasis: return the cache immediately when unchanged
+```
+
+Use diff for small changes, retaining enough original steps to identify the context. Choose HTML when several interactive states are needed. Automatic wrapping must not change diff markers or the meaning of original lines.
+
+## Relationship to the prototype
+
+Existing Card, Group, Relation, and Note primitives can represent some of these elements; Stack specifies reading order and layout constraints. Cross-form interfaces for branches, comparison, and emphasis are not yet finalized. Do not mistake this catalog for the current MCP tool parameter schema.