hd-garden 0.13.2 → 0.14.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (220) hide show
  1. package/.agents/skills/garden-compose/SKILL.md +24 -0
  2. package/.agents/skills/garden-compose/references/colors.md +11 -0
  3. package/.agents/skills/garden-compose/references/composition-patterns.md +162 -0
  4. package/.agents/skills/garden-compose/references/examples.md +55 -0
  5. package/.agents/skills/garden-compose/references/frames.md +7 -0
  6. package/.agents/skills/garden-compose/references/layout-recipes.md +84 -0
  7. package/.agents/skills/garden-compose/references/rendering-model.md +120 -0
  8. package/.agents/skills/garden-compose/references/static-play.md +19 -0
  9. package/.agents/skills/garden-compose/references/visual-selection.md +38 -0
  10. package/.agents/skills/garden-compose/references/workflow.md +27 -0
  11. package/.agents/skills/garden-compose/scripts/_cli.mjs +12 -0
  12. package/.agents/skills/garden-compose/scripts/apply.mjs +2 -0
  13. package/.agents/skills/garden-compose/scripts/check.mjs +2 -0
  14. package/.agents/skills/garden-compose/scripts/prompt.mjs +2 -0
  15. package/.agents/skills/garden-compose/scripts/scan.mjs +2 -0
  16. package/.agents/skills/garden-post-review/SKILL.md +5 -16
  17. package/Makefile +12 -3
  18. package/README.en.md +10 -5
  19. package/README.md +10 -5
  20. package/app/admin/preview/[...path]/page.tsx +3 -15
  21. package/app/api/admin/ui/blocks/route.ts +1 -1
  22. package/app/components/AdminUiPanels.tsx +6 -3
  23. package/app/components/GardenContentGuide.tsx +7 -8
  24. package/app/components/MarkdownArticle.tsx +6 -47
  25. package/app/components/TableOfContents.tsx +0 -1
  26. package/app/components/UiStudio.tsx +29 -32
  27. package/app/components/garden/AuthorRich.tsx +5 -0
  28. package/app/components/garden/ComposePreview.tsx +9 -0
  29. package/app/components/garden/GardenBlock.tsx +12 -10
  30. package/app/components/garden/GardenFile.tsx +1 -1
  31. package/app/components/garden/blocks.tsx +9 -197
  32. package/app/components/garden/file-icons.tsx +1 -1
  33. package/app/components/garden/patterns.tsx +7 -65
  34. package/app/lib/content.ts +5 -22
  35. package/app/lib/heading-number.ts +2 -7
  36. package/app/lib/rehype-garden-blocks.mjs +30 -0
  37. package/app/lib/remark-garden.mjs +0 -4
  38. package/app/lib/ui-model.ts +8 -9
  39. package/app/styles/a2.css +17 -1
  40. package/bin/garden.mjs +43 -36
  41. package/docs/handbook/ai-writing.md +19 -22
  42. package/docs/handbook/components/compose.md +16 -7
  43. package/docs/handbook/components/image.md +1 -1
  44. package/docs/handbook/components/link-card.md +2 -2
  45. package/docs/handbook/components.md +5 -213
  46. package/docs/handbook/deploy.md +11 -0
  47. package/docs/handbook/en/ai-writing.md +17 -20
  48. package/docs/handbook/en/components/compose.md +15 -6
  49. package/docs/handbook/en/components/image.md +1 -1
  50. package/docs/handbook/en/components/link-card.md +2 -2
  51. package/docs/handbook/en/components.md +7 -215
  52. package/docs/handbook/en/deploy.md +11 -0
  53. package/docs/handbook/en/index.md +29 -53
  54. package/docs/handbook/en/reference/compose.md +77 -148
  55. package/docs/handbook/en/reference.md +6 -22
  56. package/docs/handbook/en/start.md +1 -1
  57. package/docs/handbook/en/workflow.md +20 -16
  58. package/docs/handbook/en/writing.md +2 -2
  59. package/docs/handbook/index.md +26 -47
  60. package/docs/handbook/reference/compose.md +79 -148
  61. package/docs/handbook/reference.md +6 -22
  62. package/docs/handbook/start.md +1 -1
  63. package/docs/handbook/workflow.md +20 -16
  64. package/docs/handbook/writing.md +2 -2
  65. package/editors/dist/typora/main.js +324 -330
  66. package/editors/dist/typora/style.css +4299 -11
  67. package/editors/dist/vscode/garden-ui-0.1.1.vsix +0 -0
  68. package/eslint.config.mjs +3 -0
  69. package/package.json +3 -2
  70. package/public/images/compose-resources/resource-015b41eb0f32.svg +1 -0
  71. package/public/images/compose-resources/resource-ecee6b47f015.svg +1 -0
  72. package/public/images/compose-resources/resource-fd51121b5e8c.svg +1 -0
  73. package/scripts/build-content.mjs +59 -141
  74. package/scripts/build-ui-preview.mjs +7 -5
  75. package/scripts/check-post.mjs +8 -104
  76. package/scripts/check-site.mjs +80 -0
  77. package/scripts/compose-style-reference.mjs +22 -0
  78. package/scripts/dev-server.mjs +114 -0
  79. package/scripts/editor-preview-css.mjs +14 -0
  80. package/scripts/file-preview.mjs +1 -1
  81. package/scripts/file-sizes.mjs +7 -7
  82. package/scripts/generated-cache.mjs +36 -0
  83. package/scripts/handbook-facts.mjs +10 -3
  84. package/scripts/image-sizes.mjs +6 -12
  85. package/scripts/link-assets.mjs +35 -10
  86. package/scripts/managed-skills.mjs +56 -0
  87. package/scripts/prepare-pages-output.mjs +1 -1
  88. package/scripts/site-guide.mjs +19 -0
  89. package/scripts/ui-cli.mjs +26 -33
  90. package/templates/garden-blocks.md +4 -180
  91. package/templates/garden-snippets.plist +2 -183
  92. package/templates/site/AGENTS.en.md +89 -0
  93. package/templates/site/AGENTS.md +72 -0
  94. package/templates/site/Makefile +12 -3
  95. package/templates/site/Makefile.en +12 -3
  96. package/templates/site/README.en.md +8 -1
  97. package/templates/site/README.md +8 -1
  98. package/templates/skills-en/garden-compose/SKILL.md +24 -0
  99. package/templates/skills-en/garden-post-review/SKILL.md +5 -16
  100. package/templates/workflows/pages.en.yml +11 -0
  101. package/templates/workflows/pages.yml +11 -0
  102. package/ui/compose/compose.css +54 -14
  103. package/ui/compose/contracts.mjs +16 -0
  104. package/ui/compose/dil.mjs +109 -48
  105. package/ui/compose/distribution.mjs +7 -0
  106. package/ui/compose/features.mjs +90 -0
  107. package/ui/compose/icons.mjs +8 -0
  108. package/ui/compose/index.mjs +2 -0
  109. package/ui/compose/inspect.mjs +11 -0
  110. package/ui/compose/markup.mjs +80 -23
  111. package/ui/compose/preview.mjs +13 -0
  112. package/ui/compose/prompt-catalog.mjs +15 -3
  113. package/ui/compose/render.mjs +46 -11
  114. package/ui/compose/scenes.mjs +10 -0
  115. package/ui/core/apply.mjs +12 -45
  116. package/ui/core/catalog.mjs +22 -32
  117. package/ui/core/cli-locale.mjs +8 -18
  118. package/ui/core/color.mjs +34 -0
  119. package/ui/core/compile.mjs +1 -8
  120. package/ui/core/demos.mjs +138 -108
  121. package/ui/core/fence.mjs +14 -70
  122. package/ui/core/fix-prompt.mjs +1 -3
  123. package/ui/core/garden-fence.mjs +3 -63
  124. package/ui/core/index.mjs +3 -5
  125. package/ui/core/parse.mjs +22 -8
  126. package/ui/core/scan.mjs +31 -43
  127. package/ui/core/starters.mjs +3 -3
  128. package/ui/core/static.mjs +36 -6
  129. package/ui/core/transform.mjs +64 -149
  130. package/ui/core/validate.mjs +20 -9
  131. package/ui/garden/article-content.mjs +98 -0
  132. package/ui/garden/catalog.mjs +21 -427
  133. package/ui/garden/check.mjs +18 -60
  134. package/ui/garden/file-block.mjs +1 -1
  135. package/ui/garden/file-paths.mjs +8 -6
  136. package/ui/garden/markdown-syntax.mjs +1 -1
  137. package/ui/garden/parse.mjs +19 -182
  138. package/ui/garden/relations.mjs +1 -1
  139. package/ui/garden/snippets.mjs +12 -153
  140. package/ui/garden/source-icon.mjs +17 -9
  141. package/ui/garden/word-count.mjs +16 -85
  142. package/ui/index.mjs +1 -5
  143. package/ui/preview/dist/garden-ui.css +4300 -11
  144. package/ui/preview/dist/garden-ui.esm.js +446 -418
  145. package/ui/preview/dist/garden-ui.iife.js +446 -418
  146. package/ui/preview/index.tsx +31 -98
  147. package/ui/preview/site-config.ts +4 -0
  148. package/ui/prompt/build.mjs +1 -4
  149. package/ui/prompt/recipes/code-walkthrough.md +17 -12
  150. package/ui/prompt/recipes/compare.md +14 -10
  151. package/ui/prompt/recipes/compose.md +3 -3
  152. package/ui/prompt/recipes/converter.md +17 -14
  153. package/ui/prompt/recipes/data-chart.md +9 -8
  154. package/ui/prompt/recipes/inspect-grid.md +9 -8
  155. package/ui/prompt/recipes/param-bench.md +17 -12
  156. package/ui/prompt/recipes/plan.md +4 -3
  157. package/ui/prompt/recipes/stepper.md +18 -16
  158. package/ui/prompt/recipes/trace.md +20 -18
  159. package/ui/prompt/rules.md +26 -133
  160. package/ui/prompt/studio.md +3 -18
  161. package/ui/react/CatalogPage.tsx +19 -21
  162. package/ui/react/recipes.ts +3 -3
  163. package/ui/react/runtime.tsx +23 -2
  164. package/ui/react/ui.css +17 -11
  165. package/vite.config.ts +46 -8
  166. package/.agents/skills/garden-interactive-chart/SKILL.md +0 -84
  167. package/.agents/skills/garden-interactive-chart/references/shell.html +0 -49
  168. package/.agents/skills/garden-interactive-chart/references/style.md +0 -61
  169. package/.agents/skills/garden-ui/SKILL.md +0 -125
  170. package/app/components/UiBlock.tsx +0 -23
  171. package/app/components/WidgetChart.tsx +0 -224
  172. package/app/lib/generated-content.ts +0 -385
  173. package/docs/handbook/components/card.md +0 -67
  174. package/docs/handbook/components/chart.md +0 -38
  175. package/docs/handbook/components/choice.md +0 -42
  176. package/docs/handbook/components/compare.md +0 -53
  177. package/docs/handbook/components/file.md +0 -29
  178. package/docs/handbook/components/html.md +0 -49
  179. package/docs/handbook/components/interactive.md +0 -48
  180. package/docs/handbook/components/list.md +0 -65
  181. package/docs/handbook/components/relations.md +0 -95
  182. package/docs/handbook/components/stat.md +0 -39
  183. package/docs/handbook/components/timeline.md +0 -37
  184. package/docs/handbook/en/components/card.md +0 -67
  185. package/docs/handbook/en/components/chart.md +0 -38
  186. package/docs/handbook/en/components/choice.md +0 -42
  187. package/docs/handbook/en/components/compare.md +0 -53
  188. package/docs/handbook/en/components/file.md +0 -29
  189. package/docs/handbook/en/components/html.md +0 -49
  190. package/docs/handbook/en/components/interactive.md +0 -44
  191. package/docs/handbook/en/components/list.md +0 -65
  192. package/docs/handbook/en/components/relations.md +0 -95
  193. package/docs/handbook/en/components/stat.md +0 -39
  194. package/docs/handbook/en/components/timeline.md +0 -37
  195. package/docs/handbook/en/reference/card.md +0 -85
  196. package/docs/handbook/en/reference/chart.md +0 -68
  197. package/docs/handbook/en/reference/choice.md +0 -69
  198. package/docs/handbook/en/reference/compare.md +0 -59
  199. package/docs/handbook/en/reference/file.md +0 -50
  200. package/docs/handbook/en/reference/html.md +0 -62
  201. package/docs/handbook/en/reference/interactive.md +0 -71
  202. package/docs/handbook/en/reference/list.md +0 -72
  203. package/docs/handbook/en/reference/relations.md +0 -113
  204. package/docs/handbook/en/reference/stat.md +0 -60
  205. package/docs/handbook/en/reference/timeline.md +0 -56
  206. package/docs/handbook/reference/card.md +0 -85
  207. package/docs/handbook/reference/chart.md +0 -68
  208. package/docs/handbook/reference/choice.md +0 -69
  209. package/docs/handbook/reference/compare.md +0 -59
  210. package/docs/handbook/reference/file.md +0 -50
  211. package/docs/handbook/reference/html.md +0 -62
  212. package/docs/handbook/reference/interactive.md +0 -71
  213. package/docs/handbook/reference/list.md +0 -72
  214. package/docs/handbook/reference/relations.md +0 -113
  215. package/docs/handbook/reference/stat.md +0 -60
  216. package/docs/handbook/reference/timeline.md +0 -56
  217. package/templates/skills-en/garden-interactive-chart/SKILL.md +0 -84
  218. package/templates/skills-en/garden-interactive-chart/references/shell.html +0 -49
  219. package/templates/skills-en/garden-interactive-chart/references/style.md +0 -61
  220. package/templates/skills-en/garden-ui/SKILL.md +0 -125
@@ -13,24 +13,23 @@ You do not need to memorize component tags to add charts, metrics, or interactiv
13
13
 
14
14
  ## 1. Write a One-sentence Idea
15
15
 
16
- Place an unnamed `garden` fence where the component belongs and state what the reader should do and see, without naming a component:
16
+ Place a `garden compose` fence where the component belongs and state what the reader should do and see, without naming a component:
17
17
 
18
18
  ````markdown
19
- ```garden
19
+ ```garden compose
20
20
  Let the reader drag daily word count and writing days per week to see how many weeks an 8,000-word article takes.
21
21
  ```
22
22
  ````
23
23
 
24
- Draft posts (`draft: true`) may keep uncompiled idea fences; in non-draft posts, both `npx garden ui check` and `npx garden check` report a `garden-idea` error. Depending on the content, the Agent compiles the idea into a built-in component (`garden compose`, `card`, `stat`, `compare`, and others) or replaces it with plain prose when a paragraph is clearer.
24
+ Uncompiled requests use the same `garden compose` entry. Both `npx garden ui check` and `npx garden check` report `compose-uncompiled`, including in drafts. The Agent composes prose, resources, graphics and interactions inside Compose, or replaces the request with plain prose when that is clearer.
25
25
 
26
- ## 2. Three Bundled Skills
26
+ ## 2. Two Bundled Skills
27
27
 
28
- Three skills live in `.agents/skills/` at the root of the site repository. `npx hd-garden init` installs them when creating a site, the first `npx garden sync` or `npx garden dev` fills in any missing skill files, and `npx garden skill` reinstalls them on demand.
28
+ Two skills live in `.agents/skills/` at the root of the site repository. `npx hd-garden init` installs them when creating a site, the first `npx garden sync` or `npx garden dev` recursively updates managed skill files, backing up local edits under `.garden/skill-backups/`, and `npx garden skill` reinstalls them on demand.
29
29
 
30
30
  | Skill Name | Example Trigger Prompt | What It Does |
31
31
  | :--- | :--- | :--- |
32
- | `garden-ui` | "Compile this post: content/posts/writing-pace.md", "Recompile writing-pace", or pasting a fix prompt | Scans `uncompiled`, `stale`, and `error` blocks, generates components, and writes them back via `npx garden ui apply`; asking where interactive blocks fit runs read-only suggestion mode and returns up to 5 ready-to-paste idea fences |
33
- | `garden-interactive-chart` | Canvas animations or simulations beyond the built-in component catalog | Writes a standalone `.html` file inside the post's sidecar directory and embeds it in the post with a `garden html` fence |
32
+ | `garden-compose` | "Compile this post: content/posts/writing-pace.md", "Recompile writing-pace", or pasting a fix prompt | Scans `uncompiled` and `error` blocks, generates components, and writes them back via `npx garden ui apply`; asking where interactive blocks fit runs read-only suggestion mode and returns up to 5 ready-to-paste idea fences |
34
33
  | `garden-post-review` | "Review post: content/posts/writing-pace.md" | Fixes structural errors reported by `npx garden check`, repairs interactive blocks against the chart rules, and reads the full post to offer editorial suggestions without rewriting prose |
35
34
 
36
35
  ## 3. `garden ui` Subcommands and Post Checks
@@ -49,19 +48,17 @@ Authors and Agents run the same `garden ui` subcommands; when an idea fence has
49
48
 
50
49
  ## 4. Pre-commit Hook and Fix Prompts
51
50
 
52
- On the first `npx garden sync` or `npx garden dev` run, Garden writes `exec npx --no-install garden ui check --staged --quiet` to `.git/hooks/pre-commit` (if a custom hook already exists, it leaves the file untouched and prints the line to add). `--staged` reads staged content directly via `git show :<path>` and, on failure, prints the line numbers, diagnostic codes, and a fix prompt:
51
+ On the first `npx garden sync` or `npx garden dev` run, Garden writes `exec npx --no-install garden ui check --staged --quiet` to `.git/hooks/pre-commit` (if a custom hook already exists, it leaves the file untouched and prints the line to add). `--staged` reads staged content directly via `git show :<path>` and, on failure, prints line numbers, diagnostic codes, and a short instruction to load the project skill:
53
52
 
54
53
  ```console
55
- content/posts/writing-pace.md:9 - garden-idea uncompiled idea remaining
54
+ content/posts/writing-pace.md:9 - compose-uncompiled uncompiled compose idea remaining
56
55
 
57
- ──────────────────────── Fix prompt for AI ────────────────────────
58
- Handle the Garden post blocks listed below: compile uncompiled ideas, and fix interactive blocks that have errors.
59
- ……
56
+ Use garden-compose skill (.agents/skills/garden-compose/SKILL.md), fix the failing blocks, then recheck.
60
57
  ```
61
58
 
62
- - The prompt is written to `.garden/ui-fix-prompt.md` and copied to the clipboard when `pbcopy`, `wl-copy`, `xclip`, `xsel`, or `clip` is available; pass `--no-copy` or set `GARDEN_UI_NO_COPY=1` to disable clipboard copying.
63
- - When pasting into a web chat that cannot read your local repository, run `npx garden ui check <post.md> --standalone` to append the full `npx garden ui prompt` rules to the prompt (including source fences for up to 10 failing blocks).
64
- - A misspelled tag inside an interactive block (such as `<Slidr>` instead of `<Slider>`) reports `ui-component` with its exact line number; to commit anyway, run `git commit --no-verify`.
59
+ - Defaults show file/line/error diagnostics and a short instruction to load the project `garden-compose` skill. No file is written, no clipboard access occurs, and no model is called. Existing prompt files are untouched.
60
+ - Only when a self-contained export is required, run `npx garden ui check <post.md> --out .garden/export.md --standalone`. `--standalone` enriches that explicit export; alone it does not create a file.
61
+ - A misspelled tag inside an interactive block (such as `<Slidr>` instead of `<Slider>`) reports `ui-component` with its exact line number.
65
62
  - Run `npx garden hooks` to reinstall the hook (pass `--force` to overwrite an existing hook), or set `GARDEN_SKIP_HOOKS=1` to skip automatic hook installation.
66
63
 
67
64
  ## 5. Generate a Code Diff from One Sentence
@@ -75,12 +72,12 @@ pages:
75
72
  title: "Write in Markdown | Push to Update the Site"
76
73
  ```
77
74
 
78
- ```garden
75
+ ```garden compose
79
76
  Compared with the previous version: split the title into two lines with " | " instead of a period and newline.
80
77
  ```
81
78
  ````
82
79
 
83
- Following the `garden-ui` skill, the Agent replaces that idea fence with a `diff` fence right below the code block. The page merges the adjacent code and `diff` fences into a single code frame with a toggle between the full code and the diff; see [Writing Posts & Thoughts](/garden/en/writing) for the hand-written `diff` format.
80
+ Following the `garden-compose` skill, the Agent replaces that idea fence with a `diff` fence right below the code block. The page merges the adjacent code and `diff` fences into a single code frame with a toggle between the full code and the diff; see [Writing Posts & Thoughts](/garden/en/writing) for the hand-written `diff` format.
84
81
 
85
82
  ## 6. Insert, Preview, and Compile from the Editor
86
83
 
@@ -95,10 +92,10 @@ npx garden editors install --typora
95
92
 
96
93
  A component then takes four steps:
97
94
 
98
- 1. **Insert an idea.** Where the component should go, run the Garden insert command (`Cmd+Alt+I` on macOS, `Ctrl+Alt+I` on Windows and Linux in VS Code / Cursor). In Typora, type `/` and choose `/garden` to open a picker with a small preview image on each row; the command shortcut is `Ctrl+Alt+I` on Windows and Linux, and macOS needs a shortcut recorded under Settings, Keyboard Shortcuts. The insertion is a plain `garden` fence whose body tells the `garden-ui` skill which component to compile and which facts to include.
95
+ 1. **Insert an idea.** Where the component should go, run the Garden insert command (`Cmd+Alt+I` on macOS, `Ctrl+Alt+I` on Windows and Linux in VS Code / Cursor). In Typora, type `/` and choose `/garden` to open a picker with a small preview image on each row; the command shortcut is `Ctrl+Alt+I` on Windows and Linux, and macOS needs a shortcut recorded under Settings, Keyboard Shortcuts. The insertion is a plain `garden` fence whose body tells the `garden-compose` skill which component to compile and which facts to include.
99
96
  2. **Preview.** Open the Markdown preview, or in Typora move the cursor out of the fence. An `intent` block shows as an idea card. After the skill writes a `ui` block, the preview matches the blog. VS Code / Cursor also report errors in Problems and in the CodeLens above the block.
100
97
  3. **Open the catalog.** Use the catalog command, or run `npx garden ui catalog` and open `.garden/ui-catalog.html`. Starting from a recipe inserts it at the cursor when you already know which component you want.
101
- 4. **Compile.** Copy the compile prompt. On an English site the clipboard text is `Compile this post:` plus the post path. Paste it to the `garden-ui` skill. The Agent locates the block with `npx garden ui scan`, reads the rules with `npx garden ui prompt`, and writes it back with `npx garden ui apply`. The plugin does not call a model.
98
+ 4. **Compile.** Copy the compile prompt. On an English site the clipboard text is `Compile this post:` plus the post path. Paste it to the `garden-compose` skill. The Agent locates the block with `npx garden ui scan`, reads the rules with `npx garden ui prompt`, and writes it back with `npx garden ui apply`. The plugin does not call a model.
102
99
 
103
100
  **Typora prerequisite.** Install [typora-community-plugin](https://github.com/typora-community-plugin/typora-community-plugin/blob/main/docs/en-us/user-guide/1a-installation.md) first. `npx garden editors install --typora` copies the plugin to `~/.typora/community-plugins/plugins/hedon954.garden-intelligent-ui/`. On macOS it also copies to `~/Library/Application Support/abnerworks.Typora/plugins/plugins/hedon954.garden-intelligent-ui/`. Enable Garden Intelligent UI under Settings, Installed plugins. A Typora upgrade overwrites the community framework; reinstall the framework, then enable the plugin again. If `code` or `cursor` is not on `PATH`, use Install from VSIX in the Extensions view and select the file under `.garden/editors/vscode/`. Install details are in [Checks & Shortcuts](/garden/en/workflow).
104
101
 
@@ -107,7 +104,7 @@ A component then takes four steps:
107
104
  When writing components by hand without AI, you can use the templates and snippets shipped in the package:
108
105
 
109
106
  - Every draft created by `make new` includes an HTML comment at the bottom with copy-ready examples for idea fences and the built-in components; delete the comment whenever you are done.
110
- - `templates/garden-blocks.md` lists `when` / `whenNot` guidance and copyable templates for every block; macOS, Typora, and Alfred users can import `templates/garden-snippets.plist` to expand `;gidea`, `;gcard`, `;gstat`, `;gcompare`, `;gtimeline`, `;gchart`, `;gcompose`, `;ghtml`, `;ginteractive`, `;gfile`, `;grel`, `;glist`, and `;gchoice`. `;gcompose` expands to a `garden compose` fence with one sentence.
107
+ - `templates/garden-blocks.md` supplies examples for the single Compose entry. macOS, Typora and Alfred users can import `templates/garden-snippets.plist` and expand `;gcompose` to a Compose fence containing one author sentence.
111
108
  - Editor plugin usage is in the previous section. `npx garden ui catalog` writes an offline component catalog at `.garden/ui-catalog.html`.
112
109
 
113
110
  ## 8. Optional Standalone Admin
@@ -1,17 +1,19 @@
1
1
  ---
2
- title: Diagrams (compose)
3
- navTitle: Diagrams
4
- description: Write a short plain-language structure; AI compiles it into a static diagram.
2
+ title: Content, layout, and interactions (compose)
3
+ navTitle: Compose
4
+ description: Combine article content, layout, resources, and interactions through one author entry.
5
5
  section: components
6
6
  order: 36
7
7
  badge: compose
8
8
  ---
9
9
 
10
- To draw a structure diagram in a post, type `/garden` and pick **compose (idea)**. That inserts a `garden compose` fence. Write the structure in plain language, then ask the AI to compile the post. It keeps your words in `<intent>` and builds the diagram from Markdown leaves plus catalog tags.
10
+ `garden compose` is the single Garden author entry. Inside it, combine Markdown, safe HTML content islands, layout, resources, files, relations, selectable cards, and Play interactions. See the [component reference](/garden/en/reference/compose) for capabilities, content boundaries, and contextual defaults; `npx garden ui schema` is authoritative for supported fields.
11
+
12
+ To ask AI for a structure diagram, type `/garden` and pick **compose (idea)**. That inserts a `garden compose` fence. Write the structure in plain language, then ask the AI to compile the post. It keeps your words in `<intent>` and builds the diagram from Markdown leaves plus catalog tags.
11
13
 
12
14
  ## How to write
13
15
 
14
- Describe the structure readers should see. Do not prescribe styles.
16
+ Describe the relationships and hierarchy readers should see before choosing layout and necessary styles. You can also write components directly; do not assume every component accepts arbitrary HTML/CSS properties.
15
17
 
16
18
  Cover four things:
17
19
 
@@ -20,7 +22,7 @@ Cover four things:
20
22
  - **What connects to what**: who reaches whom, fans out, or joins. If there is no order, say so.
21
23
  - **Which block is the focus**: name it (“the middle column”, “the lower row”).
22
24
 
23
- Do not specify colors, radii, pill chrome, weight, gaps, shadows, or full-bleed. Defaults own appearance.
25
+ Describe the visual relationships and desired emphasis. Defaults are a starting point, not a substitute for checking alignment and hierarchy. Explicit styling must use supported controls.
24
26
 
25
27
  **Every tag and shared token**: [compose reference](/garden/en/reference/compose). **Every icon name**: [compose icons](/garden/en/reference/compose-icons).
26
28
 
@@ -189,3 +191,10 @@ intent: |
189
191
  <stat label="Predicted best time" value={best} />
190
192
  ```
191
193
 
194
+
195
+ ## Custom text and background colors
196
+
197
+ `color` controls text (inherited; children may override). `backgroundColor` paints only the current surface (not inherited). Both accept literal CSS named colors, transparent/currentColor, 3/4/6/8-digit hex, rgb/rgba/hsl/hsla with optional alpha. URLs, var(), calc(), declarations and arbitrary style are rejected by the same SSR/browser validator. Defaults preserve tone and theme; no font-family change. Explicit colors are not automatically dark-mode adapted: check contrast.
198
+
199
+ Static primitives: box/card, row/stack/columns/grid/grid-item, pill/band, group/field/header/footer/figure, title/text/caption/label/prose/badge, kpi/stat, list, table/tr/th/td/thead/tbody. Play: stack/columns/card/caption/badge/stat/table. Colors must be literals. Existing static `background` semantic tokens and chart palette/series-tone APIs are unchanged; these props do not set chart series colors.
200
+
@@ -9,7 +9,7 @@ order: 45
9
9
  An image that is its own paragraph is wrapped in a figure, with a caption underneath.
10
10
 
11
11
  - **When to use**: The figure belongs in the article, and the reader should see a caption under it.
12
- - **When to skip**: For a decorative image, start the alt text with `image` or `img` so there is no caption. Use an [explanation diagram](/garden/en/components/compose) when each step needs its own note, or [file download](/garden/en/components/file) when the reader should download the file.
12
+ - **When to skip**: For a decorative image, start the alt text with `image` or `img` so there is no caption. Use an [explanation diagram](/garden/en/components/compose) when each step needs its own note, or [file download](/garden/en/components/compose) when the reader should download the file.
13
13
 
14
14
  For a post at `content/posts/my-post.md`, put images in `content/posts/my-post/`. Reference them with Markdown image syntax, with the address `./my-post/diagram.svg` and the caption in the alt text.
15
15
 
@@ -9,7 +9,7 @@ order: 43
9
9
  A URL on its own paragraph, or a link followed immediately by `{card}`, renders as a link card (same-site and external share one path). An ordinary titled link in prose stays a link, such as [Typora](https://typora.io/): an external one shows the site favicon before the text and a `↗` at the upper right; a titled same-site link still navigates in place.
10
10
 
11
11
  - **When to use**: The reader should see the site name, title, and summary before opening the page.
12
- - **When to skip**: Use a [source chip](/garden/en/components/source) to cite a site inside a sentence, or a [reference card](/garden/en/components/card) when you are writing the takeaways yourself.
12
+ - **When to skip**: Use a [source chip](/garden/en/components/source) to cite a site inside a sentence, or a [reference card](/garden/en/components/compose) when you are writing the takeaways yourself.
13
13
 
14
14
  ## A URL on its own line
15
15
 
@@ -43,7 +43,7 @@ When the paragraph is only the marked link, that line becomes the card:
43
43
 
44
44
  `{card}` inside code stays as written, for example `[text](https://example.com){card}`. A space between `)` and the marker also leaves an ordinary link. Same-site and external jump links share one card path.
45
45
 
46
- At build time, Garden reads `{card}` links and URLs that stand alone as a paragraph, and stores the page title, summary, and image in `link-assets.json` (same-site and external share one fetch path; HTML meta refresh is followed to the target before reading OG). A failed fetch keeps the previous record, and the build continues. Run `npx garden links` to refresh just these records. Set `GARDEN_OFFLINE` to `1` to skip the fetch during an offline build.
46
+ At build time, Garden reads `{card}` links and URLs that stand alone as a paragraph, and stores the page title, summary, and image in `.garden/link-assets.json` (same-site and external share one fetch path; HTML meta refresh is followed to the target before reading OG). A failed fetch keeps the previous record, and the build continues. Run `npx garden links` to refresh just these records. Set `GARDEN_OFFLINE` to `1` to skip the fetch during an offline build.
47
47
 
48
48
  A thought can also carry an external link in Front Matter with `type: link`, using the `title`, `description`, and `image` you write. Those fields are in [Writing Posts & Thoughts](/garden/en/writing).
49
49
 
@@ -1,221 +1,13 @@
1
1
  ---
2
- title: Components Overview
3
- navTitle: Overview
4
- description: Live previews of the garden fences, plus link cards, source chips, and local images.
2
+ title: Components
3
+ navTitle: Components
4
+ description: Components
5
5
  section: components
6
6
  order: 30
7
7
  ---
8
8
 
9
- ## [Reference Card · card](/garden/en/components/card)
9
+ 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.
10
10
 
11
- ```garden card
12
- title: SQLite Write-Ahead Logging
13
- url: https://www.sqlite.org/wal.html
14
- meta: Documentation · sqlite.org
15
- description: Appends changes sequentially to a write-ahead log while readers continue reading the original database pages, reducing read-write contention.
16
- points:
17
- - Writes append to the end of the `-wal` file instead of overwriting database pages in place on commit.
18
- - Readers record the current end-of-log mark to see a consistent snapshot without blocking concurrent writers.
19
- ```
20
-
21
- ## [Key Figures · stat](/garden/en/components/stat)
22
-
23
- ```garden stat
24
- items:
25
- - label: Reading Column
26
- value: "740"
27
- unit: px
28
- caption: Default prose column width
29
- - label: Wide Figure Limit
30
- value: "1040"
31
- unit: px
32
- caption: Extends up to 150px on each side
33
- - label: Wide Table Limit
34
- value: "1340"
35
- unit: px
36
- caption: Extends up to 300px on each side
37
- ```
38
-
39
- ## [Side-by-Side Comparison · compare](/garden/en/components/compare)
40
-
41
- ```garden compare
42
- items:
43
- - title: Describe the change in one sentence
44
- text: Idea block under full code; the AI writes the diff.
45
- - title: Write the diff by hand
46
- text: Place a diff block right below the full code block.
47
- ```
48
-
49
- ## [Step Timeline · timeline](/garden/en/components/timeline)
50
-
51
- ```garden timeline
52
- items:
53
- - date: Step 1
54
- title: Sync Content and Assets
55
- text: Validate Front Matter, copy attachments, and build the search index and RSS feed.
56
- - date: Step 2
57
- title: Build Static Site Output
58
- text: Prerender every route into the static output directory.
59
- ```
60
-
61
- ## [Bar Chart · chart](/garden/en/components/chart)
62
-
63
- ```garden chart
64
- title: Max Width by Layout Zone
65
- xLabel: Layout Zone
66
- yLabel: Max Width
67
- unit: px
68
- data:
69
- - x: Prose Column
70
- y: 740
71
- - x: Wide Figure Zone
72
- y: 1040
73
- - x: Wide Table Zone
74
- y: 1340
75
- ```
76
-
77
- ## [Explanation diagram · compose](/garden/en/components/compose)
78
-
79
- ```garden compose
80
- <intent>
81
- 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.
82
- </intent>
83
- <row align="center">
84
- <title align="center">Understand</title>
85
- <arrow dir="right"/>
86
- <title align="center">Design</title>
87
- <arrow dir="right"/>
88
- <title align="center">Ship</title>
89
- </row>
90
- <divider/>
91
- <row align="center">
92
- <pill tone="muted">Hypothesize</pill>
93
- <arrow dir="right"/>
94
- <pill tone="muted">Cheap test</pill>
95
- <arrow dir="right"/>
96
- <pill tone="muted">Iterate or stop</pill>
97
- </row>
98
- ```
99
-
100
- ## [Embedded Web Snippet · html](/garden/en/components/html)
101
-
102
- ```garden html
103
- title: Character Count Widget
104
- code: |
105
- <!doctype html>
106
- <html lang="en">
107
- <head>
108
- <meta charset="utf-8" />
109
- <style>
110
- body { margin: 0; padding: 16px 18px; font: 14px/1.6 system-ui, sans-serif; color: #1b1a18; background: #faf9f5; }
111
- input { width: 100%; box-sizing: border-box; padding: 8px 10px; border: 1px solid #d5d1c8; border-radius: 6px; font: inherit; background: #fff; color: #1b1a18; }
112
- .meta { margin-top: 10px; color: #6e6b64; font-variant-numeric: tabular-nums; }
113
- strong { color: #1b1a18; }
114
- </style>
115
- </head>
116
- <body>
117
- <input id="txt" value="Keep your posts in a Git repository and push to deploy." aria-label="Sample text input" />
118
- <div class="meta">Characters: <strong id="count">55</strong></div>
119
- <script>
120
- const input = document.getElementById("txt");
121
- const count = document.getElementById("count");
122
- input.addEventListener("input", () => { count.textContent = String(input.value.length); });
123
- </script>
124
- </body>
125
- </html>
126
- ```
127
-
128
- ## [Interactive Formula & Parameters · interactive](/garden/en/components/interactive)
129
-
130
- ```garden compose #overview-reading
131
- caption: "Example: estimate reading time from word count and reading speed."
132
- ---
133
- <State words={6000} speed={400} />
134
- <Let minutes={round(words / speed)} />
135
-
136
- <Slider bind="words" label="Word count" min={1000} max={20000} step={500} unit="words" />
137
- <Slider bind="speed" label="Reading speed" min={200} max={800} step={50} unit="wpm" />
138
-
139
- <Stat label="Estimated reading time" value={minutes} unit="min" />
140
- ```
141
-
142
- ## [File Download & Preview · file](/garden/en/components/file)
143
-
144
- ```garden file
145
- src: ./components/file/checklist.md
146
- title: Pre-publish Checklist
147
- note: Click Preview to read inline or Download to save the file
148
- ```
149
-
150
- ## [Relationship diagram · relations](/garden/en/components/relations)
151
-
152
- ```garden relations
153
- items:
154
- - title: Pick
155
- text: Choose this month's book
156
- - title: Read
157
- text: Finish the agreed chapters each week
158
- - title: Talk
159
- text: Meet and share views
160
- - title: Review
161
- text: Note what to change next time
162
- links:
163
- - from: 1
164
- to: 2
165
- - from: 2
166
- to: 3
167
- - from: 3
168
- to: 4
169
- - from: 4
170
- to: 1
171
- - from: 3
172
- to: 1
173
- style: dashed
174
- label: shapes the pick
175
- ```
176
-
177
- ## [Icon List · list](/garden/en/components/list)
178
-
179
- ```garden list
180
- items:
181
- - icon: search
182
- text: Searches for this month's title
183
- - icon: eye
184
- text: Reads 3 reviews
185
- - icon: heart
186
- text: Saves the event page
187
- - icon: chat
188
- text: Asks in the group chat whether listening only is fine
189
- ```
190
-
191
- ## [Choice Cards · choice](/garden/en/components/choice)
192
-
193
- ```garden choice
194
- title: Where should we meet next month?
195
- items:
196
- - icon: idea
197
- value: $6 each
198
- text: Corner café, one drink included
199
- label: Prefer the atmosphere
200
- reply: Café it is. We will book the long table by the window.
201
- - icon: book
202
- value: Free
203
- text: Library meeting room, booking needed
204
- label: Prefer the quiet
205
- reply: Library it is. We will book the room at the start of the month.
206
- none:
207
- label: Neither / not sure
208
- reply: No problem. We will share a few more venues in the group chat.
209
- ```
210
-
211
- ## [Link card · {card}](/garden/en/components/link-card)
212
-
213
- [Supported KaTeX functions](https://katex.org/docs/supported.html){card}
214
-
215
- ## [Source chip · {source}](/garden/en/components/source)
216
-
217
- Cited from Wikipedia [wikipedia.org](https://en.wikipedia.org/wiki/Book_discussion_club){source}
218
-
219
- ## [Local image](/garden/en/components/image)
220
-
221
- ![Reading column, wide figure zone, and wide table zone](../assets/reading-layout-en.svg)
11
+ - [Compose](/garden/en/components/compose)
12
+ - [Compose reference](/garden/en/reference/compose)
13
+ - [Icons](/garden/en/reference/compose-icons)
@@ -38,6 +38,17 @@ jobs:
38
38
  steps:
39
39
  - uses: actions/checkout@v7
40
40
 
41
+ - name: Restore generated Garden caches
42
+ uses: actions/cache@v4
43
+ with:
44
+ path: |
45
+ .garden/image-sizes.json
46
+ .garden/link-assets.json
47
+ public/link-assets
48
+ key: ${{ runner.os }}-garden-generated-v1-${{ github.ref_name }}-${{ github.run_id }}
49
+ restore-keys: |
50
+ ${{ runner.os }}-garden-generated-v1-${{ github.ref_name }}-
51
+
41
52
  - uses: actions/setup-node@v7
42
53
  with:
43
54
  node-version: 22
@@ -18,14 +18,14 @@ Drop an unnamed `garden` fence where the interactive block should go and state w
18
18
  ````markdown
19
19
  ## Writing Pace
20
20
 
21
- ```garden
21
+ ```garden compose
22
22
  Let the reader drag daily word count and writing days per week to see how many weeks an 8,000-word article takes.
23
23
  ```
24
24
  ````
25
25
 
26
26
  ### 2. The Agent Scans and Writes Back the Component
27
27
 
28
- 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:
28
+ 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:
29
29
 
30
30
  ```console
31
31
  $ npx garden ui scan content/posts/writing-pace.md
@@ -34,7 +34,7 @@ $ npx garden ui scan content/posts/writing-pace.md
34
34
  "draft": false,
35
35
  "blocks": [
36
36
  {
37
- "lang": "garden-idea",
37
+ "lang": "garden-compose",
38
38
  "status": "uncompiled",
39
39
  "startLine": 9,
40
40
  "intentHash": "8866427a",
@@ -52,54 +52,42 @@ $ npx garden ui apply content/posts/writing-pace.md --intent-hash 8866427a --fil
52
52
  {"ok":true,"file":"content/posts/writing-pace.md","kind":"garden","line":9}
53
53
  ```
54
54
 
55
- ### 3. The Pre-commit Hook Checks and Prints a Fix Prompt
55
+ ### 3. The Pre-commit Hook Checks and Points to the Project Skill
56
56
 
57
- 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:
57
+ 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:
58
58
 
59
59
  ```console
60
60
  $ git commit -m "Writing pace"
61
- content/posts/writing-pace.md:9 - garden-idea uncompiled idea remaining
62
-
63
- ──────────────────────── Fix prompt for AI ────────────────────────
64
- Handle the Garden post blocks listed below: compile uncompiled ideas, and fix interactive blocks that have errors.
65
-
66
- Rules:
67
- - First run npx garden ui prompt and read the component catalog and rules; if the repo has the garden-ui skill, follow its flow.
68
- - 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.
69
- - Keep the author's meaning. When done, run npx garden ui check <post> until it passes.
70
- - If you cannot access this repository, reply with only the finished fence for each block.
71
-
72
- 1. content/posts/writing-pace.md, lines 9–11, intent-hash: 8866427a
73
- - 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).
74
-
75
- Current fence:
76
-
77
- ```garden
78
- Let the reader drag daily word count and writing days per week to see how many weeks an 8,000-word article takes.
79
- ```
80
- ────────────────────────────────────────────────────────────
81
- Wrote .garden/ui-fix-prompt.md. To commit anyway, run git commit --no-verify.
61
+ content/posts/writing-pace.md:9 - compose-uncompiled uncompiled compose idea remaining
62
+ Use garden-compose skill (.agents/skills/garden-compose/SKILL.md), fix the failing blocks, then recheck.
82
63
  ```
83
64
 
84
- 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`.
65
+ 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`.
85
66
 
86
67
  ### 4. The Rendered Result
87
68
 
88
69
  The `garden compose` fence written back in step 2 renders directly on the article page as an interactive calculator:
89
70
 
90
71
  ```garden compose #writing-pace
91
- caption: Writing a few hundred extra words each day finishes sooner than adding another writing day per week.
92
- intent: |
93
- Let the reader drag daily word count and writing days per week to see how many weeks an 8,000-word article takes.
72
+ caption: Writing a few hundred extra words each day finishes sooner than adding
73
+ another writing day per week.
74
+ intent: >
75
+ Let the reader drag daily word count and writing days per week to see how many
76
+ weeks an 8,000-word article takes.
94
77
  ---
95
- <State daily={500} days={3} />
96
- <Let weekly={daily * days} />
97
- <Let weeks={ceil(8000 / weekly)} />
78
+ {@body const [daily, setDaily] = DIL.useState(500)}
79
+ {@body const [days, setDays] = DIL.useState(3)}
80
+ {@body const weekly = daily * days}
81
+ {@body const weeks = ceil(8000 / weekly)}
82
+
83
+
98
84
 
99
- <Slider bind="daily" label="Words per day" min={200} max={2000} step={100} unit="words" />
100
- <Slider bind="days" label="Days per week" min={1} max={7} step={1} unit="days" />
101
85
 
102
- <Stat label="Weeks to finish 8,000 words" value={weeks} unit="weeks" hint="Rounded up to full weeks" />
86
+ <slider bind="daily" label="Words per day" min={200} max={2000} step={100} unit="words" />
87
+ <slider bind="days" label="Days per week" min={1} max={7} step={1} unit="days" />
88
+
89
+ <stat label="Weeks to finish 8,000 words" value={weeks} unit="weeks" hint="Rounded up to full weeks" />
90
+
103
91
  ```
104
92
 
105
93
  > [!IMPORTANT] Humans and Agents Share the Same Tools
@@ -153,25 +141,13 @@ pages:
153
141
 
154
142
  ## Structured Components in Markdown
155
143
 
156
- Use ```` ```garden <name> ```` fences to insert metrics, side-by-side comparisons, timelines, or charts. Here is a `garden stat` block:
157
-
158
- ```garden stat
159
- items:
160
- - label: Reading Column
161
- value: "740"
162
- unit: px
163
- caption: Default width for paragraphs, code blocks, and lists
164
- - label: Wide Figure Zone
165
- value: "1040"
166
- unit: px
167
- caption: Screenshots display at half their pixel width and expand up to this limit above ~2000px
168
- - label: Wide Table Zone
169
- value: "1340"
170
- unit: px
171
- caption: Maximum width for wide multi-column tables expanding symmetrically on desktop
144
+ Use `garden compose` to combine metrics, comparisons, timelines, or plots. Here is a metric scene:
145
+
146
+ ```garden compose
147
+ <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>
172
148
  ```
173
149
 
174
- 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.
150
+ 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.
175
151
 
176
152
  <h2 id="garden-admin-title">From Init to Daily Writing</h2>
177
153