@bestagentkits/render 0.1.0 → 0.2.0

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 (111) hide show
  1. package/CHANGELOG.md +119 -0
  2. package/README.md +189 -34
  3. package/assets/fonts/bricolage-grotesque/OFL.txt +93 -0
  4. package/assets/fonts/fraunces/OFL.txt +93 -0
  5. package/assets/fonts/geist/OFL.txt +93 -0
  6. package/assets/fonts/inter-tight/OFL.txt +93 -0
  7. package/assets/fonts/jetbrains-mono/OFL.txt +93 -0
  8. package/assets/fonts/plus-jakarta-sans/OFL.txt +93 -0
  9. package/dist/cli.d.ts +2 -0
  10. package/dist/cli.d.ts.map +1 -1
  11. package/dist/cli.js +51 -10
  12. package/dist/cli.js.map +1 -1
  13. package/dist/mcp-server.d.ts +37 -0
  14. package/dist/mcp-server.d.ts.map +1 -0
  15. package/dist/mcp-server.js +274 -0
  16. package/dist/mcp-server.js.map +1 -0
  17. package/dist/registry/roster.d.ts +1 -1
  18. package/dist/registry/roster.d.ts.map +1 -1
  19. package/dist/registry/roster.js +222 -6
  20. package/dist/registry/roster.js.map +1 -1
  21. package/dist/render/block-helpers.d.ts +52 -0
  22. package/dist/render/block-helpers.d.ts.map +1 -0
  23. package/dist/render/block-helpers.js +113 -0
  24. package/dist/render/block-helpers.js.map +1 -0
  25. package/dist/render/blocks.d.ts +3 -4
  26. package/dist/render/blocks.d.ts.map +1 -1
  27. package/dist/render/blocks.js +126 -121
  28. package/dist/render/blocks.js.map +1 -1
  29. package/dist/render/charts.d.ts +5 -0
  30. package/dist/render/charts.d.ts.map +1 -1
  31. package/dist/render/charts.js +205 -90
  32. package/dist/render/charts.js.map +1 -1
  33. package/dist/render/derived-variables.d.ts +17 -0
  34. package/dist/render/derived-variables.d.ts.map +1 -0
  35. package/dist/render/derived-variables.js +17 -0
  36. package/dist/render/derived-variables.js.map +1 -0
  37. package/dist/render/diagram-fallback.d.ts +25 -0
  38. package/dist/render/diagram-fallback.d.ts.map +1 -0
  39. package/dist/render/diagram-fallback.js +86 -0
  40. package/dist/render/diagram-fallback.js.map +1 -0
  41. package/dist/render/document.d.ts +4 -0
  42. package/dist/render/document.d.ts.map +1 -1
  43. package/dist/render/document.js +34 -6
  44. package/dist/render/document.js.map +1 -1
  45. package/dist/render/effects-styles.d.ts +14 -0
  46. package/dist/render/effects-styles.d.ts.map +1 -0
  47. package/dist/render/effects-styles.js +39 -0
  48. package/dist/render/effects-styles.js.map +1 -0
  49. package/dist/render/embedded-fonts.generated.d.ts +22 -0
  50. package/dist/render/embedded-fonts.generated.d.ts.map +1 -0
  51. package/dist/render/embedded-fonts.generated.js +59 -0
  52. package/dist/render/embedded-fonts.generated.js.map +1 -0
  53. package/dist/render/feature-styles.d.ts +14 -0
  54. package/dist/render/feature-styles.d.ts.map +1 -0
  55. package/dist/render/feature-styles.js +161 -0
  56. package/dist/render/feature-styles.js.map +1 -0
  57. package/dist/render/font-faces.d.ts +22 -0
  58. package/dist/render/font-faces.d.ts.map +1 -0
  59. package/dist/render/font-faces.js +60 -0
  60. package/dist/render/font-faces.js.map +1 -0
  61. package/dist/render/outline.d.ts +21 -0
  62. package/dist/render/outline.d.ts.map +1 -0
  63. package/dist/render/outline.js +44 -0
  64. package/dist/render/outline.js.map +1 -0
  65. package/dist/render/render.d.ts.map +1 -1
  66. package/dist/render/render.js +53 -10
  67. package/dist/render/render.js.map +1 -1
  68. package/dist/render/runtime.d.ts.map +1 -1
  69. package/dist/render/runtime.js +184 -10
  70. package/dist/render/runtime.js.map +1 -1
  71. package/dist/render/showcase-blocks.d.ts +47 -0
  72. package/dist/render/showcase-blocks.d.ts.map +1 -0
  73. package/dist/render/showcase-blocks.js +349 -0
  74. package/dist/render/showcase-blocks.js.map +1 -0
  75. package/dist/render/showcase-styles.d.ts +15 -0
  76. package/dist/render/showcase-styles.d.ts.map +1 -0
  77. package/dist/render/showcase-styles.js +217 -0
  78. package/dist/render/showcase-styles.js.map +1 -0
  79. package/dist/render/signature-styles.d.ts +18 -0
  80. package/dist/render/signature-styles.d.ts.map +1 -0
  81. package/dist/render/signature-styles.js +41 -0
  82. package/dist/render/signature-styles.js.map +1 -0
  83. package/dist/render/styles.d.ts +18 -9
  84. package/dist/render/styles.d.ts.map +1 -1
  85. package/dist/render/styles.js +224 -128
  86. package/dist/render/styles.js.map +1 -1
  87. package/dist/render/surface-styles.d.ts +24 -0
  88. package/dist/render/surface-styles.d.ts.map +1 -0
  89. package/dist/render/surface-styles.js +41 -0
  90. package/dist/render/surface-styles.js.map +1 -0
  91. package/dist/render/verify.d.ts.map +1 -1
  92. package/dist/render/verify.js +30 -0
  93. package/dist/render/verify.js.map +1 -1
  94. package/dist/spec/normalize.d.ts.map +1 -1
  95. package/dist/spec/normalize.js +32 -0
  96. package/dist/spec/normalize.js.map +1 -1
  97. package/dist/theme/load-theme.d.ts +2 -2
  98. package/dist/theme/load-theme.d.ts.map +1 -1
  99. package/dist/theme/load-theme.js +46 -10
  100. package/dist/theme/load-theme.js.map +1 -1
  101. package/dist/theme/presets.d.ts +4 -3
  102. package/dist/theme/presets.d.ts.map +1 -1
  103. package/dist/theme/presets.js +35 -18
  104. package/dist/theme/presets.js.map +1 -1
  105. package/dist/theme/tokens.d.ts.map +1 -1
  106. package/dist/theme/tokens.js +4 -4
  107. package/dist/theme/tokens.js.map +1 -1
  108. package/dist/version.d.ts +1 -1
  109. package/dist/version.js +1 -1
  110. package/llms.txt +25 -0
  111. package/package.json +9 -3
package/CHANGELOG.md CHANGED
@@ -9,6 +9,125 @@ Release mechanics and the compatibility contract live in
9
9
 
10
10
  ## [Unreleased]
11
11
 
12
+ ## [0.2.0] - 2026-10-05
13
+
14
+ Every emitted page changes in this release: new styles, embedded fonts, and a
15
+ CSP that allows `font-src data:` on pages that carry a face.
16
+
17
+ ### Changed
18
+
19
+ - Polished the emitted artifacts:
20
+ - Heading sizes now follow the `font-scale` token.
21
+ - Spacing is driven by density, with larger gaps at section breaks.
22
+ - The hero carries an accent eyebrow rule, and the theme toggle is a right-aligned pill.
23
+ - Callouts, badges and tables are tinted, buttons and tabs have hover and press states, and all transitions use the motion tokens.
24
+ - Mobile touch targets are 44px.
25
+ - Charts now have clean axis ticks with gridlines, rounded bars centered under their labels, a series palette derived from the theme accent, legends, a donut total, and SVG heights sized to their content (sparkline and progress).
26
+ - Elevation shadows are layered. A table title no longer prints twice; its caption is kept for screen readers only.
27
+ - Artifacts now emit `og:title`, `og:type`, `og:description` and `twitter:card` from the spec meta.
28
+ - The gallery index is now one card per artifact.
29
+ - Redesigned the component system in the emitted stylesheet:
30
+ - Top-level sections open on a hairline with a short accent tab, and nested block titles step down a size, so the heading hierarchy reads at a glance.
31
+ - The hero title is larger, and the page carries a faint accent wash at the top.
32
+ - Stats share one framed panel with hairline dividers. Steps use numbered rings on a connector, and timeline dots carry a halo.
33
+ - Callouts and alerts carry a tone glyph instead of a side stripe. Quotes use a hanging quote mark.
34
+ - Tabs are a segmented control, accordion items are separate panels with a plus/minus indicator, and the carousel slide is a framed stage with arrow controls.
35
+ - Tables gain a caption bar, row headers, and a minimum width on small screens so cells scroll instead of breaking word by word. Comparisons, key-value lists, code blocks, badges, key caps, progress bars, sliders, search inputs and dialogs were refined to match.
36
+ - In dark schemes, surfaces get a top-lit sheen, because the fixed elevation shadows are invisible on a dark page.
37
+ - Images on a page that allows `images` now add their origin to `img-src` for every image-bearing block. Before, only `image` and `gallery` did; only `video` and `audio` use the `media` capability.
38
+ - Feature stylesheets moved to `src/render/feature-styles.ts`; `styles.ts` re-exports them.
39
+ - **Embedded fonts (CSP change).** Every preset now leads its display stack with a bundled SIL OFL 1.1 variable face: Geist (blueprint), Fraunces (editorial), Bricolage Grotesque (paper-ink), Inter Tight (swiss-clean), JetBrains Mono (terminal-mono) and Plus Jakarta Sans (warm-signal).
40
+ - The face is inlined as a `data:` WOFF2, so nothing is fetched. The Latin subset is always emitted; the Vietnamese subset only when the page text needs it.
41
+ - Pages that carry a face emit `font-src data:` instead of `font-src 'none'`. Verification fails on any `@font-face` source that is not inlined, and on a CSP that does not match.
42
+ - Artifacts grow by roughly 30–60 kB per page. A custom font stack that names no bundled `AK ` family embeds nothing.
43
+ - The licences ship in `assets/fonts/<family>/OFL.txt` and in the npm package. Each `@font-face` carries a notice comment.
44
+ - Blueprint's light scheme is warmer and higher-contrast: a drafting-paper background (`#f4f2ed`), near-black text, and a cobalt accent (`#1d4fd7`).
45
+ - Bento tile images now sit as a panel bleeding off the tile edge over an accent-tinted backdrop. Showcase frame images drift with scroll (parallax) instead of settling.
46
+ - The browser frame styles moved to the base sheet, so the hero can use them.
47
+
48
+ ### Added
49
+
50
+ - `ak-render mcp` serves the compiler as an MCP server over stdio, with `catalog`, `describe`, `validate`, `render` and `themes` tools. `render` writes the HTML to the `out` path, which must end in `.html` or `.htm`, and returns only a summary. `themes` returns the presets plus any preset file that failed to load. The server accepts JSON-RPC batches and answers an unknown tool or a null id with a protocol error. No new runtime dependency.
51
+ - An `ak-render` agent skill (`skills/ak-render/SKILL.md`), installable with `npx skills add bestagentkits/ak-render`, plus Claude Code and Codex plugin marketplaces that bundle the skill and register the MCP server, pinned to the matching package version.
52
+ - Pass `-` as the spec path to compile or validate a spec from standard input. Diagnostics name the source `<stdin>`.
53
+ - `llms.txt` (shipped in the package) and `docs/agent-guide.md`: the agent loop, a minimal spec, and the MCP client config.
54
+ - `section` gains `surface: plain | inverse`. An inverse section sits on a night band: a dark panel where every colour token takes the theme's dark value, so nested blocks recolour without variants.
55
+ - A `cta` block: eyebrow, an oversized gradient title, text, and up to three link actions, on the night band. It is the new `cta` runtime feature.
56
+ - `hero` gains optional `src`, `alt`, `address` and `align: start | center`. With `src`, a framed product shot sits below the copy and straightens from a tilt as the page scrolls. `alt` is required when `src` is set.
57
+ - The theme toggle reveals the new scheme as a circle growing from the button, through the View Transitions API, when motion is allowed. Otherwise it switches instantly, as before.
58
+ - `scripts/capture-demo-media.mjs` records element-level crops at 2x (`crop-chart`, `crop-donut`, `crop-compare`, `crop-timeline`, `crop-diagram`). The showcase bento uses them.
59
+ - `pnpm fonts:generate` and `pnpm fonts:check` regenerate and check the embedded font module.
60
+ - A page outline ("On this page") with scroll-spy appears when a page has three or more titled top-level sections. It is the new `outline` runtime feature, and sections now carry an `id` of the form `ak-sec-<node id>`.
61
+ - A reading-progress rail.
62
+ - A colophon footer with a back-to-top link.
63
+ - Code blocks have line numbers, a language pill, and a Copy button with a copied state. The `code` block now declares the `copy` runtime feature.
64
+ - Charts:
65
+ - Area fills are gradients.
66
+ - Bars and points reveal their values on hover or focus.
67
+ - The cartesian viewBox is 800×300, and on narrow screens the chart scrolls sideways instead of shrinking its text.
68
+ - Tables:
69
+ - Numeric columns align right.
70
+ - Diff status, risk levels and review kinds render as toned badges.
71
+ - Diff line counts are signed and colored.
72
+ - External links in prose carry a ↗ marker.
73
+ - Diagram fallbacks render a simple chain as a flow of node cards joined by labelled arrows, vertical on phones. Other graphs show node cards plus an explicit connection list.
74
+ - A signature style layer (`src/render/signature-styles.ts`):
75
+ - a fluid display-size hero title and a staggered hero entrance;
76
+ - balanced headings;
77
+ - drawn link underlines;
78
+ - cards that end in a link become a single lifted target with an arrow CTA;
79
+ - larger stat figures and a subtle top light on primary buttons.
80
+ - Bar charts use per-series gradients.
81
+ - Eight showcase blocks:
82
+ - `bento`, a mosaic of tiles with sizes, images and display figures;
83
+ - `marquee`, an accessible looping ticker;
84
+ - `terminal`, a typed session with a copy control;
85
+ - `file-tree`, built from flat paths with status;
86
+ - `before-after`, an image slider driven by a native range input, which adds the `before-after` runtime feature;
87
+ - `kpi`, metrics with a delta, a good/bad verdict and a sparkline;
88
+ - `showcase`, copy beside a capture in browser chrome;
89
+ - `checklist`, with a done count and a progress meter.
90
+ Each has its own tree-shaken feature sheet.
91
+ - An effects layer (`src/render/effects-styles.ts`):
92
+ - a theme-tinted hero aurora;
93
+ - a word-by-word hero title reveal;
94
+ - a film-grain texture;
95
+ - a pointer spotlight on cards;
96
+ - count-up for numeric stats and KPIs;
97
+ - scroll-linked settling of framed images;
98
+ - a sweep on primary buttons.
99
+ All of it respects reduced motion and print. Count-up keeps the authored value in the DOM and draws the rolling figure on a hidden layer, so screen readers, copy and print always get the real number.
100
+ - Real demo media in `fixtures/assets`: screenshots and a 41s screen recording of the compiled gallery, captured by `scripts/capture-demo-media.mjs`.
101
+ - A `showcase` landing fixture. The media fixture plays the local recording, shows the real screenshots, and compares light and dark. The gallery index opens with a marquee and a showcase of the landing page.
102
+
103
+ ### Fixed
104
+
105
+ - A non-colour token set under a theme's `tokens` (a font stack, spacing, or motion value) now applies to the dark scheme too. Before, dark mode fell back to the parent preset's value.
106
+ - `motion-policy: none` now stops every animation, not only the token-driven durations: the aurora, marquee, caret, word reveal, scroll-linked reveals, count-up, the primary-button sweep and the theme-toggle transition. The zeroed duration now also wins over the dark scheme, which used to restore it under reduced motion. The reading-progress rail still follows the scroll position, since it moves only when the reader scrolls. The page renders as it does under reduced motion, and the root carries `data-motion="none"`.
107
+ - `loadTheme` reports a non-object `tokens` or `dark` value as a `POLICY_VIOLATION` render error instead of throwing a `TypeError`.
108
+ - File trees order names by code point, so the order no longer depends on the runtime's collation.
109
+ - A blocked remote image keeps its alt text, and every blocked image, video, audio or embed names the real reason: the network is denied, the capability is not allowed, or the host is not on the provider allowlist. Before, the note always said the network was denied.
110
+ - A `bento` tile with `src` now requires `alt`; an explicit `alt: ""` marks a decorative image.
111
+ - The terminal's caption is a direct child of its figure, and the figure is named by the title alone.
112
+ - Checklist, browser-frame (hero shot and showcase) and bento image styles moved out of the base stylesheet into feature sheets, so pages without those blocks no longer carry them. `checklist` and `frame` are new runtime features.
113
+ - The night band now uses the same tint, focus ring and sheen as dark mode; it had drifted to stronger values.
114
+ - Font verification checks every source of every `@font-face`, and rejects `local()`, instead of only the first `url()`.
115
+ - The theme toggle names the scheme it switches to from the first paint, and follows a system scheme change while the page is open. Before, it read "Dark" on a page the system had already put in dark mode.
116
+ - A `split`, `grid` or `comparison` column no longer grows past a phone screen when a child holds a long code line; the line scrolls inside its frame.
117
+ - `ak-render <command> --help` prints that command's usage instead of trying to read a file named `--help`; `ak-render page.yaml --help` prints the compile usage instead of compiling.
118
+ - `--out` creates missing folders, and a file that cannot be written exits `2` with a one-line reason instead of a stack trace and exit `1`, which agents read as "fix the spec".
119
+ - `img-src` and `media-src` include `'self'`, so a page's relative assets load when it is served over HTTP(S) instead of opened from disk. Remote URLs are still gated by the network policy.
120
+
121
+ ## [0.1.1-next.1] - 2026-09-22
122
+
123
+ Prerelease published to exercise the trusted-publishing release path end to end:
124
+ the tag run publishes over GitHub OIDC with provenance and no stored token. No
125
+ functional changes; the compiler behaves as `0.1.0`.
126
+
127
+ ## [0.1.0] - 2026-09-22
128
+
129
+ First public release, published to npm as `@bestagentkits/render`.
130
+
12
131
  ### Added
13
132
 
14
133
  - Repository baseline for the public AK Render package: MIT license,
package/README.md CHANGED
@@ -1,37 +1,192 @@
1
1
  # @bestagentkits/render
2
2
 
3
- Declarative page compiler for AgentKit: a constrained JSON/YAML **Page Spec**
4
- in, a deterministic, self-contained, interactive **standalone HTML** out.
3
+ A declarative page compiler for coding agents. An agent writes a short YAML or
4
+ JSON **Page Spec**; `ak-render` compiles it into one deterministic,
5
+ self-contained, interactive **HTML file**.
6
+
7
+ [![The AK Render landing page, itself compiled from a Page Spec](./docs/assets/landing.webp)](https://render.agentkit.best)
8
+
9
+ **[render.agentkit.best](https://render.agentkit.best)** · [Gallery](https://render.agentkit.best/gallery/) · [Agent guide](./docs/agent-guide.md) · [npm](https://www.npmjs.com/package/@bestagentkits/render)
5
10
 
6
11
  Agents describe meaning and composition. The compiler owns HTML, CSS,
7
- interaction, accessibility, responsive layout, theming, asset bundling, security
8
- policy, and byte-for-byte determinism.
12
+ interaction, accessibility, responsive layout, theming, fonts, security policy
13
+ and byte-for-byte determinism. The agent spends tokens on the content instead
14
+ of on markup, and the result looks designed every time.
15
+
16
+ - **Offline by default.** The file opens from disk (`file://`) and makes zero
17
+ network requests. Fonts are embedded; nothing loads from a CDN.
18
+ - **Deterministic.** The same spec and compiler version produce the same bytes.
19
+ - **No escape hatch.** A spec cannot carry raw HTML, CSS or JavaScript, so a
20
+ page cannot drift off the design system or smuggle in a script.
21
+ - **Local is canonical.** No account, no server, no API key.
22
+
23
+ ## Quick start
24
+
25
+ Requires Node.js >= 20.11.
26
+
27
+ 1. Write a spec, `plan.yaml`:
28
+
29
+ ```yaml
30
+ version: 1
31
+ meta:
32
+ title: Migration plan
33
+ description: How we move the API to the new gateway.
34
+ theme:
35
+ preset: editorial
36
+ blocks:
37
+ - type: hero
38
+ eyebrow: Plan
39
+ title: Migration plan
40
+ description: Move the public API to the new gateway without downtime.
41
+ - type: section
42
+ title: Steps
43
+ blocks:
44
+ - type: steps
45
+ items:
46
+ - title: Mirror traffic
47
+ text: Send a copy of production requests to the new gateway.
48
+ - title: Switch reads
49
+ text: Route read endpoints once error rates match.
50
+ - type: callout
51
+ tone: info
52
+ title: Rollback
53
+ text: Point DNS back to the old gateway; no data migrates.
54
+ ```
55
+
56
+ 2. Validate it, then compile it:
57
+
58
+ ```bash
59
+ npx -y @bestagentkits/render validate plan.yaml
60
+ npx -y @bestagentkits/render plan.yaml --out plan.html
61
+ ```
62
+
63
+ 3. Open `plan.html` in any browser. It is one file you can attach, email or
64
+ commit.
65
+
66
+ ## Usage guide
67
+
68
+ ### Find the blocks you need
69
+
70
+ There are 54 block types, from primitives (`section`, `grid`, `split`, `text`)
71
+ to semantic blocks that carry the design for you (`hero`, `steps`, `timeline`,
72
+ `comparison`, `kpi`, `chart`, `terminal`, `bento`, `cta`). List them, then read
73
+ the full contract of the ones you use:
74
+
75
+ ```bash
76
+ ak-render catalog # every block and action, one line each
77
+ ak-render describe timeline # props, defaults, bounds, slots, a11y notes
78
+ ak-render describe kpi --json # the same, machine-readable
79
+ ```
80
+
81
+ Containers (`section`, `grid`, `split`, `stack`) take their children under
82
+ `blocks:`.
83
+
84
+ ### Validate and fix
85
+
86
+ ```bash
87
+ ak-render validate plan.yaml --json
88
+ ```
89
+
90
+ The result is `{ ok, diagnostics[] }`. Each diagnostic has a stable `code` and
91
+ the JSON `path` to fix, such as `$.blocks[1].blocks[0].items[2].title`. Exit
92
+ code `1` means "fix and retry"; `2` means the input could not be read or the
93
+ output could not be written.
94
+
95
+ ### Compile
96
+
97
+ ```bash
98
+ ak-render plan.yaml --out plan.html # compile is the default command
99
+ ak-render plan.yaml --out plan.html --json # print bytes, hash, features, warnings
100
+ ak-render - --out plan.html < plan.yaml # read the spec from stdin
101
+ ak-render plan.yaml --theme blueprint # override the spec's theme
102
+ ```
103
+
104
+ ### Themes
105
+
106
+ Six built-in presets, each with a light and a dark scheme and an embedded
107
+ display face: `blueprint`, `editorial`, `paper-ink`, `swiss-clean`,
108
+ `terminal-mono` and `warm-signal`. Pick one under `theme.preset`, or extend one
109
+ with validated tokens:
110
+
111
+ ```yaml
112
+ theme:
113
+ preset: team-theme
114
+ extends: editorial
115
+ tokens:
116
+ color-accent: "#b8860b"
117
+ motion-policy: none # a still page, as under reduced motion
118
+ ```
119
+
120
+ `ak-render themes` lists the presets it can see, including project and user
121
+ presets. See [docs/themes.md](./docs/themes.md).
122
+
123
+ ### Interaction
124
+
125
+ Tabs, accordions, carousels, sliders, dialogs, filters, copy buttons and the
126
+ theme toggle come from a small trusted runtime. A spec wires them with a closed
127
+ set of declarative actions (`ak-render catalog` lists them); there is no
128
+ JavaScript field. Every page reads completely with scripts off, with motion
129
+ reduced, in print and in a screenshot.
130
+
131
+ ### Images, video and the network
132
+
133
+ Local paths (`assets/shot.png`) always work. A remote URL renders as a labelled
134
+ fallback with a link unless the spec opts in:
135
+
136
+ ```yaml
137
+ policy:
138
+ network:
139
+ allow: [images, media]
140
+ ```
141
+
142
+ The page's Content Security Policy is derived from that policy. See
143
+ [docs/media-policy.md](./docs/media-policy.md).
144
+
145
+ ## Use it from an agent
146
+
147
+ Agents follow one loop: `catalog` once, `describe` the blocks they use,
148
+ `validate` and fix diagnostics by JSON path, then compile. The
149
+ [agent guide](./docs/agent-guide.md) has the details and [llms.txt](./llms.txt)
150
+ is the LLM-facing index.
151
+
152
+ ### Install the agent skill
153
+
154
+ The `ak-render` skill ([skills/ak-render/SKILL.md](./skills/ak-render/SKILL.md))
155
+ teaches an agent that loop.
156
+
157
+ **Any agent**, with the [skills CLI](https://github.com/vercel-labs/skills):
9
158
 
10
159
  ```bash
11
- npx @bestagentkits/render page.yaml --out page.html
160
+ npx skills add bestagentkits/ak-render
12
161
  ```
13
162
 
14
- The emitted file opens directly from disk (`file://`) and makes zero network
15
- requests by default. The local compiler is canonical: no account, no network, no
16
- server.
163
+ **Claude Code**, as a plugin that also registers the MCP server:
17
164
 
18
- > **Status:** pre-1.0, in active construction. This repository is being built in
19
- > milestones. The package skeleton, ADR, CI, and fixture corpus exist; the
20
- > schema, compiler, themes, runtime, catalog, and cloud service land in the
21
- > milestones described in [docs/adr/0001-page-spec-compiler-boundary.md](./docs/adr/0001-page-spec-compiler-boundary.md)
22
- > and the [changelog](./CHANGELOG.md). Nothing below is advertised as available
23
- > before it exists.
165
+ ```bash
166
+ claude plugin marketplace add bestagentkits/ak-render
167
+ claude plugin install ak-render@ak-render
168
+ ```
24
169
 
25
- ## Why
170
+ **Codex and ChatGPT**, as a plugin:
26
171
 
27
- AgentKit's HTML-producing skills each carried the presentation layer in model
28
- context: layout, CSS, JavaScript, charts, responsive rules, theming, and
29
- verification. That costs tokens, adds latency, invites retries after
30
- HTML/CSS/JS mistakes, and lets skills drift against each other.
172
+ ```bash
173
+ codex plugin marketplace add bestagentkits/ak-render
174
+ codex plugin add ak-render@ak-render
175
+ ```
31
176
 
32
- `ak:diagram` already proved the alternative for diagrams: typed IR, deterministic
33
- compiler, trusted fragment boundary. AK Render applies the same pattern to whole
34
- pages.
177
+ ### MCP server
178
+
179
+ `ak-render mcp` serves `catalog`, `describe`, `validate`, `render` and `themes`
180
+ as MCP tools over stdio. `render` writes the HTML to disk and returns only a
181
+ summary, so the page never enters the agent's context.
182
+
183
+ ```json
184
+ {
185
+ "mcpServers": {
186
+ "ak-render": { "command": "npx", "args": ["-y", "@bestagentkits/render", "mcp"] }
187
+ }
188
+ }
189
+ ```
35
190
 
36
191
  ## Design in one screen
37
192
 
@@ -64,20 +219,15 @@ Six decisions define the boundary, argued in
64
219
  `extends` them. No CSS escape hatch, no CDN fonts.
65
220
  5. **Local is canonical; cloud is opt-in.** The hosted renderer reuses the same
66
221
  compiler and is never the source of truth.
67
- 6. **Optional capabilities arrive as adapters.** Diagrams delegate to the
68
- existing `ak:diagram` compiler where installed; the public package never
69
- copies paid or Engineer-only implementation.
222
+ 6. **Optional capabilities arrive as adapters.** Diagrams can delegate to an
223
+ installed diagram compiler; without one, a structured fallback renders.
70
224
 
71
- ## Install
225
+ ## Install as a dependency
72
226
 
73
227
  ```bash
74
228
  pnpm add @bestagentkits/render
75
- # or run without installing
76
- npx @bestagentkits/render --help
77
229
  ```
78
230
 
79
- Requires Node.js >= 20.11.
80
-
81
231
  ## Library API
82
232
 
83
233
  ```ts
@@ -103,21 +253,22 @@ import {
103
253
  | `loadTheme(input)` | Validate and resolve a theme preset | Available |
104
254
  | `buildThemeCatalog(options)` | Discover built-in, user, project, and explicit presets | Available |
105
255
 
106
- ## CLI
256
+ ## CLI reference
107
257
 
108
258
  ```bash
109
259
  ak-render page.yaml --out page.html
260
+ ak-render - --out page.html < page.yaml # read the spec from stdin
110
261
  ak-render validate page.json
111
262
  ak-render catalog
112
263
  ak-render describe carousel
113
264
  ak-render themes
265
+ ak-render mcp # MCP server over stdio
114
266
 
115
- ak-render --help
267
+ ak-render <command> --help
116
268
  ak-render --version
117
269
  ```
118
270
 
119
- The CLI only advertises commands it can actually run; the compiler subcommands
120
- are registered by the milestones that implement them.
271
+ Every command accepts `--json` and never prompts.
121
272
 
122
273
  ## Fixtures and snapshots
123
274
 
@@ -139,6 +290,8 @@ capability is not done until a fixture exercises it.
139
290
  | `benchmarks/` | Reproducible measurement harnesses |
140
291
  | `docs/adr/` | Architecture decision records |
141
292
  | `docs/artifacts/` | Captured measurements and evidence |
293
+ | `skills/`, `.claude-plugin/`, `.agents/plugins/` | Agent skill and plugin manifests |
294
+ | `site/` | Landing page spec, build script output and Cloudflare config |
142
295
  | `apps/cloud/` | Opt-in Cloudflare renderer (cloud milestone) |
143
296
 
144
297
  ## Development
@@ -149,6 +302,8 @@ pnpm verify # lint + typecheck + unit tests + build
149
302
  pnpm test:browser # Playwright, after: pnpm exec playwright install chromium
150
303
  pnpm test:package # pack, install into a temp project, exercise API and bin
151
304
  pnpm bench:baseline # re-run the legacy presentation-context measurement
305
+ pnpm site:build # compile the landing page and gallery into site/dist
306
+ pnpm site:deploy # build, then deploy site/dist with wrangler
152
307
  ```
153
308
 
154
309
  See [CONTRIBUTING.md](./CONTRIBUTING.md) for the determinism, trust, and testing
@@ -0,0 +1,93 @@
1
+ Copyright 2022 The Bricolage Grotesque Project Authors (https://github.com/ateliertriay/bricolage)
2
+
3
+ This Font Software is licensed under the SIL Open Font License, Version 1.1.
4
+ This license is copied below, and is also available with a FAQ at:
5
+ http://scripts.sil.org/OFL
6
+
7
+
8
+ -----------------------------------------------------------
9
+ SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
10
+ -----------------------------------------------------------
11
+
12
+ PREAMBLE
13
+ The goals of the Open Font License (OFL) are to stimulate worldwide
14
+ development of collaborative font projects, to support the font creation
15
+ efforts of academic and linguistic communities, and to provide a free and
16
+ open framework in which fonts may be shared and improved in partnership
17
+ with others.
18
+
19
+ The OFL allows the licensed fonts to be used, studied, modified and
20
+ redistributed freely as long as they are not sold by themselves. The
21
+ fonts, including any derivative works, can be bundled, embedded,
22
+ redistributed and/or sold with any software provided that any reserved
23
+ names are not used by derivative works. The fonts and derivatives,
24
+ however, cannot be released under any other type of license. The
25
+ requirement for fonts to remain under this license does not apply
26
+ to any document created using the fonts or their derivatives.
27
+
28
+ DEFINITIONS
29
+ "Font Software" refers to the set of files released by the Copyright
30
+ Holder(s) under this license and clearly marked as such. This may
31
+ include source files, build scripts and documentation.
32
+
33
+ "Reserved Font Name" refers to any names specified as such after the
34
+ copyright statement(s).
35
+
36
+ "Original Version" refers to the collection of Font Software components as
37
+ distributed by the Copyright Holder(s).
38
+
39
+ "Modified Version" refers to any derivative made by adding to, deleting,
40
+ or substituting -- in part or in whole -- any of the components of the
41
+ Original Version, by changing formats or by porting the Font Software to a
42
+ new environment.
43
+
44
+ "Author" refers to any designer, engineer, programmer, technical
45
+ writer or other person who contributed to the Font Software.
46
+
47
+ PERMISSION & CONDITIONS
48
+ Permission is hereby granted, free of charge, to any person obtaining
49
+ a copy of the Font Software, to use, study, copy, merge, embed, modify,
50
+ redistribute, and sell modified and unmodified copies of the Font
51
+ Software, subject to the following conditions:
52
+
53
+ 1) Neither the Font Software nor any of its individual components,
54
+ in Original or Modified Versions, may be sold by itself.
55
+
56
+ 2) Original or Modified Versions of the Font Software may be bundled,
57
+ redistributed and/or sold with any software, provided that each copy
58
+ contains the above copyright notice and this license. These can be
59
+ included either as stand-alone text files, human-readable headers or
60
+ in the appropriate machine-readable metadata fields within text or
61
+ binary files as long as those fields can be easily viewed by the user.
62
+
63
+ 3) No Modified Version of the Font Software may use the Reserved Font
64
+ Name(s) unless explicit written permission is granted by the corresponding
65
+ Copyright Holder. This restriction only applies to the primary font name as
66
+ presented to the users.
67
+
68
+ 4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
69
+ Software shall not be used to promote, endorse or advertise any
70
+ Modified Version, except to acknowledge the contribution(s) of the
71
+ Copyright Holder(s) and the Author(s) or with their explicit written
72
+ permission.
73
+
74
+ 5) The Font Software, modified or unmodified, in part or in whole,
75
+ must be distributed entirely under this license, and must not be
76
+ distributed under any other license. The requirement for fonts to
77
+ remain under this license does not apply to any document created
78
+ using the Font Software.
79
+
80
+ TERMINATION
81
+ This license becomes null and void if any of the above conditions are
82
+ not met.
83
+
84
+ DISCLAIMER
85
+ THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
86
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
87
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
88
+ OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
89
+ COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
90
+ INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
91
+ DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
92
+ FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
93
+ OTHER DEALINGS IN THE FONT SOFTWARE.
@@ -0,0 +1,93 @@
1
+ Copyright 2020 The Fraunces Project Authors (github.com/undercasetype/Fraunces) Fraunces-Italic[SOFT,WONK,opsz,wght].ttf: Copyright 2020 The Fraunces Project Authors (github.com/undercasetype/Fraunces)
2
+
3
+ This Font Software is licensed under the SIL Open Font License, Version 1.1.
4
+ This license is copied below, and is also available with a FAQ at:
5
+ http://scripts.sil.org/OFL
6
+
7
+
8
+ -----------------------------------------------------------
9
+ SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
10
+ -----------------------------------------------------------
11
+
12
+ PREAMBLE
13
+ The goals of the Open Font License (OFL) are to stimulate worldwide
14
+ development of collaborative font projects, to support the font creation
15
+ efforts of academic and linguistic communities, and to provide a free and
16
+ open framework in which fonts may be shared and improved in partnership
17
+ with others.
18
+
19
+ The OFL allows the licensed fonts to be used, studied, modified and
20
+ redistributed freely as long as they are not sold by themselves. The
21
+ fonts, including any derivative works, can be bundled, embedded,
22
+ redistributed and/or sold with any software provided that any reserved
23
+ names are not used by derivative works. The fonts and derivatives,
24
+ however, cannot be released under any other type of license. The
25
+ requirement for fonts to remain under this license does not apply
26
+ to any document created using the fonts or their derivatives.
27
+
28
+ DEFINITIONS
29
+ "Font Software" refers to the set of files released by the Copyright
30
+ Holder(s) under this license and clearly marked as such. This may
31
+ include source files, build scripts and documentation.
32
+
33
+ "Reserved Font Name" refers to any names specified as such after the
34
+ copyright statement(s).
35
+
36
+ "Original Version" refers to the collection of Font Software components as
37
+ distributed by the Copyright Holder(s).
38
+
39
+ "Modified Version" refers to any derivative made by adding to, deleting,
40
+ or substituting -- in part or in whole -- any of the components of the
41
+ Original Version, by changing formats or by porting the Font Software to a
42
+ new environment.
43
+
44
+ "Author" refers to any designer, engineer, programmer, technical
45
+ writer or other person who contributed to the Font Software.
46
+
47
+ PERMISSION & CONDITIONS
48
+ Permission is hereby granted, free of charge, to any person obtaining
49
+ a copy of the Font Software, to use, study, copy, merge, embed, modify,
50
+ redistribute, and sell modified and unmodified copies of the Font
51
+ Software, subject to the following conditions:
52
+
53
+ 1) Neither the Font Software nor any of its individual components,
54
+ in Original or Modified Versions, may be sold by itself.
55
+
56
+ 2) Original or Modified Versions of the Font Software may be bundled,
57
+ redistributed and/or sold with any software, provided that each copy
58
+ contains the above copyright notice and this license. These can be
59
+ included either as stand-alone text files, human-readable headers or
60
+ in the appropriate machine-readable metadata fields within text or
61
+ binary files as long as those fields can be easily viewed by the user.
62
+
63
+ 3) No Modified Version of the Font Software may use the Reserved Font
64
+ Name(s) unless explicit written permission is granted by the corresponding
65
+ Copyright Holder. This restriction only applies to the primary font name as
66
+ presented to the users.
67
+
68
+ 4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
69
+ Software shall not be used to promote, endorse or advertise any
70
+ Modified Version, except to acknowledge the contribution(s) of the
71
+ Copyright Holder(s) and the Author(s) or with their explicit written
72
+ permission.
73
+
74
+ 5) The Font Software, modified or unmodified, in part or in whole,
75
+ must be distributed entirely under this license, and must not be
76
+ distributed under any other license. The requirement for fonts to
77
+ remain under this license does not apply to any document created
78
+ using the Font Software.
79
+
80
+ TERMINATION
81
+ This license becomes null and void if any of the above conditions are
82
+ not met.
83
+
84
+ DISCLAIMER
85
+ THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
86
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
87
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
88
+ OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
89
+ COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
90
+ INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
91
+ DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
92
+ FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
93
+ OTHER DEALINGS IN THE FONT SOFTWARE.