@offorte/show-doc 0.0.2 → 0.0.4

package/README.md

@@ -2,24 +2,29 @@
 
 **Write for agents. Render for people.**
 
-ShowDoc is an agent skill for Codex, Claude Code, and other compatible coding agents. It turns
-reports, plans, reviews, and explanations into polished HTML documents. You describe the document.
-The skill handles the structure, components, Markdown, and browser setup.
+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.
 
-Agents work well with Markdown. It is compact, easy to scan, and cheap to change. People often need
-more visual structure. Clear type, spacing, status, columns, code, and optional detail make complex
-documents easier to read.
+An agent writes compact Markdown and semantic `shw-*` elements. One JavaScript include
+provides the components, Markdown rendering, presentation DOM, and CSS.
 
-Normal HTML artifacts solve the visual problem. They often repeat hundreds of lines of HTML, CSS,
-and JavaScript. That source is expensive for an agent to inspect whenever one sentence changes.
-
-The ShowDoc skill keeps the source small. It guides an agent to write Markdown and semantic `shw-*`
-elements. ShowDoc turns that source into a polished document.
+The source DOM stays small and focused on content. Agents can read and update it without sorting
+through repeated presentation code. People get clear type, spacing, status, columns, code, and
+optional detail. There is no second version to keep in sync.
 
 In one practical review, a normal artifact was estimated at **300 to 800 lines**. The same document
 was estimated at **40 to 80 lines of ShowDoc source**. This is an illustrative comparison, not a
 fixed benchmark. The exact reduction depends on the document.
 
+## Example
+
+Open [How Offorte ShowDoc works](https://offorte.github.io/show-doc/) to see a complete ShowDoc
+document. It explains the authoring model and shows the components in a real page.
+
+Then use **View Page Source** in your browser. The source contains compact `shw-*` elements,
+Markdown, and one versioned CDN script. It does not contain copied component markup or presentation
+CSS that an agent must maintain.
+
 ## What the skill creates
 
 The skill creates compact source that contains the meaning and layout decision:
@@ -45,9 +50,55 @@ Use ShowDoc for:
 ShowDoc is not intended for dashboards, forms, modals, or large interactive tools. Those need their
 own application code.
 
-See the complete [codebase overview artifact](./examples/codebase-overview.html). It uses ShowDoc to
-explain ShowDoc. Each release also publishes this artifact as the
-[live ShowDoc showcase](https://offorte.github.io/show-doc/).
+## 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
 
@@ -76,10 +127,14 @@ 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.
+
 ## Safety
 
 ShowDoc uses Micromark with safe defaults. Raw HTML and dangerous URL protocols are not enabled in
@@ -101,12 +156,23 @@ pnpm build
 pnpm agent:verify
 ```
 
-`pnpm serve` rebuilds the production bundle and serves the isolated showcase at
+`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
 Manifest, bundle limits, package contents, and unused code.
 
+## Releases
+
+Release Please reads Conventional Commit types on `main`. `fix:` and `opt:` prepare a patch release.
+`feat:` prepares a minor release. A type with `!`, or a `BREAKING CHANGE` footer, prepares a major
+release.
+
+Merging the Release Please pull request creates the GitHub release. The `Release package` workflow
+then verifies and publishes the npm package. After publication succeeds, it calls the separate
+`Deploy Pages` workflow with the release tag. `Deploy Pages` only deploys the example site. It can
+also run manually.
+
 ## About Offorte
 
 Offorte is automated proposal software that helps businesses create, send, and track beautiful,

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": {