hd-garden 0.13.3 → 0.14.2

package/docs/handbook/en/components.md

@@ -1,221 +1,13 @@
 ---
-title: Components Overview
-navTitle: Overview
-description: Live previews of the garden fences, plus link cards, source chips, and local images.
+title: Components
+navTitle: Components
+description: Components
 section: components
 order: 30
 ---
 
-## [Reference Card · card](/garden/en/components/card)
+Use one `garden compose` fence for article layouts, rich content, semantic scenes and interactive explanations. Select components inside that entry; use ordinary Markdown when it already communicates the idea.
 
-```garden card
-title: SQLite Write-Ahead Logging
-url: https://www.sqlite.org/wal.html
-meta: Documentation · sqlite.org
-description: Appends changes sequentially to a write-ahead log while readers continue reading the original database pages, reducing read-write contention.
-points:
-  - Writes append to the end of the `-wal` file instead of overwriting database pages in place on commit.
-  - Readers record the current end-of-log mark to see a consistent snapshot without blocking concurrent writers.
-```
-
-## [Key Figures · stat](/garden/en/components/stat)
-
-```garden stat
-items:
-  - label: Reading Column
-    value: "740"
-    unit: px
-    caption: Default prose column width
-  - label: Wide Figure Limit
-    value: "1040"
-    unit: px
-    caption: Extends up to 150px on each side
-  - label: Wide Table Limit
-    value: "1340"
-    unit: px
-    caption: Extends up to 300px on each side
-```
-
-## [Side-by-Side Comparison · compare](/garden/en/components/compare)
-
-```garden compare
-items:
-  - title: Describe the change in one sentence
-    text: Idea block under full code; the AI writes the diff.
-  - title: Write the diff by hand
-    text: Place a diff block right below the full code block.
-```
-
-## [Step Timeline · timeline](/garden/en/components/timeline)
-
-```garden timeline
-items:
-  - date: Step 1
-    title: Sync Content and Assets
-    text: Validate Front Matter, copy attachments, and build the search index and RSS feed.
-  - date: Step 2
-    title: Build Static Site Output
-    text: Prerender every route into the static output directory.
-```
-
-## [Bar Chart · chart](/garden/en/components/chart)
-
-```garden chart
-title: Max Width by Layout Zone
-xLabel: Layout Zone
-yLabel: Max Width
-unit: px
-data:
-  - x: Prose Column
-    y: 740
-  - x: Wide Figure Zone
-    y: 1040
-  - x: Wide Table Zone
-    y: 1340
-```
-
-## [Explanation diagram · compose](/garden/en/components/compose)
-
-```garden compose
-<intent>
-The top row is delivery order: Understand, Design, Ship. The bottom row is the decision loop to emphasize: Hypothesize, Cheap test, Iterate or stop. The top row is background. The bottom row is the point.
-</intent>
-<row align="center">
-  <title align="center">Understand</title>
-  <arrow dir="right"/>
-  <title align="center">Design</title>
-  <arrow dir="right"/>
-  <title align="center">Ship</title>
-</row>
-<divider/>
-<row align="center">
-  <pill tone="muted">Hypothesize</pill>
-  <arrow dir="right"/>
-  <pill tone="muted">Cheap test</pill>
-  <arrow dir="right"/>
-  <pill tone="muted">Iterate or stop</pill>
-</row>
-```
-
-## [Embedded Web Snippet · html](/garden/en/components/html)
-
-```garden html
-title: Character Count Widget
-code: |
-  <!doctype html>
-  <html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <style>
-      body { margin: 0; padding: 16px 18px; font: 14px/1.6 system-ui, sans-serif; color: #1b1a18; background: #faf9f5; }
-      input { width: 100%; box-sizing: border-box; padding: 8px 10px; border: 1px solid #d5d1c8; border-radius: 6px; font: inherit; background: #fff; color: #1b1a18; }
-      .meta { margin-top: 10px; color: #6e6b64; font-variant-numeric: tabular-nums; }
-      strong { color: #1b1a18; }
-    </style>
-  </head>
-  <body>
-    <input id="txt" value="Keep your posts in a Git repository and push to deploy." aria-label="Sample text input" />
-    <div class="meta">Characters: <strong id="count">55</strong></div>
-    <script>
-      const input = document.getElementById("txt");
-      const count = document.getElementById("count");
-      input.addEventListener("input", () => { count.textContent = String(input.value.length); });
-    </script>
-  </body>
-  </html>
-```
-
-## [Interactive Formula & Parameters · interactive](/garden/en/components/interactive)
-
-```garden compose #overview-reading
-caption: "Example: estimate reading time from word count and reading speed."
----
-<State words={6000} speed={400} />
-<Let minutes={round(words / speed)} />
-
-<Slider bind="words" label="Word count" min={1000} max={20000} step={500} unit="words" />
-<Slider bind="speed" label="Reading speed" min={200} max={800} step={50} unit="wpm" />
-
-<Stat label="Estimated reading time" value={minutes} unit="min" />
-```
-
-## [File Download & Preview · file](/garden/en/components/file)
-
-```garden file
-src: ./components/file/checklist.md
-title: Pre-publish Checklist
-note: Click Preview to read inline or Download to save the file
-```
-
-## [Relationship diagram · relations](/garden/en/components/relations)
-
-```garden relations
-items:
-  - title: Pick
-    text: Choose this month's book
-  - title: Read
-    text: Finish the agreed chapters each week
-  - title: Talk
-    text: Meet and share views
-  - title: Review
-    text: Note what to change next time
-links:
-  - from: 1
-    to: 2
-  - from: 2
-    to: 3
-  - from: 3
-    to: 4
-  - from: 4
-    to: 1
-  - from: 3
-    to: 1
-    style: dashed
-    label: shapes the pick
-```
-
-## [Icon List · list](/garden/en/components/list)
-
-```garden list
-items:
-  - icon: search
-    text: Searches for this month's title
-  - icon: eye
-    text: Reads 3 reviews
-  - icon: heart
-    text: Saves the event page
-  - icon: chat
-    text: Asks in the group chat whether listening only is fine
-```
-
-## [Choice Cards · choice](/garden/en/components/choice)
-
-```garden choice
-title: Where should we meet next month?
-items:
-  - icon: idea
-    value: $6 each
-    text: Corner café, one drink included
-    label: Prefer the atmosphere
-    reply: Café it is. We will book the long table by the window.
-  - icon: book
-    value: Free
-    text: Library meeting room, booking needed
-    label: Prefer the quiet
-    reply: Library it is. We will book the room at the start of the month.
-none:
-  label: Neither / not sure
-  reply: No problem. We will share a few more venues in the group chat.
-```
-
-## [Link card · {card}](/garden/en/components/link-card)
-
-[Supported KaTeX functions](https://katex.org/docs/supported.html){card}
-
-## [Source chip · {source}](/garden/en/components/source)
-
-Cited from Wikipedia [wikipedia.org](https://en.wikipedia.org/wiki/Book_discussion_club){source}
-
-## [Local image](/garden/en/components/image)
-
-![Reading column, wide figure zone, and wide table zone](../assets/reading-layout-en.svg)
+- [Compose](/garden/en/components/compose)
+- [Compose reference](/garden/en/reference/compose)
+- [Icons](/garden/en/reference/compose-icons)

package/docs/handbook/en/deploy.md

@@ -38,6 +38,17 @@ jobs:
     steps:
       - uses: actions/checkout@v7
 
+      - name: Restore generated Garden caches
+        uses: actions/cache@v4
+        with:
+          path: |
+            .garden/image-sizes.json
+            .garden/link-assets.json
+            public/link-assets
+          key: ${{ runner.os }}-garden-generated-v1-${{ github.ref_name }}-${{ github.run_id }}
+          restore-keys: |
+            ${{ runner.os }}-garden-generated-v1-${{ github.ref_name }}-
+
       - uses: actions/setup-node@v7
         with:
           node-version: 22

package/docs/handbook/en/index.md

@@ -18,14 +18,14 @@ Drop an unnamed `garden` fence where the interactive block should go and state w
 ````markdown
 ## Writing Pace
 
-```garden
+```garden compose
 Let the reader drag daily word count and writing days per week to see how many weeks an 8,000-word article takes.
 ```
 ````
 
 ### 2. The Agent Scans and Writes Back the Component
 
-Tell the Agent to compile `content/posts/writing-pace.md`. Following the `garden-ui` skill in the repository, the Agent first runs `npx garden ui scan` to read the line number, original wording, and hash:
+Tell the Agent to compile `content/posts/writing-pace.md`. Following the `garden-compose` skill in the repository, the Agent first runs `npx garden ui scan` to read the line number, original wording, and hash:
 
 ```console
 $ npx garden ui scan content/posts/writing-pace.md
@@ -34,7 +34,7 @@ $ npx garden ui scan content/posts/writing-pace.md
   "draft": false,
   "blocks": [
     {
-      "lang": "garden-idea",
+      "lang": "garden-compose",
       "status": "uncompiled",
       "startLine": 9,
       "intentHash": "8866427a",
@@ -52,54 +52,42 @@ $ npx garden ui apply content/posts/writing-pace.md --intent-hash 8866427a --fil
 {"ok":true,"file":"content/posts/writing-pace.md","kind":"garden","line":9}
 ```
 
-### 3. The Pre-commit Hook Checks and Prints a Fix Prompt
+### 3. The Pre-commit Hook Checks and Points to the Project Skill
 
-On the first `garden sync` or `garden dev` run, Garden writes `exec npx --no-install garden ui check --staged --quiet` to `.git/hooks/pre-commit`. If the author commits before step 2, the hook blocks the commit and prints a ready-to-paste prompt for the AI:
+On the first `garden sync` or `garden dev` run, Garden writes `exec npx --no-install garden ui check --staged --quiet` to `.git/hooks/pre-commit`. If the author commits before step 2, the hook blocks the commit and shows diagnostics and a short project-skill instruction:
 
 ```console
 $ git commit -m "Writing pace"
-content/posts/writing-pace.md:9  -  garden-idea  uncompiled idea remaining
-
-──────────────────────── Fix prompt for AI ────────────────────────
-Handle the Garden post blocks listed below: compile uncompiled ideas, and fix interactive blocks that have errors.
-
-Rules:
-- First run npx garden ui prompt and read the component catalog and rules; if the repo has the garden-ui skill, follow its flow.
-- Change only the listed blocks. Write them back with npx garden ui apply <post> --id <id> (use --intent-hash for ideas without an id). Do not edit the post by hand.
-- Keep the author's meaning. When done, run npx garden ui check <post> until it passes.
-- If you cannot access this repository, reply with only the finished fence for each block.
-
-1. content/posts/writing-pace.md, lines 9–11, intent-hash: 8866427a
-   - garden-idea: this idea is not compiled yet; compile it into garden compose or another garden component (or put the sentence back into the prose).
-
-Current fence:
-
-```garden
-Let the reader drag daily word count and writing days per week to see how many weeks an 8,000-word article takes.
-```
-────────────────────────────────────────────────────────────
-Wrote .garden/ui-fix-prompt.md. To commit anyway, run git commit --no-verify.
+content/posts/writing-pace.md:9  -  compose-uncompiled  uncompiled compose idea remaining
+Use garden-compose skill (.agents/skills/garden-compose/SKILL.md), fix the failing blocks, then recheck.
 ```
 
-The same prompt is saved to `.garden/ui-fix-prompt.md` and copied to the clipboard when a clipboard command is available. Once the Agent applies the block and the author commits again, the hook exits silently with code `0`.
+The terminal shows diagnostics and a short instruction to load the project `garden-compose` skill. No file, clipboard copy, source dump, or catalog export is produced by default. After repair, the hook exits silently with code `0`.
 
 ### 4. The Rendered Result
 
 The `garden compose` fence written back in step 2 renders directly on the article page as an interactive calculator:
 
 ```garden compose #writing-pace
-caption: Writing a few hundred extra words each day finishes sooner than adding another writing day per week.
-intent: |
-  Let the reader drag daily word count and writing days per week to see how many weeks an 8,000-word article takes.
+caption: Writing a few hundred extra words each day finishes sooner than adding
+  another writing day per week.
+intent: >
+  Let the reader drag daily word count and writing days per week to see how many
+  weeks an 8,000-word article takes.
 ---
-<State daily={500} days={3} />
-<Let weekly={daily * days} />
-<Let weeks={ceil(8000 / weekly)} />
+{@body const [daily, setDaily] = DIL.useState(500)}
+{@body const [days, setDays] = DIL.useState(3)}
+{@body const weekly = daily * days}
+{@body const weeks = ceil(8000 / weekly)}
+
+
 
-<Slider bind="daily" label="Words per day" min={200} max={2000} step={100} unit="words" />
-<Slider bind="days" label="Days per week" min={1} max={7} step={1} unit="days" />
 
-<Stat label="Weeks to finish 8,000 words" value={weeks} unit="weeks" hint="Rounded up to full weeks" />
+<slider bind="daily" label="Words per day" min={200} max={2000} step={100} unit="words" />
+<slider bind="days" label="Days per week" min={1} max={7} step={1} unit="days" />
+
+<stat label="Weeks to finish 8,000 words" value={weeks} unit="weeks" hint="Rounded up to full weeks" />
+
 ```
 
 > [!IMPORTANT] Humans and Agents Share the Same Tools
@@ -153,25 +141,13 @@ pages:
 
 ## Structured Components in Markdown
 
-Use ```` ```garden <name> ```` fences to insert metrics, side-by-side comparisons, timelines, or charts. Here is a `garden stat` block:
-
-```garden stat
-items:
-  - label: Reading Column
-    value: "740"
-    unit: px
-    caption: Default width for paragraphs, code blocks, and lists
-  - label: Wide Figure Zone
-    value: "1040"
-    unit: px
-    caption: Screenshots display at half their pixel width and expand up to this limit above ~2000px
-  - label: Wide Table Zone
-    value: "1340"
-    unit: px
-    caption: Maximum width for wide multi-column tables expanding symmetrically on desktop
+Use `garden compose` to combine metrics, comparisons, timelines, or plots. Here is a metric scene:
+
+```garden compose
+<stack><metric label="Reading Column" value="740" unit="px" caption="Default width for paragraphs, code blocks, and lists"></metric><metric label="Wide Figure Zone" value="1040" unit="px" caption="Screenshots display at half their pixel width and expand up to this limit above ~2000px"></metric><metric label="Wide Table Zone" value="1340" unit="px" caption="Maximum width for wide multi-column tables expanding symmetrically on desktop"></metric></stack>
 ```
 
-The component pages cover the `garden` fences, plus link cards, source chips, and local images. Explanation diagrams are [compose](/garden/en/components/compose). See [Components Overview](/garden/en/components) for the live examples.
+The component pages use `garden compose` as the single Garden author entry, alongside link cards, source chips, and local images. Combine content, layout, and interactions inside [compose](/garden/en/components/compose). See [Components Overview](/garden/en/components) for the live examples.
 
 <h2 id="garden-admin-title">From Init to Daily Writing</h2>
 

package/docs/handbook/en/reference/compose.md

@@ -1,182 +1,111 @@
 ---
-title: Component reference · compose
+title: Compose reference
 navTitle: compose
-description: Scannable catalog of every compose tag, shared tokens, and links to the icon grid.
+description: One author entry, executable rendering contracts and verification.
 section: reference
 order: 6
 badge: compose
 ---
 
-[← Component reference](/garden/en/reference) · [Usage](/garden/en/components/compose) · [Icons](/garden/en/reference/compose-icons)
+## One entry, component selection inside it
 
-Fence: ` ```garden compose `. Author intent stays in `<intent>` (not drawn). Unknown tags fail with `compose-invalid`.
+Use `garden compose`. Select by the reader's task, not by another fence name:
 
-**68 tags** in the catalog below. Icons: **690** names — see [compose icons](/garden/en/reference/compose-icons).
+| Need | Compose structure |
+| :--- | :--- |
+| Reference material and takeaways | `resources/resource`, nested `point`, `reference` |
+| Key results | `metric` with label, value, unit, caption, paragraphs and references |
+| Time or stages | `timeline/event` |
+| Alternatives and verdicts | `compare/item` |
+| Icon-led editorial paragraphs | `icon-list/entry` or a small `icon` beside one shared text container |
+| Download and preview | `files/file` or one `file src="…"` |
+| Connected concepts | `relations/entity/edge`, stable ids; 3–6 entities |
+| Rich selectable cards and replies | `choices/choice-option`, optional `none` option |
+| Discrete bars and exact values | `plot/datum`; expandable data table |
+| Parameter-dependent results | Play declarations, controls, `chart/bar/line`, `pie`, `table` |
+| Article text and useful HTML | `markdown` and `html` content islands |
+| Independent executable illustration | Play `sandbox` with literal html/css/js; isolated offline iframe |
 
-## Shared tokens
+The authoritative, demand-loaded catalog is `npx garden ui schema`: actual semantic fields, Play props/defaults/child contracts, icon names, safe HTML tags/attributes/CSS properties. `npx garden ui prompt` adds working recipes. `styleReference` also extracts current font/layout declarations, selectors, responsive conditions and source order from the installed stylesheets; it reports source defaults, not universal computed values. These are generated from the validators and actual styles; do not maintain a second exhaustive tag list. Static layout normalization is not a universal HTML/CSS API: inspect the normalized tree and output because some unsupported static layout attributes are ignored. Semantic unknown fields fail validation.
 
-Write once; most layout tags accept them. Colors come only from Garden theme variables (Claude paper).
+See the executable [Compose active-hours chart](/garden/en/components/compose#ui-compose-chart-active-hours).
 
-| Token | Values |
-| :--- | :--- |
-| `padding` / `gap` | `0`–`4` (4px × n) |
-| `background` | `surface` `surface-secondary` `surface-accent` `surface-tip` `surface-muted` `transparent` |
-| `radius` | `none` `sm` `md` `lg` `xl` `full` |
-| `border` | `subtle` `strong`/`true` `none`/`false` |
-| `size` | `sm` `md` `lg` `xl` |
-| `tone` | `plain` `accent` `tip` `muted` (and callout `note`/`warn`) |
-| `align` | `start` `center` `end` `stretch` |
-| `justify` (row) | `start` `center` `end` `between` `around` |
-| `wrap` (row) | `wrap` `nowrap` |
+## Relationships → hierarchy → layout → style → actual output
 
-## High-traffic attributes
+First identify what belongs together. A heading and all its paragraphs must share a container. Next choose columns and proportions, then alignments and typography. Only then add surfaces and decorative details.
 
-### `box` / `card`
+A static `row` wraps by default. Its direct text/title/stack/card children share available width (`flex: 1 1 0`), whereas an icon is content-sized. A heading placed directly in that row is a sibling column, not the heading of a paragraph below the row. `align="center"` on a row changes more than vertical placement: theme rules also center text. A centered stack propagates text alignment. For an editorial list use explicit start alignment on children of a shared right-hand group; do not center each title independently.
 
-| Attr | Notes |
-| :--- | :--- |
-| `frame` | `card` (default) `band` `pill` `text` — or sugar tags `<band>` / `<pill>` |
-| `padding` `gap` `radius` `border` `background` `size` `align` `tone` `id` `mark` | shared tokens; `mark="shield"` draws a shield glyph |
+Direct `row > stack` has 12px top padding in the current theme. A `group` is a width:100%, min-width:0 vertical container that shrinks beside the fixed icon and reads gap without that contextual padding; use it when icon and heading must begin on the same top line. Explicit `align="start"` survives normalization and emits data-align.
 
-### `row` / `stack` / `grid`
+Nested paragraphs need separate `text` leaves or an article content island. Two unrelated top-level leaves do not establish a shared right column. Put a full-width divider **between rows**, not inside the right text container, if the rule must span the icon column too. `divider` and `separator` are real primitives, not text lines.
 
-| Attr | Notes |
-| :--- | :--- |
-| `gap` `align` | shared |
-| `justify` `wrap` | `row` only |
-| `cols` | `grid` only, 1–6 |
-| `span` | `grid-item` only, 1–6 |
+```garden compose
+<figure frame="none">
+<row wrap="nowrap" align="start" gap="4">
+  <icon name="book-open" size="xl"/>
+  <group gap="2">
+    <title align="start">Test heading — not article content</title>
+    <text align="start">Explicit test paragraph: the heading and this body share the same right column. Keep the author's complete text; do not shrink or summarize it to fit.</text>
+    <text align="start">A second independent test paragraph stays in that column.</text>
+  </group>
+</row>
+<divider/>
+<row wrap="nowrap" align="start" gap="4">
+  <icon name="users" size="xl"/>
+  <group gap="2">
+    <title align="start">Second test heading</title>
+    <text align="start">Another test body, aligned with its heading rather than spanning the icon column.</text>
+  </group>
+</row>
+</figure>
+```
 
-### `text` / `title` / `caption`
+For a native editorial list the same relationship is expressed with `icon-list` containing `entry icon="…" title="…"`, and multiple `text` children per entry. Native paragraph children are lowered to text strings: their nested text size/alignment/layout properties are not carried into the native scene. Use a generic layout with text size controls for such precision; do not assume identical nested styling contracts. Native scenes preserve the app's keyboard/selection/detail/file-preview behavior when rendered by the Garden article host. A standalone static export is a readable fallback, not an identical interactive host.
 
-| Attr | Notes |
-| :--- | :--- |
-| `size` `align` | shared |
-| `tone` | `text`: `plain` `muted` `accent` `tip`. `caption` forces muted. |
+## Typography and complete-theme context
 
-### `icon`
+Default body text inherits the **actual article's** family, size and line height. There is no universal pixel baseline. This includes ordinary static text, list bodies and native readable prose; changing the article typography configuration must propagate. Semantic headings, graph labels, values, captions and controls intentionally retain their hierarchy.
 
-| Attr | Notes |
+| Element/context | Actual source rule / intentional variation |
 | :--- | :--- |
-| `name` | required; must be in the [icon catalog](/garden/en/reference/compose-icons) |
-| `size` | `sm` `md` `lg` `xl` |
-| `inline` | sit with surrounding text |
+| Static `text` and `title` | Inherit body size; title weight 600, line height 1.4. `size="sm"` .875em; `lg` 1.125em; `xl` 1.25em. `md` keeps the baseline. |
+| Static outer figure title/caption | Source defaults 18px/14px, not ordinary body; actual cascade still matters. |
+| Static inline caption | Own semantic style; `sm` 11px, `lg` 16px. Not a body substitute. |
+| Native icon-list entry title/body | Title weight 600; body inherits article. Group heading uses `--fs-small`. |
+| Native choice value | 22px; narrow rule 20px. Option body inherits article. |
+| Native relation ring | Compact/context-dependent labels and line clamps; detail prose inherits article. Do not treat a ring label as a long paragraph. |
+| Play components | Query schema defaults and complete theme. Their controls/KPI/graph semantics are not globally changed to body size. |
 
-## Tag catalog
+Use explicit variation only for a meaningful hierarchy. Never shrink body text globally to fit a screenshot or discard facts to avoid wrapping. Inspect actual computed styles with globals → tokens → article theme → shell in the real order, on desktop and narrow widths; base component CSS alone does not prove the final result.
 
-One mini sample per group, then a one-line table for every tag. No per-tag essays.
+## Markdown, safe HTML, and execution
 
-### Layout
+`text`, `title` and captions are inline contexts: `**bold**`, `_emphasis_`, backticks, `[links](https://example.com)`, `~~strike~~` and safe inline HTML such as `<u>underline</u>`. `<u>` is HTML, not standard Markdown.
 
-```garden compose
-<row gap={2}><box padding={2} radius="md" border="subtle"><title size="sm">A</title></box><box padding={2} radius="md" background="surface-accent"><title size="sm">B</title></box></row>
-```
-
-| Tag | Purpose |
-| :--- | :--- |
-| `box` | Generic container; padding / gap / background / radius |
-| `card` | Alias of box as a card face |
-| `stack` | Vertical stack |
-| `row` | Horizontal row |
-| `columns` | Multi-column row (wrap by default) |
-| `grid` | Equal grid; cols 1–6 |
-| `grid-item` | Grid cell; span columns |
-| `group` | Semantic group |
-| `field` | Form-field group |
-| `header` | Header region |
-| `footer` | Footer region |
-| `figure` | Figure region |
-| `prose` | Prose region |
-| `divider` | Divider (self-closing) |
-| `separator` | Alias of divider |
-| `spacer` | Empty spacer |
-| `band` | Full-width band (box frame=band) |
-| `pill` | Pill (box frame=pill) |
-
-### Text
+Use `markdown` or `html` islands for full paragraphs, lists, headings, blockquotes, code blocks, tables, images, details/summary and other allowlisted article content. The islands share the article Markdown/GFM and safe-HTML renderer; they are not arbitrary component trees. Static text outside islands is a lightweight layout shorthand, **not** the whole article block grammar. Play islands are literal content, not interpolated expressions. Keep state and expressions in Play component nodes outside them.
 
 ```garden compose
-<stack gap={1}><title size="sm">Title</title><text size="sm">Body</text><caption size="sm">Caption</caption><badge>badge</badge></stack>
-```
+<figure frame="none">
+<markdown>
+### Explicit test content
 
-| Tag | Purpose |
-| :--- | :--- |
-| `title` | Short title |
-| `text` | Body text |
-| `caption` | Caption (muted by default) |
-| `label` | Control label |
-| `badge` | Pill badge |
-| `kpi` | Metric (self-closing) |
-| `stat` | Alias of kpi |
-| `icon` | Named stroke icon (self-closing) |
-| `callout` | Callout strip |
-| `kbd` | Keyboard keycap |
-| `link` | Inline link |
-| `intent` | Author intent (not drawn) |
-
-### Controls
+**Bold**, _emphasis_, `code`, [link](https://example.com), ~~strike~~ and <u>underline</u>.
 
-```garden compose
-<stack gap={2}><row gap={2}><avatar label="A" size="sm"/><badge>ok</badge><kbd>⌘K</kbd></row><list><list-item>One</list-item><list-item>Two</list-item></list><progress value={40} max={100} label="40%"/></stack>
+- A full Markdown list
+- Another test item
+
+<details><summary>Safe HTML details</summary><p>Useful article HTML can coexist with Markdown.</p></details>
+</markdown>
+</figure>
 ```
 
-| Tag | Purpose |
-| :--- | :--- |
-| `button` | Button snapshot |
-| `slider` | Slider snapshot / play |
-| `progress` | Progress bar |
-| `meter` | Meter bar |
-| `checkbox` | Checkbox snapshot |
-| `radio` | Radio snapshot |
-| `toggle` | Toggle snapshot |
-| `switch` | Alias of toggle |
-| `input` | Text input snapshot |
-| `textarea` | Textarea snapshot |
-| `select` | Select snapshot |
-| `tabs` | Tabs container |
-| `tab` | One tab |
-| `list` | List |
-| `list-item` | List item |
-| `table` | Table |
-| `thead` | Table head |
-| `tbody` | Table body |
-| `tr` | Table row |
-| `th` | Header cell |
-| `td` | Data cell |
-| `image` | Image |
-| `avatar` | Avatar placeholder |
-| `empty` | Empty state |
-| `option` | Segment option snapshot |
-
-### Connectors
+Safe HTML supports allowlisted local `style` properties, including useful layout and typography; inspect the generated schema for the actual set. Unsupported tags/properties, events, unsafe URLs, executable scripts and network CSS functions report diagnostics. Do not expand the article allowlist into arbitrary execution. An intentional executable demo uses `sandbox` inside the **same Compose entry**, with literal html/css/js and no parent origin access. Sandbox layout is its own document, not inherited article prose.
 
-```garden compose
-<stack align="center" gap={1}><pill>Start</pill><arrow dir="down"/><band tone="accent" align="center"><title size="sm">Hub</title></band></stack>
-```
+## Verification levels
 
-| Tag | Purpose |
-| :--- | :--- |
-| `arrow` | Arrow |
-| `fan` | Downward fan arrows |
-| `join` | V-shaped join |
-| `lanes` | Swimlanes |
-| `actor` | Lane actor |
-| `message` | Lane message |
-| `steps` | Steps container |
-| `step` | One step |
-| `note` | Step note |
-| `compare` | Compare cards |
-| `item` | Compare item |
-| `code` | Code snapshot |
-| `pre` | Preformatted text |
-
-
-## Chart examples
-
-Play-level chart samples (static eight bars, fusion weight slider) live on [Diagrams · compose](/garden/en/components/compose#ui-compose-chart-active-hours).
-
-## Limits
-
-- Nesting ~10 levels / ~220 nodes.
-- Uncompiled prose-only fences report `compose-uncompiled`.
-- Play path (`{@body}`, `{#if}`, …) is documented in the repo `docs/compose-dil.md`; static fences render default-state snapshots for control tags.
+1. Run `npx garden ui check <file>` (and `npx garden check <file>` for real file paths). Preserve original text/resources and inspect diagnostics.
+2. Parse/render the actual scene; confirm accepted properties survive normalization and meaningful content appears.
+3. Inspect the complete-theme render: icon rail fixed, heading and **all** paragraphs share the same right edge/left edge, no centered headings or full-width body beneath a detached icon row, dividers outside rows, no unintended cards/arrows, no horizontal overflow.
+4. Check desktop and narrow screenshots plus geometry/computed styles; exercise choices, relations, file previews, state updates and sandbox behavior when used.
+5. A hand-authored passing scene proves engine capability, not that an independent model reliably produces it from a short prompt. Report those claims separately.