@offorte/show-doc 0.0.3 → 0.0.5

package/dist/types/components/shw-code.d.ts

@@ -1,6 +1,7 @@
 import { LitElement } from "lit";
+import "./shw-markdown";
 /**
- * Shows a syntax-highlighted code block with an optional filename.
+ * Shows code or a supplied unified diff, with optional source line numbers and notes.
  *
  * @element shw-code
  */
@@ -13,12 +14,28 @@ export declare class ShwCode extends LitElement {
         language: {
             type: StringConstructor;
         };
+        lineNumbers: {
+            type: BooleanConstructor;
+            attribute: string;
+        };
+        highlight: {
+            type: StringConstructor;
+        };
+        annotations: {
+            type: StringConstructor;
+        };
     };
     static styles: import("lit").CSSResult[];
     /** Optional filename shown above the code. */
     filename: string;
-    /** Syntax language. Supported values are html, js, ts, and json. */
+    /** Syntax language: html, js, ts, json, or diff for a supplied unified diff. */
     language: string;
+    /** Show 1-based positions in the displayed source, including diff headers. */
+    lineNumbers: boolean;
+    /** Source lines to emphasize, for example 2,4-6. */
+    highlight: string;
+    /** JSON array of { start, end?, text } notes. Text is safe Markdown; lines are 1-based. */
+    annotations: string;
     protected render(): import("lit").TemplateResult<1>;
 }
 declare global {

package/dist/types/components/shw-collapsible.d.ts

@@ -1,13 +1,17 @@
 import { LitElement } from "lit";
 import "./shw-markdown";
 /**
- * Hides optional Markdown details behind a native disclosure control.
+ * Hides optional Markdown or child document blocks behind a native disclosure control.
  *
  * @element shw-collapsible
+ * @slot - Document blocks when content="blocks".
  */
 export declare class ShwCollapsible extends LitElement {
     #private;
     static properties: {
+        content: {
+            type: StringConstructor;
+        };
         open: {
             type: BooleanConstructor;
             reflect: boolean;
@@ -21,6 +25,8 @@ export declare class ShwCollapsible extends LitElement {
     open: boolean;
     /** Label for the disclosure control. */
     summary: string;
+    /** Body input: Markdown text by default, or slotted document blocks. */
+    content: "markdown" | "blocks";
     protected render(): import("lit").TemplateResult<1>;
 }
 declare global {

package/dist/types/components/shw-mermaid.d.ts

@@ -10,10 +10,16 @@ export declare class ShwMermaid extends LitElement {
         label: {
             type: StringConstructor;
         };
+        page: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
     };
     static styles: import("lit").CSSResult[];
     /** Accessible name for the rendered diagram. */
     label: string;
+    /** Fills the browser window with this one diagram. Use it without `shw-doc`. */
+    page: boolean;
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected render(): import("lit").TemplateResult<1>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@offorte/show-doc",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Agent skill and web components for polished, human-readable HTML documents.",
   "keywords": [
     "documentation",
@@ -73,7 +73,7 @@
     "fallow:check": "fallow --format compact --fail-on-issues --summary",
     "verify:source": "pnpm format:check && pnpm lint && pnpm typecheck",
     "verify:build": "pnpm test:browser && pnpm manifest:check && pnpm check:build && pnpm check:package && pnpm fallow:check",
-    "agent:verify": "pnpm verify:source && pnpm build && pnpm verify:build",
+    "agent:check": "pnpm verify:source && pnpm build && pnpm verify:build",
     "prepack": "pnpm build && pnpm manifest:check && pnpm check:build && pnpm check:package"
   },
   "dependencies": {
@@ -86,8 +86,12 @@
     "@tailwindcss/vite": "4.3.3",
     "@types/node": "26.3.0",
     "@types/prismjs": "1.26.6",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
     "@web/test-runner": "1.0.0",
     "@web/test-runner-playwright": "1.0.0",
+    "@xyflow/react": "12.12.0",
+    "elkjs": "0.12.1",
     "fallow": "3.18.0",
     "mermaid": "11.17.2",
     "micromark": "4.0.2",
@@ -97,6 +101,8 @@
     "oxlint": "1.80.0",
     "playwright": "1.62.1",
     "prismjs": "1.30.0",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
     "tailwindcss": "4.3.3",
     "typescript": "7.0.2",
     "vite": "8.2.2"

package/skills/show-doc/SKILL.md

@@ -1,22 +1,25 @@
 ---
 name: show-doc
-description: Create compact, readable standalone HTML documents with versioned Offorte ShowDoc components and Markdown when a human-facing artifact needs more visual structure than normal prose.
+description: Create compact, readable standalone HTML documents with Offorte ShowDoc components and Markdown when a human-facing artifact needs more visual structure than normal prose, or one full-page Mermaid diagram when the user asks for a Mermaid diagram.
 metadata:
-  version: "0.0.3" # x-release-please-version
+  version: "0.0.5" # x-release-please-version
 ---
 
 # ShowDoc
 
-Use ShowDoc when the user asks for a ShowDoc or HTML document. Otherwise, use it for reports, plans,
+Use ShowDoc when the user asks for a ShowDoc, an HTML document, or a Mermaid diagram. Otherwise, use it for reports, plans,
 reviews, decisions, and explanations that need a durable file or more visual structure than normal
 chat Markdown. Do not use it for dashboards, forms, or application-like tools.
 
 ## Output contract
 
-Create one HTML file. Use this skill's exact `metadata.version` in the CDN URL. Use the complete
-starting point below when the document does not need Mermaid:
+Create one HTML file. Use `@latest` in the CDN URL by default. This loads the latest published
+release, so an existing document can receive runtime updates. If the user needs a fixed result,
+use an exact published version instead. The skill's `metadata.version` identifies the skill
+release; it does not select the default runtime version.
 
-<!-- x-release-please-start-version -->
+Documents use light mode by default, regardless of the system theme. Use the complete starting
+point below when the document does not need Mermaid:
 
 ```html
 <!doctype html>
@@ -26,20 +29,23 @@ starting point below when the document does not need Mermaid:
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <script
       type="module"
-      src="https://cdn.jsdelivr.net/npm/@offorte/show-doc@0.0.3/dist/showdoc.js"
+      src="https://cdn.jsdelivr.net/npm/@offorte/show-doc@latest/dist/showdoc.js"
     ></script>
-    <title>Release decision</title>
+    <title>Retry plan</title>
   </head>
   <body>
     <shw-doc>
-      <shw-header heading="Release decision" eyebrow="Review">
-        The current build passed all required checks.
+      <shw-header heading="A safer retry" eyebrow="Implementation plan">
+        Preserve the draft when a temporary connection error interrupts a save.
       </shw-header>
 
-      <shw-summary>The release is **approved**. Complete these two steps.</shw-summary>
+      <shw-summary heading="Proposal">Keep the draft and let the user retry.</shw-summary>
 
       <shw-section heading="Next steps">
-        <shw-steps> 1. Publish the package. 2. Confirm the production version. </shw-steps>
+        <shw-steps>
+          1. Keep the current draft after a failed save. 2. Check that a successful retry saves it
+          once.
+        </shw-steps>
       </shw-section>
     </shw-doc>
   </body>
@@ -51,12 +57,10 @@ If the document uses Mermaid, replace the script in the starting point with the
 ```html
 <script
   type="module"
-  src="https://cdn.jsdelivr.net/npm/@offorte/show-doc@0.0.3/dist/showdoc-mermaid.js"
+  src="https://cdn.jsdelivr.net/npm/@offorte/show-doc@latest/dist/showdoc-mermaid.js"
 ></script>
 ```
 
-<!-- x-release-please-end -->
-
 Use only one script. The Mermaid bundle contains all core components.
 
 Use normal document metadata. Wrap the visible document in one `shw-doc`. Do not add inline
@@ -68,27 +72,28 @@ available. Return the exact file path.
 
 ## Component chooser
 
-| Element           | Compact API                          | Use                                              |
-| ----------------- | ------------------------------------ | ------------------------------------------------ |
-| `shw-doc`         | -                                    | The one page canvas.                             |
-| `shw-header`      | `heading`, `eyebrow?`                | The one title and short Markdown lead.           |
-| `shw-summary`     | `heading?`                           | The answer before the evidence.                  |
-| `shw-section`     | `heading?`, `intro?`, `level?`       | A topic with an automatic divider.               |
-| `shw-markdown`    | -                                    | Normal prose, lists, links, tasks, and headings. |
-| `shw-mermaid`     | `label?`                             | A diagram from Mermaid source.                   |
-| `shw-grid`        | `columns?`                           | Two to four sibling blocks to compare.           |
-| `shw-card`        | `heading?`, `label?`, `tone?`        | One grouped idea, choice, or status.             |
-| `shw-badge`       | `tone?`                              | A short standalone state or category.            |
-| `shw-callout`     | `heading?`, `tone?`                  | One message that needs attention.                |
-| `shw-stat`        | `label`, `value`, `change?`, `tone?` | One prominent metric or result.                  |
-| `shw-steps`       | -                                    | A process from numbered Markdown lines.          |
-| `shw-code`        | `filename?`, `language?`             | Highlighted HTML, JS, TS, or JSON.               |
-| `shw-table`       | `caption?`                           | Row and column data from pipe text.              |
-| `shw-figure`      | `caption?`                           | An image, inline SVG, or diagram.                |
-| `shw-collapsible` | `summary?`, `open?`                  | Evidence or detail most readers can skip.        |
+| Element           | Compact API                                                             | Use                                              |
+| ----------------- | ----------------------------------------------------------------------- | ------------------------------------------------ |
+| `shw-doc`         | -                                                                       | The one page canvas.                             |
+| `shw-header`      | `heading`, `eyebrow?`                                                   | The one title and short Markdown lead.           |
+| `shw-summary`     | `heading?`                                                              | The answer before the evidence.                  |
+| `shw-section`     | `heading?`, `intro?`, `level?`                                          | A topic with an automatic divider.               |
+| `shw-markdown`    | -                                                                       | Normal prose, lists, links, tasks, and headings. |
+| `shw-mermaid`     | `label?`, `page?`                                                       | A diagram from Mermaid source.                   |
+| `shw-grid`        | `columns?`                                                              | Two to four sibling blocks to compare.           |
+| `shw-card`        | `heading?`, `label?`, `tone?`                                           | One grouped idea, choice, or status.             |
+| `shw-badge`       | `tone?`                                                                 | A short standalone state or category.            |
+| `shw-callout`     | `heading?`, `tone?`                                                     | One message that needs attention.                |
+| `shw-stat`        | `label`, `value`, `change?`, `tone?`                                    | One prominent metric or result.                  |
+| `shw-steps`       | -                                                                       | A process from numbered Markdown lines.          |
+| `shw-code`        | `filename?`, `language?`, `line-numbers?`, `highlight?`, `annotations?` | Code, supplied diffs, and notes tied to lines.   |
+| `shw-table`       | `caption?`                                                              | Row and column data from pipe text.              |
+| `shw-figure`      | `caption?`                                                              | An image, inline SVG, or diagram.                |
+| `shw-collapsible` | `summary?`, `open?`, `content?`                                         | Optional Markdown or child document blocks.      |
 
 Defaults reduce source. A summary heading is `Summary`. A section level is `2`. Grid columns are
-`2`. A collapsible summary is `Details`. Default tone is `neutral`, except callouts use `info`.
+`2`. A collapsible summary is `Details`, and its content mode is `markdown`. Default tone is
+`neutral`, except callouts use `info`.
 
 Tones are `info`, `success`, `warning`, `danger`, and `neutral`. Use them only when the meaning helps
 the reader.
@@ -99,8 +104,8 @@ the reader.
 - Start with `shw-header`. Add `shw-summary` when readers need the answer first.
 - Use Markdown for the story. Add a component only when it gives meaning or layout.
 - Use `shw-steps` for a simple sequence. Write each step as `1. ...`, `2. ...`, and so on.
-- Use `shw-code` without `language` for pseudocode, call trees, component trees, file trees, and
-  structural diffs. Set `language` only for highlighted HTML, JS, TS, or JSON source.
+- Use `shw-code` without `language` for pseudocode and structural trees. Use `html`, `js`, `ts`, or
+  `json` for syntax highlighting. Use `diff` for a supplied unified patch.
 - Use `shw-mermaid` when relationships, branches, data flow, or participant interactions matter.
 - Put two or three comparable cards or stats in `shw-grid`.
 - Use a table only for aligned data. Table body cells support Markdown.
@@ -110,10 +115,96 @@ the reader.
 Use more than one visual form only when each one answers a different question. Do not turn every
 paragraph into a card. Do not use a callout as decoration.
 
+## Give the document a visual rhythm
+
+For a substantial document, choose a useful central visual: a comparison, a flow, a change excerpt,
+or a small set of real metrics. Build the explanation around it. Alternate readable prose with
+focused visuals and compact evidence instead of repeating the same grid of cards in every section.
+
+- Use the header eyebrow for context and a short title for the main idea.
+- Keep prose narrow. Give code, wide tables, and diagrams a full section when they need space.
+- Use grids for comparable short items. Stack wide screenshots and long code excerpts.
+- Label comparisons explicitly: current/proposed, before/after, or option names. Use the same
+  capture size and scale for screenshots. Keep unchanged context visible.
+- Put the purpose of a code excerpt or diagram immediately above it. Use a figure caption for
+  the visual's scope, source, or limitation.
+- Use the default theme and semantic tones. The components provide accent details and subtle
+  surface contrast. Do not invent metrics, statuses, icons, or decorative panels to fill space.
+
+## Plan and recap recipes
+
+These are starting points. Omit sections that do not help with the actual task.
+
+**Implementation plan:** Start with the proposed outcome and the reason. Show current/proposed
+behavior with two cards in a grid, or use a Mermaid diagram for relationships. Use sections inside
+a grid when each side needs several child components. Record the chosen direction separately from
+open questions. Use steps for the work sequence; name the expected result and check for each step.
+Put supporting source and rejected alternatives in disclosures.
+
+**Change recap:** Start with what changed and who it affects. Show a small real diff or matched
+before/after figures when comparison helps. Explain the important lines with a few annotations.
+Use a table for checks, observed results, and remaining gaps. Keep blockers visible. Put long logs
+and secondary evidence in disclosures.
+
+Use source facts for filenames, code, fields, and results. Label proposals, inferred UI sketches,
+and illustrative examples. Distinguish **implemented** from **verified**. Name which checks ran;
+never turn a suggested check or an unchecked box into a passed result.
+
+## Rich expandable detail
+
+Use `content="blocks"` to place other ShowDoc components inside a disclosure. Wrap prose in
+`shw-markdown` in this mode. Keep Markdown text as the default for a simple note.
+
+<!-- prettier-ignore -->
+```html
+<shw-collapsible summary="Inspect the evidence" content="blocks">
+  <shw-code filename="save.ts" language="ts">await save(draft);</shw-code>
+  <shw-table caption="Verification record">
+    Check | Result
+    Retry after a failed save | Not run
+  </shw-table>
+</shw-collapsible>
+```
+
+## Code changes and annotations
+
+ShowDoc displays supplied source. It does not fetch files, compute a diff, or verify a claim.
+Use `language="diff"` for unified diff text. Preserve its headers and `+`, `-`, and space prefixes.
+Do not use a diff when a short after-only example explains the change better.
+
+Use `line-numbers` when referring to code lines. `highlight="2,4-6"` emphasizes selected lines.
+`annotations` is a JSON array with `start`, optional `end`, and Markdown `text`. Notes stay visible
+below the code. Use a few notes to explain intent, consequences, or a subtle constraint.
+
+All line references are **1-based positions in the displayed excerpt**, including diff headers.
+They are not repository line numbers. Count after removing the outer blank lines and common
+indentation. Invalid JSON or out-of-range references produce a visible authoring message; correct
+that message before sharing the document.
+
+<!-- prettier-ignore -->
+```html
+<shw-code
+  filename="save.ts"
+  language="ts"
+  line-numbers
+  highlight="2"
+  annotations='[{"start":2,"text":"Keep the draft available until the save succeeds."}]'
+>
+  async function saveDraft(draft) {
+    await save(draft);
+    clearDraft();
+  }
+</shw-code>
+```
+
+In single-quoted JSON attributes, encode an apostrophe as `&#39;`. Encode `&` as `&amp;` and literal
+`<` as `&lt;`. Use JSON escapes for double quotes inside note text.
+
 ## Source rules
 
 Keep the HTML shallow. Markdown-rendering components read their text content. Do not nest a
-component inside their Markdown.
+component inside their Markdown. Layout components and a collapsible with `content="blocks"`
+accept child components.
 
 Blank lines create paragraphs. Task lists use `- [ ]` and `- [x]`. Strikethrough uses `~~text~~`.
 Start optional Markdown headings at `##`. `shw-header` already creates the single `h1`.
@@ -127,4 +218,53 @@ Raw HTML inside Markdown is disabled. Write `&lt;` for a literal `<`, including
 Write Mermaid diagram text directly inside `shw-mermaid`. Set `label` to its short accessible name.
 The Mermaid bundle supports the full Mermaid package and makes no extra runtime request.
 
+## Mermaid diagrams
+
+ShowDoc draws flowcharts, state diagrams, and sequence diagrams itself. Mermaid draws every other
+diagram type, and any diagram with `click` links, icons, images, or half arrows.
+
+The page is HTML, so write `&lt;` for each `<` in the source. For example, write
+`state check &lt;&lt;choice&gt;&gt;`. Write a second line in a label as `\n`, not `<br/>`. The second
+line appears as small code text.
+
+- A `subgraph` in a flowchart becomes a lane, a column with an uppercase title. Name each lane after
+  what its parts do. A nested subgraph, a line from a node to itself, or a line to a subgraph gives a
+  normal group layout instead of lanes.
+- `:::new`, `:::changed`, and `:::removed` add a status pill. Use them only when the diagram compares
+  two states.
+- `:::icon-code`, `window`, `box`, `play`, `queue`, `service`, `db`, `file`, `user`, `cloud`, or
+  `decision` (each with the `icon-` prefix) adds an icon. `[( )]` adds the database icon. In a lane,
+  every card has an icon.
+- A frontmatter title appears in a chip above the diagram. Text after `|` appears as grey code:
+  `title: Container view | architecture-overview · hero`.
+
+## Only a diagram
+
+When the user asks only for a Mermaid diagram, do not build a document. Write this page with one
+`shw-mermaid` that has the `page` attribute and no `shw-doc`.
+
+<!-- prettier-ignore -->
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <script
+      type="module"
+      src="https://cdn.jsdelivr.net/npm/@offorte/show-doc@latest/dist/showdoc-mermaid.js"
+    ></script>
+    <title>Save flow</title>
+  </head>
+  <body>
+    <shw-mermaid page label="Saving a draft">
+      flowchart LR
+        A[Save draft] --> B{Save succeeds?}
+        B -->|Yes| C[Clear draft]
+        B -->|No| D[Keep draft]
+    </shw-mermaid>
+  </body>
+</html>
+```
+
 Do not run a generic HTML formatter over the result. It can remove meaningful Markdown line breaks.