@bestagentkits/render 0.1.1-next.1 → 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.
- package/CHANGELOG.md +109 -0
- package/README.md +189 -34
- package/assets/fonts/bricolage-grotesque/OFL.txt +93 -0
- package/assets/fonts/fraunces/OFL.txt +93 -0
- package/assets/fonts/geist/OFL.txt +93 -0
- package/assets/fonts/inter-tight/OFL.txt +93 -0
- package/assets/fonts/jetbrains-mono/OFL.txt +93 -0
- package/assets/fonts/plus-jakarta-sans/OFL.txt +93 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +51 -10
- package/dist/cli.js.map +1 -1
- package/dist/mcp-server.d.ts +37 -0
- package/dist/mcp-server.d.ts.map +1 -0
- package/dist/mcp-server.js +274 -0
- package/dist/mcp-server.js.map +1 -0
- package/dist/registry/roster.d.ts +1 -1
- package/dist/registry/roster.d.ts.map +1 -1
- package/dist/registry/roster.js +222 -6
- package/dist/registry/roster.js.map +1 -1
- package/dist/render/block-helpers.d.ts +52 -0
- package/dist/render/block-helpers.d.ts.map +1 -0
- package/dist/render/block-helpers.js +113 -0
- package/dist/render/block-helpers.js.map +1 -0
- package/dist/render/blocks.d.ts +3 -4
- package/dist/render/blocks.d.ts.map +1 -1
- package/dist/render/blocks.js +126 -121
- package/dist/render/blocks.js.map +1 -1
- package/dist/render/charts.d.ts +5 -0
- package/dist/render/charts.d.ts.map +1 -1
- package/dist/render/charts.js +205 -90
- package/dist/render/charts.js.map +1 -1
- package/dist/render/derived-variables.d.ts +17 -0
- package/dist/render/derived-variables.d.ts.map +1 -0
- package/dist/render/derived-variables.js +17 -0
- package/dist/render/derived-variables.js.map +1 -0
- package/dist/render/diagram-fallback.d.ts +25 -0
- package/dist/render/diagram-fallback.d.ts.map +1 -0
- package/dist/render/diagram-fallback.js +86 -0
- package/dist/render/diagram-fallback.js.map +1 -0
- package/dist/render/document.d.ts +4 -0
- package/dist/render/document.d.ts.map +1 -1
- package/dist/render/document.js +34 -6
- package/dist/render/document.js.map +1 -1
- package/dist/render/effects-styles.d.ts +14 -0
- package/dist/render/effects-styles.d.ts.map +1 -0
- package/dist/render/effects-styles.js +39 -0
- package/dist/render/effects-styles.js.map +1 -0
- package/dist/render/embedded-fonts.generated.d.ts +22 -0
- package/dist/render/embedded-fonts.generated.d.ts.map +1 -0
- package/dist/render/embedded-fonts.generated.js +59 -0
- package/dist/render/embedded-fonts.generated.js.map +1 -0
- package/dist/render/feature-styles.d.ts +14 -0
- package/dist/render/feature-styles.d.ts.map +1 -0
- package/dist/render/feature-styles.js +161 -0
- package/dist/render/feature-styles.js.map +1 -0
- package/dist/render/font-faces.d.ts +22 -0
- package/dist/render/font-faces.d.ts.map +1 -0
- package/dist/render/font-faces.js +60 -0
- package/dist/render/font-faces.js.map +1 -0
- package/dist/render/outline.d.ts +21 -0
- package/dist/render/outline.d.ts.map +1 -0
- package/dist/render/outline.js +44 -0
- package/dist/render/outline.js.map +1 -0
- package/dist/render/render.d.ts.map +1 -1
- package/dist/render/render.js +53 -10
- package/dist/render/render.js.map +1 -1
- package/dist/render/runtime.d.ts.map +1 -1
- package/dist/render/runtime.js +184 -10
- package/dist/render/runtime.js.map +1 -1
- package/dist/render/showcase-blocks.d.ts +47 -0
- package/dist/render/showcase-blocks.d.ts.map +1 -0
- package/dist/render/showcase-blocks.js +349 -0
- package/dist/render/showcase-blocks.js.map +1 -0
- package/dist/render/showcase-styles.d.ts +15 -0
- package/dist/render/showcase-styles.d.ts.map +1 -0
- package/dist/render/showcase-styles.js +217 -0
- package/dist/render/showcase-styles.js.map +1 -0
- package/dist/render/signature-styles.d.ts +18 -0
- package/dist/render/signature-styles.d.ts.map +1 -0
- package/dist/render/signature-styles.js +41 -0
- package/dist/render/signature-styles.js.map +1 -0
- package/dist/render/styles.d.ts +18 -9
- package/dist/render/styles.d.ts.map +1 -1
- package/dist/render/styles.js +224 -128
- package/dist/render/styles.js.map +1 -1
- package/dist/render/surface-styles.d.ts +24 -0
- package/dist/render/surface-styles.d.ts.map +1 -0
- package/dist/render/surface-styles.js +41 -0
- package/dist/render/surface-styles.js.map +1 -0
- package/dist/render/verify.d.ts.map +1 -1
- package/dist/render/verify.js +30 -0
- package/dist/render/verify.js.map +1 -1
- package/dist/spec/normalize.d.ts.map +1 -1
- package/dist/spec/normalize.js +32 -0
- package/dist/spec/normalize.js.map +1 -1
- package/dist/theme/load-theme.d.ts +2 -2
- package/dist/theme/load-theme.d.ts.map +1 -1
- package/dist/theme/load-theme.js +46 -10
- package/dist/theme/load-theme.js.map +1 -1
- package/dist/theme/presets.d.ts +4 -3
- package/dist/theme/presets.d.ts.map +1 -1
- package/dist/theme/presets.js +35 -18
- package/dist/theme/presets.js.map +1 -1
- package/dist/theme/tokens.d.ts.map +1 -1
- package/dist/theme/tokens.js +4 -4
- package/dist/theme/tokens.js.map +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.d.ts.map +1 -1
- package/dist/version.js +1 -1
- package/dist/version.js.map +1 -1
- package/llms.txt +25 -0
- package/package.json +9 -3
package/CHANGELOG.md
CHANGED
|
@@ -9,6 +9,115 @@ 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
|
+
|
|
12
121
|
## [0.1.1-next.1] - 2026-09-22
|
|
13
122
|
|
|
14
123
|
Prerelease published to exercise the trusted-publishing release path end to end:
|
package/README.md
CHANGED
|
@@ -1,37 +1,192 @@
|
|
|
1
1
|
# @bestagentkits/render
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
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
|
+
[](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,
|
|
8
|
-
|
|
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
|
|
160
|
+
npx skills add bestagentkits/ak-render
|
|
12
161
|
```
|
|
13
162
|
|
|
14
|
-
|
|
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
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
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
|
-
|
|
170
|
+
**Codex and ChatGPT**, as a plugin:
|
|
26
171
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
172
|
+
```bash
|
|
173
|
+
codex plugin marketplace add bestagentkits/ak-render
|
|
174
|
+
codex plugin add ak-render@ak-render
|
|
175
|
+
```
|
|
31
176
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
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
|
|
68
|
-
|
|
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
|
-
|
|
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.
|