v0.3.0

[0.3.0] - 2026-10-06

The Page Spec stays version: 1, and every spec that was valid in 0.2.0 stays
valid. These changes alter existing behaviour or output on purpose:

• --theme (and the theme render option) now replaces the spec's
  theme.recipes as well as its tokens. Before, spec recipes applied
  regardless.
• Every gallery thumbnail opens a full-size lightbox. There is no author
  flag, so every page with a gallery emits new markup, CSS and runtime.
• Tabs no longer fire select for the initial tab when the page loads, so page
  state keeps its declared initial values.
• A remote video poster that the network policy blocks is a validate error
  (POLICY_VIOLATION at the poster path), not a compile failure at $.
• Pages with tabs or a carousel change markup and CSS so every panel and slide
  reads without scripts and in print.
• catalog text is grouped by category, and catalog --json prints one block
  per line with new category and tags fields.
• The Claude Code and Codex plugin manifests link to https://render.agentkit.best, and the Codex plugin shows an icon, a logo and the brand colour in the plugin directory.
• The benchmarks are measured against AgentKit 9e322f928. The legacy baseline no longer counts the slide guide for document tasks (AgentKit loads it for --slides only), so its per-task mean is ~25.0k tokens, not ~33.7k. render-benchmark.mjs measures the ak-render skill route per task: the AgentKit shared HTML contract, the skill, catalog, and describe --json for each block type the task's fixture compiles to. It fails when the AgentKit checkout is missing. Presentation context now drops 64–68% (previously reported as 87–88%). The typical-task estimate is 54% with full contracts and 66% with describe --compact, which counts the shared contract too (previously 65% and 75%). agent-token-cost.mjs --reuse-legacy reruns that estimate from recorded corpus measurements. The README and landing page use the new figures.
• The landing page shows what the compiler saves an agent (measured and estimated token figures, kept apart), each component crop beside the fixture YAML that produced it, and a gallery of every demo page. The README gains a token cost section.

Added

• Rich composition: a tab panel, an accordion section, a carousel slide and a bento tile hold child blocks in items[i].blocks (up to 12, or 6 in a bento tile). Any block may nest except page, section and hero, and tabs may nest in tabs. An item's text, and a bento tile's title, are optional when the item has blocks; an item with neither is an error at its path.
• Nested slots with accepts and parents rules. Diagnostics carry the nested JSON path, and nested blocks count toward the block limit.
• grid-item places blocks on a 12-track grid with span, tabletSpan, mobileSpan, rowSpan, start and align. grid.columns takes 1–12 or auto (with minItemWidth), grids take gap and align, and stack takes align.
• Semantic page layouts: sidebar-layout (a sidebar beside the main blocks, on either side), main-aside (an aside that stays in view on wide screens) and rail-layout (a compact rail, a labelled <nav> when it holds only links or toolbars).
• Datasets: top-level datasets, and dataRef, inline data and a bounded transform (filter, groupBy, sort, select, limit) on blocks that take data. Values format through one locale-free formatter (number, integer, compact, percent, currency, duration, bytes, date); percent takes 87 for "87%". See docs/data-and-state.md.
• visibleWhen shows a block only while a state value matches (equals, notEquals, in, notIn, truthy, falsy). The compiler emits the initial view, so the page reads correctly without scripts and in print.
• Native input controls select, radio-group, checkbox, switch, text-input, number-input and date-input. Each has a visible label, writes one value to state.<key> through bind, and fires change with its value.
• filter-bar filters a data-table, kanban or log-viewer with 1–8 controls, each naming a row field and a match. It adds an announced result count and a Reset button; select and radio-group can list the target's values with optionsFrom. A data-table that a filter-bar targets renders no search box, row count or "no match" note of its own, so two filters never fight over the same rows; put free-text search in the bar as a search child.
• data-table: a typed, sortable table bound to a dataset. Column types text, number, percent (alias percentage), currency, date, badge, link, progress and sparkline; search past 10 rows (unless a filter-bar targets the table), a sticky header past 12, labelled cards on phones, and the full table in authored order without scripts or in print.
• Chart kinds scatter, histogram, stacked-bar, stacked-bar-100, heatmap, waterfall, funnel, gauge and treemap. A chart can bind rows and read them through the x, y, series: { field } and value encodings, and takes markers, annotations, sort and a gauge target. A bound chart's fallback table comes from the bound rows. Charts that use labels and series render the same markup as before.
• Engineering widgets: kanban, roadmap, test-results, log-viewer, api-endpoint and schema-viewer.
• Evidence widgets: benchmark-comparison (computed delta, change and verdict; currency is set once for the whole block, not per metric), metric-breakdown, annotated-image and references (stable #ref-<id> anchors).
• Product widgets: pricing, feature-matrix, testimonial (two or more quotes form a grid), logo-cloud, people and calendar (weeks start on Monday; weekStart: sunday changes that).
• Theme recipes restyle components through closed enums for cards, sections, tables, charts, hero, metrics, media and callouts. A preset, a preset file or the spec's theme.recipes selects them. See docs/themes.md.
• Four built-in presets: data-console, executive-report, product-studio and research-notebook. They reuse the bundled faces. Every built-in preset is tested for WCAG 2.2 contrast in both schemes.
• An inline spec theme accepts theme.dark, dark-scheme token overrides.
• Catalog discovery: every block has a category and tags. ak-render catalog --category <c> lists one category, ak-render search-catalog <terms...> ranks block types by intent words, and ak-render describe <type...> --compact returns up to 12 contracts with one line per prop; a shape repeated within a contract reads like <field> and a repeated long enum enum as <field>. Row-filtering words rank filter-bar first. MCP gains search-catalog, catalog{category} and describe{types, compact}, on the stdio and the remote server; the remote search-catalog needs no token. The library exports searchCatalog and describeMany.
• Page recipes: ak-render recipes [--json] lists ten starter specs (architecture-review, benchmark-report, case-study, dashboard, decision-memo, implementation-plan, incident-report, product-showcase, release-recap, research-report), and ak-render recipe <name> prints one as YAML, or the full record with --json. An unknown name exits 1 and lists the allowed names; a missing name exits 2. Each recipe validates with no errors or warnings, compiles deterministically, stays within 3,000 bytes of YAML and loads nothing remote. MCP serves them as recipes and recipe{name} on the stdio and the remote server, and the library as recipes(), recipe(name) and the PageRecipe and PageRecipeSummary types; an unknown name throws SPEC_VALIDATION_ERROR at path name with details.allowed.
• pnpm recipes:generate embeds the recipe YAML in src/recipes/recipes.generated.ts, and pnpm recipes:check, part of pnpm verify, fails when that module is stale.
• The library exports BLOCK_CATEGORIES, THEME_RECIPE_SPECS, VALUE_FORMATS and the MaterializedData, DataRow and DataScalar types.
• Remote MCP over Streamable HTTP at https://render.agentkit.best/mcp, served by the cloud Worker. It lists the same tools as ak-render mcp: catalog, search-catalog, describe, recipes, recipe, validate, render and themes. A remote render takes no out: it compiles through the same path as POST /v1/render (byte-identical HTML), stores the page and returns the summary plus artifactUrl and expiresAt, never the HTML. The artifact lives one hour, or becomes an expiring share with share: true (needs the share scope). catalog, search-catalog, describe, recipes, recipe and themes answer without a token; validate and render need an AgentKit bearer and count against the same per-subject rate limits as REST.
• The MCP server is split into transport-independent modules under src/mcp/: protocol vocabulary, one set of tool contracts, JSON-RPC routing, the stdio transport, and a Fetch-API Streamable HTTP transport the Worker imports. ak-render mcp answers byte for byte as before.
• GET /v1/artifact/:id serves the short-lived artifact a remote MCP render stored.
• scripts/cloud-smoke.mjs smoke-tests a deployed renderer (MCP and REST, share lifecycle, exports) with BASE_URL and an optional TOKEN; the manual cloud deploy workflow runs it after deploying.
• benchmarks/agent-token-cost.mjs estimates the tokens of a page task end to end: guidance read, output written and what returns into context, against a corpus of hand-written HTML passed with --legacy-html. Results are in docs/artifacts/agent-token-cost.md, with the corpus recorded by anonymous label. --legacy-from <artifact.json> refreshes the artifact from the recorded legacy rows without the private corpus, and a second typical-task row measures the compact workflow (`describe <types...> --comp...

v0.2.0

[0.2.0] - 2026-10-05

Every emitted page changes in this release: new styles, embedded fonts, and a
CSP that allows font-src data: on pages that carry a face.

Changed

• Polished the emitted artifacts:
  • Heading sizes now follow the font-scale token.
  • Spacing is driven by density, with larger gaps at section breaks.
  • The hero carries an accent eyebrow rule, and the theme toggle is a right-aligned pill.
  • Callouts, badges and tables are tinted, buttons and tabs have hover and press states, and all transitions use the motion tokens.
  • Mobile touch targets are 44px.
• 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).
• Elevation shadows are layered. A table title no longer prints twice; its caption is kept for screen readers only.
• Artifacts now emit og:title, og:type, og:description and twitter:card from the spec meta.
• The gallery index is now one card per artifact.
• Redesigned the component system in the emitted stylesheet:
  • 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.
  • The hero title is larger, and the page carries a faint accent wash at the top.
  • Stats share one framed panel with hairline dividers. Steps use numbered rings on a connector, and timeline dots carry a halo.
  • Callouts and alerts carry a tone glyph instead of a side stripe. Quotes use a hanging quote mark.
  • 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.
  • 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.
  • In dark schemes, surfaces get a top-lit sheen, because the fixed elevation shadows are invisible on a dark page.
• 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.
• Feature stylesheets moved to src/render/feature-styles.ts; styles.ts re-exports them.
• 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).
  • 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.
  • 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.
  • Artifacts grow by roughly 30–60 kB per page. A custom font stack that names no bundled AK family embeds nothing.
  • The licences ship in assets/fonts/<family>/OFL.txt and in the npm package. Each @font-face carries a notice comment.
• Blueprint's light scheme is warmer and higher-contrast: a drafting-paper background (#f4f2ed), near-black text, and a cobalt accent (#1d4fd7).
• 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.
• The browser frame styles moved to the base sheet, so the hero can use them.

Added

• 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.
• 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.
• Pass - as the spec path to compile or validate a spec from standard input. Diagnostics name the source <stdin>.
• llms.txt (shipped in the package) and docs/agent-guide.md: the agent loop, a minimal spec, and the MCP client config.
• 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.
• 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.
• 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.
• 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.
• 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.
• pnpm fonts:generate and pnpm fonts:check regenerate and check the embedded font module.
• 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>.
• A reading-progress rail.
• A colophon footer with a back-to-top link.
• 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.
• Charts:
  • Area fills are gradients.
  • Bars and points reveal their values on hover or focus.
  • The cartesian viewBox is 800×300, and on narrow screens the chart scrolls sideways instead of shrinking its text.
• Tables:
  • Numeric columns align right.
  • Diff status, risk levels and review kinds render as toned badges.
  • Diff line counts are signed and colored.
• External links in prose carry a ↗ marker.
• 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.
• A signature style layer (src/render/signature-styles.ts):
  • a fluid display-size hero title and a staggered hero entrance;
  • balanced headings;
  • drawn link underlines;
  • cards that end in a link become a single lifted target with an arrow CTA;
  • larger stat figures and a subtle top light on primary buttons.
• Bar charts use per-series gradients.
• Eight showcase blocks:
  • bento, a mosaic of tiles with sizes, images and display figures;
  • marquee, an accessible looping ticker;
  • terminal, a typed session with a copy control;
  • file-tree, built from flat paths with status;
  • before-after, an image slider driven by a native range input, which adds the before-after runtime feature;
  • kpi, metrics with a delta, a good/bad verdict and a sparkline;
  • showcase, copy beside a capture in browser chrome;
  • checklist, with a done count and a progress meter.
    Each has its own tree-shaken feature sheet.
• An effects layer (src/render/effects-styles.ts):
  • a theme-tinted hero aurora;
  • a word-by-word hero title reveal;
  • a film-grain texture;
  • a pointer spotlight on cards;
  • count-up for numeric stats and KPIs;
  • scroll-linked settling of framed images;
  • a sweep on primary buttons.
    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.
• Real demo media in fixtures/assets: screenshots and a 41s screen recording of the compiled gallery, captured by scripts/capture-demo-media.mjs.
• 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.

Fixed

• 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.
• 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".
• loadTheme reports a non-object tokens or dark value as a POLICY_VIOLATION render error instead of throwing a TypeError.
• File trees order names by code point, so the order no longer depends on the runtime's collation.
• 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.
• A bento tile with src now requires alt; an explicit alt: "" marks a decorative image.
• The terminal's caption is a direct child of its figure, and the figure is named by the title alone.
• Checklist, browser-frame (hero shot and ...

v0.1.1-next.1

[0.1.1-next.1] - 2026-09-22

Prerelease published to exercise the trusted-publishing release path end to end:
the tag run publishes over GitHub OIDC with provenance and no stored token. No
functional changes; the compiler behaves as 0.1.0.

v0.1.0

[0.1.0] - 2026-09-22

First public release, published to npm as @bestagentkits/render.

Added

• Repository baseline for the public AK Render package: MIT license,
  contribution guide, security policy, release policy, and CI covering lint,
  typecheck, unit tests, browser tests, build, and package smoke.
• TypeScript ESM package skeleton targeting Node >= 20.11, with a library entry
  point, an ak-render CLI bin, and a pack/install smoke test that exercises
  both surfaces from a throwaway consumer project.
• Architecture decision record
  (ADR 0001) fixing the Page
  Spec versus internal IR split, catalog/registry separation, trusted
  interaction runtime, theme trust model, local/cloud boundary, and the
  optional AgentKit adapter model.
• Fixture corpus representing the plan, explain, recap, diff, dashboard, media,
  and interactive page classes.
• Reproducible baseline measurement of the legacy HTML presentation guidance
  currently carried in agent model context, with captured results under
  docs/artifacts/.