@offorte/show-doc 0.0.3 → 0.0.5

package/README.md

@@ -5,7 +5,7 @@
 ShowDoc is an agent skill for Codex, Claude Code, and other compatible coding agents. It replaces
 separate Markdown and HTML versions with one shared HTML artifact for agents and people.
 
-An agent writes compact Markdown and semantic `shw-*` elements. One versioned JavaScript include
+An agent writes compact Markdown and semantic `shw-*` elements. One JavaScript include
 provides the components, Markdown rendering, presentation DOM, and CSS.
 
 The source DOM stays small and focused on content. Agents can read and update it without sorting
@@ -50,6 +50,56 @@ Use ShowDoc for:
 ShowDoc is not intended for dashboards, forms, modals, or large interactive tools. Those need their
 own application code.
 
+## Plans and change recaps
+
+Build a plan from an outcome, a focused comparison or diagram, and steps with clear checks. Build
+a recap from the resulting behavior, a real change excerpt, and the checks that actually ran.
+Existing grids, sections, cards, figures, and tables supply the structure.
+
+For code, `shw-code` supports `language="diff"` for supplied unified patches, `line-numbers`,
+`highlight="2,4-6"`, and notes tied to lines:
+
+<!-- prettier-ignore -->
+```html
+<shw-code
+  filename="save.ts"
+  language="ts"
+  line-numbers
+  highlight="2"
+  annotations='[{"start":2,"text":"Clear the draft only after the save succeeds."}]'
+>
+  await save(draft);
+  clearDraft();
+</shw-code>
+```
+
+Annotations are a JSON array of `start`, optional `end`, and Markdown `text`. Line references are
+1-based positions in the displayed excerpt, including any diff headers. They are not file line
+numbers. Invalid JSON or ranges show an authoring message without hiding the source. Notes remain
+visible below the code. ShowDoc does not fetch source, compute changes, or verify claims.
+
+Use `shw-collapsible content="blocks"` for expandable evidence that contains other components:
+
+<!-- prettier-ignore -->
+```html
+<shw-collapsible summary="Supporting evidence" content="blocks">
+  <shw-code filename="save.ts" language="ts">await save(draft);</shw-code>
+  <shw-table caption="Checks">
+    Check | Result
+    Save retry | Not run
+  </shw-table>
+</shw-collapsible>
+```
+
+The default disclosure body remains Markdown. In blocks mode, wrap prose in `shw-markdown`.
+The [authoring skill](./skills/show-doc/SKILL.md) includes plan and recap recipes, comparison
+guidance, source escaping rules, and the full compact API.
+
+Documents default to light mode, regardless of the system theme. The theme uses a clear title,
+restrained accents, distinct metrics, and subtle surface contrast.
+Use visual variety to explain the content: short comparisons in a grid, wide evidence in a full
+section, and secondary detail in a disclosure. Keep uncertain results and open decisions explicit.
+
 ## Install the skill
 
 After you download or clone this repository, copy the complete [`skills/show-doc`](./skills/show-doc/)
@@ -77,10 +127,33 @@ Ask your agent for the document you need:
 
 > Use the ShowDoc skill to create a visual project update.
 
-The [`show-doc` skill](./skills/show-doc/SKILL.md) contains the full versioned runtime contract,
+The [`show-doc` skill](./skills/show-doc/SKILL.md) contains the runtime setup,
 component reference, and authoring rules. It creates the complete HTML file for you. You do not need
 to choose a CDN script or write setup code.
 
+The skill uses `@latest` CDN URLs by default, so generated documents can receive future published
+updates. Ask for an exact version when a document needs to keep the same runtime. The released
+showcase stays pinned to its matching package version.
+
+## Diagrams
+
+`shw-mermaid` draws flowcharts, state diagrams, and sequence diagrams with cards, routed lines, and
+a dotted canvas that the reader can drag and zoom. An expand button shows any diagram over the full
+window, with a button for light and dark. Subgraphs become lanes. The classes `new`,
+`changed`, and `removed` add a status pill. A frontmatter title appears in a chip, and text after
+`|` appears as grey code. Mermaid draws all other diagram types. These diagrams use React Flow, so
+the Mermaid bundle includes React and shows a small React Flow link in the corner.
+
+Add the `page` attribute and leave out `shw-doc` to show one diagram in the full browser window:
+
+<!-- prettier-ignore -->
+```html
+<shw-mermaid page label="Saving a draft">
+  flowchart LR
+    A[Save draft] --> B{Save succeeds?}
+</shw-mermaid>
+```
+
 ## Safety
 
 ShowDoc uses Micromark with safe defaults. Raw HTML and dangerous URL protocols are not enabled in
@@ -99,13 +172,13 @@ pnpm install --frozen-lockfile
 pnpm dev
 pnpm serve
 pnpm build
-pnpm agent:verify
+pnpm agent:check
 ```
 
 `pnpm serve` rebuilds the package and serves the CDN-backed showcase at
 `http://127.0.0.1:4173`.
 
-`pnpm agent:verify` checks formatting, lint, TypeScript, browser behavior, the Custom Elements
+`pnpm agent:check` checks formatting, lint, TypeScript, browser behavior, the Custom Elements
 Manifest, bundle limits, package contents, and unused code.
 
 ## Releases

package/custom-elements.json

@@ -182,7 +182,7 @@
         },
         {
           "kind": "class",
-          "description": "Shows a syntax-highlighted code block with an optional filename.",
+          "description": "Shows code or a supplied unified diff, with optional source line numbers and notes.",
           "name": "ShwCode",
           "members": [
             {
@@ -204,8 +204,41 @@
                 "text": "string"
               },
               "default": "\"text\"",
-              "description": "Syntax language. Supported values are html, js, ts, and json.",
+              "description": "Syntax language: html, js, ts, json, or diff for a supplied unified diff.",
               "attribute": "language"
+            },
+            {
+              "kind": "field",
+              "name": "lineNumbers",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Show 1-based positions in the displayed source, including diff headers.",
+              "attribute": "line-numbers"
+            },
+            {
+              "kind": "field",
+              "name": "highlight",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "description": "Source lines to emphasize, for example 2,4-6.",
+              "attribute": "highlight"
+            },
+            {
+              "kind": "field",
+              "name": "annotations",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "description": "JSON array of { start, end?, text } notes. Text is safe Markdown; lines are 1-based.",
+              "attribute": "annotations"
             }
           ],
           "attributes": [
@@ -224,8 +257,35 @@
                 "text": "string"
               },
               "default": "\"text\"",
-              "description": "Syntax language. Supported values are html, js, ts, and json.",
+              "description": "Syntax language: html, js, ts, json, or diff for a supplied unified diff.",
               "fieldName": "language"
+            },
+            {
+              "name": "line-numbers",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Show 1-based positions in the displayed source, including diff headers.",
+              "fieldName": "lineNumbers"
+            },
+            {
+              "name": "highlight",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "description": "Source lines to emphasize, for example 2,4-6.",
+              "fieldName": "highlight"
+            },
+            {
+              "name": "annotations",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "description": "JSON array of { start, end?, text } notes. Text is safe Markdown; lines are 1-based.",
+              "fieldName": "annotations"
             }
           ],
           "superclass": {
@@ -237,8 +297,14 @@
         },
         {
           "kind": "class",
-          "description": "Hides optional Markdown details behind a native disclosure control.",
+          "description": "Hides optional Markdown or child document blocks behind a native disclosure control.",
           "name": "ShwCollapsible",
+          "slots": [
+            {
+              "description": "Document blocks when content=\"blocks\".",
+              "name": ""
+            }
+          ],
           "members": [
             {
               "kind": "field",
@@ -262,9 +328,29 @@
               "default": "\"Details\"",
               "description": "Label for the disclosure control.",
               "attribute": "summary"
+            },
+            {
+              "kind": "field",
+              "name": "content",
+              "privacy": "public",
+              "type": {
+                "text": "\"markdown\" | \"blocks\""
+              },
+              "default": "\"markdown\"",
+              "description": "Body input: Markdown text by default, or slotted document blocks.",
+              "attribute": "content"
             }
           ],
           "attributes": [
+            {
+              "name": "content",
+              "type": {
+                "text": "\"markdown\" | \"blocks\""
+              },
+              "default": "\"markdown\"",
+              "description": "Body input: Markdown text by default, or slotted document blocks.",
+              "fieldName": "content"
+            },
             {
               "name": "open",
               "type": {
@@ -981,6 +1067,18 @@
               "default": "\"Diagram\"",
               "description": "Accessible name for the rendered diagram.",
               "attribute": "label"
+            },
+            {
+              "kind": "field",
+              "name": "page",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Fills the browser window with this one diagram. Use it without `shw-doc`.",
+              "attribute": "page",
+              "reflects": true
             }
           ],
           "attributes": [
@@ -992,6 +1090,15 @@
               "default": "\"Diagram\"",
               "description": "Accessible name for the rendered diagram.",
               "fieldName": "label"
+            },
+            {
+              "name": "page",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Fills the browser window with this one diagram. Use it without `shw-doc`.",
+              "fieldName": "page"
             }
           ],
           "superclass": {