Skip to content

bestagentkits/ak-render

v0.3.0MIT

Turn plans, reports, recaps, diff reviews, dashboards and explainers into one polished, offline, self-contained HTML page from a short YAML Page Spec, without hand-writing HTML.

Changelog

All notable changes to this project are documented in this file.

The format follows Keep a Changelog and this project adheres to Semantic Versioning. Release mechanics and the compatibility contract live in docs/release-policy.md.

[Unreleased]

3D v1

3D v1 is complete: 14 widgets (scene-3d, model-3d, network-3d, scatter-3d, bars-3d, globe-3d, product-3d, particles-3d, shader-3d, text-3d, point-cloud-3d, timeline-3d, morph-3d, terrain-3d), each drawn by the shared inlined three.js runtime and backed by a compiler-projected static drawing for no-JS, no-WebGL, print and reduced motion. The gallery's 3D section shows every widget; the docs hub is docs/3d.md with scenes, effects and data recipes. The export matrix records PNG and PDF export per widget, and pnpm bench:3d now measures one fixture per widget (docs/artifacts/benchmark-3d.md).

Known limits:

  • Cloud export is unverified until Browser Run credentials are available; local export is the verified path.
  • PNG export of globe-3d and product-3d is not byte-identical across repeated runs (GPU sampling); compiled HTML stays deterministic.
  • Uploading 3D assets to R2 was dropped: pages embed their model, font and data assets, so they stay offline and need no storage.
  • model-3d does not yet react to WebGL context loss (#177).

Migration: no spec changes are needed; existing specs compile unchanged and 3D blocks are opt-in. Rollback: pin the previous release, or remove 3D blocks from a spec.

Added

  • social-post and social-feed blocks: one post, or up to 24 in the supplied order, from X, Threads, Bluesky, Mastodon, LinkedIn, YouTube, Reddit, Hacker News or another site, drawn as static cards from supplied data with no frame, platform script or beacon. A post carries its author, text, an ISO date shown as written in a <time>, up to four media items (image under the images capability, video under media), compact counts with platform nouns, a reply handle and one quoted post. A blocked avatar falls back to initials, blocked media to a described fallback with a link to the post, and a blocked poster is dropped, so a deny page still validates. validate warns on a URL off the platform's hosts and on expiring signed Meta CDN URLs. See docs/media-policy.md.

  • Providers x, threads, bluesky, linkedin, reddit and hackernews for policy.network.providers. A provider may now declare asset hosts, the CDNs its avatars, images and video files come from (youtube gains ytimg.com and yt3.ggpht.com); an asset that names no provider passes a declared allowlist from those hosts too. The new names are also accepted by the provider prop of video and audio, which link out to the post as they do for every provider. See docs/media-policy.md.

  • Enum props may declare aliases: a common name for an allowed value is a safe enum/alias fix that repair applies, such as platform: twitter to x.

  • Claude plugin folder. plugins/ak-render/ is a self-contained plugin for the Claude plugin directory: a manifest that starts the pinned @bestagentkits/render MCP server, a skill written for that version with report, dashboard and architecture review examples, an icon, screenshots, a README with a supported-surface matrix, privacy and support details, and the license. The repository marketplace now installs that folder instead of the repository root. pnpm test:plugin smoke-tests it against the published package. See docs/claude-plugin.md.

  • shader-3d block: five closed shader presets (noise, fresnel, hologram, distortion, dissolve) on a sphere, torus, torus knot or plane, with typed intensity, scale, progress and speed dials, theme tones and a seed. Post-processing is a closed chain (bloom, chromatic, scanlines, grain, vignette) checked against each preset. Built-in preset buttons and sliders, and a bind map to state, change uniforms live and fire change. Shader source is rejected anywhere in a spec; every line of GLSL is compiler-owned. An SVG poster shaded by the same formula covers no-JS, no-WebGL and print, reduced motion holds that frame and a Pause button stops the motion. The gallery's 3D section shows the presets and a live reveal. See docs/3d-effects.md.

  • text-3d block: extruded, bevelled lettering from two bundled SIL OFL fonts (Bricolage Grotesque, Fraunces) with satin, metal, chrome, glass and neon finishes, depth and bevel, and rise, wave, float and spin motion by character or word. Text is NFC-normalized across Latin, Latin Extended and Vietnamese; a character the font lacks draws its box, warns with the code point and is spelled out in the caption. An SVG poster of the same layout covers no-JS, no-WebGL and print, and the gallery's 3D section shows a headline and the finishes. See docs/3d-scenes.md.

  • particles-3d block: seeded particle effects from six presets (galaxy, nebula, fountain, snow, fireflies, vortex) with typed emitter shape, force and noise fields, color and size over life, count and speed overrides. The same seed draws the same frame; a GPU path (up to 20,000 particles) and a bounded CPU path (up to 4,000) share one closed-form simulation, step down by halves when frames run slow, pause offscreen and release every resource on unmount. An SVG poster of the same frame covers no-JS, no-WebGL and print; reduced motion holds it still and a Pause button stops the motion. export3dPosterSvg exports that poster with its night sky, and the gallery's 3D section shows the galaxy. See docs/3d-effects.md.

  • globe-3d block: latitude/longitude markers and great-circle arcs on a dotted globe drawn from bundled Natural Earth land (public domain), with an atmosphere, a sunlit day side and a night side. Markers and arcs sit on layers the reader can hide, a time step filters them (bound to page state), nearby markers merge into counts when zoomed out, and choosing a place writes page state and flies the camera to it. Compact markerList and arcList lines carry up to 1,000 markers and 500 arcs. A static SVG globe and tables of every place (coordinates, layer, value, time) and route (great-circle distance) carry it without JS, without WebGL and in print. See docs/3d-data.md.

  • product-3d block: a studio-lit product from typed parts with a finish dropdown bound to page state, numbered hotspots that fly the camera to them, and an exploded view; a drawn plan with the same pins, the finish list and the hotspot list carry it without JS, without WebGL and in print. Product parts add the rounded-box and capsule shapes. See docs/3d-scenes.md.

  • point-cloud-3d block: a scanned point cloud at true proportions from a local .xyz/.csv/.txt file (up to 100,000 points, read inside the spec directory) or inline columns (up to 20,000), with intensity or height colour, a clip box from axis min/max, a compile-time level-of-detail order and a budget the status line always reports, spatial picking that writes bind and shows the authored coordinates with units, and a Cut above section slider. Oversized or malformed files fail with the line number instead of being truncated. A sampled SVG drawing, the selected point, per-column statistics over every point and a data table carry it without JS, without WebGL and in print. See docs/3d-data.md.

  • timeline-3d block: up to 200 milestones in order along a lit path in space (a ribbon for a few, a rising spiral for many), with a camera that flies to each one, Prev/Next, a scrubber, a one-tab-stop milestone list, canvas keys, a narrative card and a bind state path. Dates out of order are a compile error. A drawing of the path, the card and the ordered list carry it without JS, without WebGL and in print; reduced motion moves the camera at once. See docs/3d-data.md.

  • morph-3d block: one studio-lit surface that morphs between two to six typed target shapes (closed: sphere, cube, capsule, cylinder, cone, gem, blob, star; rings: torus, knot, twist) sampled on one shared grid per topology, with smooth, spring, snap or linear easing, a loop, once or manual timeline, and target buttons, canvas keys and a bind state path that choose a target. Mixing a closed shape with a ring is a compile error naming the invalid topology. A shaded drawing of the current target and the target list carry it without JS, without WebGL and in print; reduced motion lands every morph at once and a Pause button freezes a playing timeline. See docs/3d-effects.md.

  • terrain-3d block: a heightmap block from rows of elevations (up to 256 x 256) or a seeded relief of typed landforms (peak, ridge, valley, crater, basin), drawn to true scale times a vertical exaggeration when the ground's width is known, with contour lines at a round interval (heavier every fifth), five colour ramps, soil walls and numbered places that list their elevation read from the heightmap. A flyover tours the places with a Pause button; choosing a place (list, pin, canvas keys or a bind state path) flies to it and fires select. A shaded drawing of the block under the live camera, the elevation legend and the place list carry it without JS, without WebGL and in print. The input bounds let a heights grid and its rows reach 256 items. See docs/3d-data.md.

  • edge-flow now flows on every diagram in view and keeps flowing when the reader selects a node; every diagram in the showcase uses it except sequence playback.

  • edge-flow diagram motion recipe: dashed relationships march and a glowing pulse travels each one while the diagram is in view, with a Pause flow control; the governor keeps it to one flowing diagram per page and stops it on selection, reduced motion, print and hidden tabs. The diagram showcase opens with a deploy pipeline drawn as dark cards with a mono subtitle, a glowing hub and a status pill.

  • scene-3d block: a nested 3D scene as typed data (primitive shapes, material and lighting presets, camera, timeline, views) drawn live by a shared, inlined three.js runtime and backed by a compiler-projected SVG plan for no-JS, print and reduced motion. Picking an object writes page state. See docs/3d.md.

  • ak-render export <spec> --format png|pdf: local export through an installed Chrome, Edge or Playwright Chromium (never downloaded) that captures each 3D scene's live WebGL frame and fails with a stable code instead of exporting the static plan. ak-render export doctor reports the browser and its WebGL 2 support.

  • exportDiagramSvg writes a standalone, deterministic SVG of a contract 2 drawing; window.akRenderDiagram.freeze() settles diagram motion for capture; Motion Studio accepts a diagram adapter and inspects the drawing. See docs/diagram-adapter.md.

  • 22 golden diagram cases with determinism, zero-fabrication, geometry, accessibility, offline, print, no-JS, preset and motion checks, and a recorded compile time, DOM size and memory baseline. See docs/diagram-adapter.md.

  • Diagram motion recipes for contract 2 drawings: edge-trace, signal-relay, node-activation and sequence-playback. One governor per page plays one diagram at a time, follows the viewer's selection, and stops on hide, theme switch, reduced motion and print; sequence playback never starts itself and names each step in a status line. See docs/motion.md.

  • Diagram viewer for adapter contract 2 drawings: select a node to see its connections, Shift+select to trace a directed route, show everything downstream, inspect a relationship, find a node (diacritic-insensitive), zoom, fit and pan, with the selection kept in the link. Controls appear only for the capabilities the adapter declares, ship hidden without script and drop out of print.

  • Diagram adapter contract 2. An adapter that declares contract: 2 may return { svg, manifest, capabilities }: the manifest names which drawn element is which node, relationship and group of the spec, and the capabilities say which viewer interactions the drawing supports. The compiler rejects a manifest that names anything the spec does not declare, writes its own data-ak-* hooks with labels taken from the spec, and prefixes every id in the drawing with the panel scope. Contract 1 adapters are unchanged. See docs/diagram-adapter.md.

  • ChatGPT plugin package. packaging/chatgpt/ connects ChatGPT to the hosted MCP server at https://render.agentkit.best/mcp with AgentKit OAuth, so no Node or npm is needed; the local stdio manifests are unchanged. pnpm plugin:chatgpt checks it against the Agent Plugins schemas and the directory limits and writes a deterministic upload ZIP to .tmp/chatgpt-plugin/. The Worker serves the portal's domain-verification token from the OPENAI_APPS_CHALLENGE secret at /.well-known/openai-apps-challenge, and the cloud smoke checks tool hints, the OAuth client mode, artifact content type, truthful render errors and expiry. See apps/cloud/README.md.

  • MCP tool annotations. Every tool in tools/list, local and remote, states readOnlyHint, destructiveHint and openWorldHint.

  • Remote artifact export. The hosted MCP server adds artifact-export: given an artifactUrl, share URL or id the caller owns, it returns signed URLs (HMAC-SHA256, one hour, never past the page's own expiry) for the HTML, a PNG, a PDF or the retained spec, never the bytes. PNG and PDF are made once through Browser Run and reused. Remote render takes retainSpec: true to keep the spec source with the page's owner and expiry; revoking a share deletes its spec and exports. Deployments need the DOWNLOAD_SIGNING_KEY secret; without it the tool answers DOWNLOAD_UNAVAILABLE. See apps/cloud/README.md.

  • Visual audit. ak-render audit-ui <spec|page.html> checks the compiled artifact. The quick preset (default) reads the resolved theme and the markup without a browser: theme text contrast, wide tables and long chart labels. --preset publication adds a headless Chromium pass at 375, 768 and 1440 px in light and dark, then no-JS, reduced motion and print: horizontal overflow (also with disclosures open), clipped chart labels, rendered text contrast, small text, touch targets, broken images, runtime errors, a tab/disclosure/theme-toggle smoke test, content hidden without JavaScript and motion under reduced motion. It runs under a time budget (--timeout), blocks every network request, runs only the runtime it compiled (HTML from elsewhere runs with JavaScript off) and writes one screenshot per check with --evidence-dir. Findings carry a rule, severity, spec path, viewport, evidence and fix; --fail-on gates CI and an incomplete run fails the gate. The MCP servers add audit-ui (quick only remotely); the library exports auditUi, auditUiQuick and UI_RULES. See docs/audit-ui.md.

  • Derived metrics and KPI citations. transform.derive adds fields from a closed list of operations (ratio, percentOf, delta, percentChange, share, cumulative), and on a data-table transform.rollup adds a sum or mean total row as the table footer; neither accepts an expression. Value formats take signed: true for a leading + (not the benchmark and breakdown widgets, which sign their own differences). A kpi item may cite a dataset field with an aggregate: the compiler fills an omitted value from it, or warns (rule: kpi-cite) when the written value disagrees with the data. value is now optional on a kpi item that has a cite. See docs/data-and-state.md.

  • Compose. ak-render compose input.yaml --out page.html builds a whole page from a typed intent and content slots, with no Page Spec to write. The first intent is investment-report (thesis and recommendation, key facts, metrics, scenario chart and table over one shared dataset, risks, milestones, sources). Composition is deterministic, checks every slot with a JSON path diagnostic, expands into ordinary blocks and compiles through the same compile(), so the HTML is byte-identical to rendering the emitted spec (--spec-out, --dry-run). compose intents --json lists intents and their content schemas. The library exports compose(), composeSpec(), composeIntents() and composeInputJsonSchema(), and both MCP servers gain a compose tool (dryRun, returnSpec; remote stores it like render). Additive: render and validate are unchanged.

  • Revisioned spec editing. ak-render patch <spec> <ops> applies an RFC 6902 JSON Patch to a spec file in place: a path starting /blocks/@<id> addresses the block with that author id at any depth, operations are all or nothing, YAML comments and layout are kept, and the reply is a content hash plus the applied changes, never the spec. --base-hash refuses an edit made against a stale spec (SPEC_PATCH_CONFLICT); a patch that raises the error count is not written, and only a file that reads as a Page Spec is edited. The patch MCP tool (local: file under the working directory, or spec; remote: spec, authenticated like validate) and the library patch, patchSpecText and specHash expose the same contract. Motion Studio's atomic save now creates its temporary file exclusively under a random name. See docs/agent-guide.md. Migration: additive. RenderErrorCode gains SPEC_PATCH_ERROR and SPEC_PATCH_CONFLICT, so an exhaustive switch over it needs two cases; tools/list gains patch after repair.

  • Suggested fixes and a safe repair mode. validate(spec, { suggest: true }) (CLI validate --suggest, MCP validate with suggest: true) attaches fixes to diagnostics: RFC 6902 patches that start with a test of the current value, with a rule id, the diagnostic path and a safe or ambiguous classification. repair(spec, { mode: 'safe' }) (CLI ak-render repair, MCP repair) applies only the safe fixes, revalidates, keeps YAML comments where the edit can be replayed in place and returns a change log; near-name guesses for block types, actions, events, properties and enum values stay with the author. Without suggest, diagnostics are unchanged.

  • Vietnamese intent search. search-catalog (CLI, MCP and searchCatalog) folds diacritics and đ before tokenizing and maps common Vietnamese words and phrases ("biểu đồ", "bảng giá", "dòng thời gian") to the English words the block index uses, longest phrase first. English queries over index words rank as before; a few short Vietnamese words that are not English index words ("bang", "nut", "loc") now find their blocks. Motion recipe search shares the same tokenizer.

  • Motion Studio. ak-render motion studio <spec> serves a local, development-only dashboard over one Page Spec: a block list and a recipe gallery of compiled examples, an inspector with the phase timeline, timing, properties, fallback and emitted CSS, bounded token controls, Replay, Pause, Rapid toggle, a preview-only motion policy switch, Compare, Undo and Reset. Accept writes the reviewed diff to the spec in place, keeps YAML comments and refuses a stale, duplicate, invalid or empty proposal. It listens on 127.0.0.1 behind a session path with a strict CSP and never touches compiled HTML. See docs/motion.md.

  • Motion discovery and audit. ak-render motions lists the motion recipes, motions search <terms> ranks them by intent and motions describe <id> (--compact for the short form) returns one descriptor, all projected from the registry and never carrying CSS. ak-render motion audit <spec|page.html> reports deterministic findings with a rule id, severity, path, evidence and fix: the spec audit is authoritative (incompatible, nested, excessive or never-playing recipes, theme policy); the compiled-page audit is best effort (unguarded or looping motion, transition: all, layout keyframes, missing recipe CSS, exit or runtime, CSP and remote resources). --fail-on gates CI, --baseline gates only on new findings and standing errors, and the score is advisory. The MCP servers add motions (no bearer remotely) and audit-motion (bearer, like validate); the library exports the same functions. See docs/motion.md.

  • Blocks can opt into a named motion recipe with motion: <recipe> (or motion: { preset }): reveal-soft, stagger, figure-roll, fade-swap, tabs-slide, accordion-expand and dialog-pop. Recipes are compiler-owned CSS behind the reduced-motion guard, timed from a scale that derives from motion-duration, so reduced, still, print and no-JS pages settle as before. A page that names no recipe emits identical bytes. Validation rejects unknown or incompatible recipes and any field other than preset with a JSON path. The JSON Schema, describe --compact and the library exports (MOTION_RECIPES, getMotionRecipe, motionPresetsFor) carry the registry. See docs/motion.md.

  • Code blocks and api-endpoint bodies are syntax highlighted at compile time for php, javascript, typescript, python, go, rust, java, kotlin, csharp, c, cpp, swift, ruby, bash, sql, json, yaml and diff, plus common aliases such as ts, py, sh and yml. Colours come from theme tokens through the new syntax feature sheet, which ships only on pages with a highlighted token, and keep WCAG AA contrast in every preset. Other languages render plain, as before. The language prop's description lists the highlighted languages.

  • Code blocks also highlight html (with xml and svg, and embedded <script> and <style> bodies), css and markdown (md), and TypeScript (ts, tsx) now has its own grammar so type words such as string and number are colored.

  • decision and feedback blocks let a reader answer a plan inside the page. A decision is a question with up to six options, one of which may be recommended (it starts checked), and a note. One feedback block per page turns on commenting: select any text, or use the Comment button on a top-level section, and a comment records where it points, including code line numbers. A section's button turns into Edit comment once it has one, clicking commented text reopens its comment, and each comment in the panel links back to its place. Copy feedback copies every answer, comment and general note as one prompt to paste back to the agent. Comments survive a reload and reset when the content changes. Without scripts both blocks read completely, with the inputs disabled. A decision needs a feedback block on the page. The new plan-review gallery page shows both, and the skill and agent guide tell agents to use them for plans.

  • Icons by meaning. Cards, callouts, alerts, buttons and the items of stats, steps and timeline take an icon (gauge, phosphor:rocket, or { name, pack, size, label }), and a new icon block shows one glyph with a caption. Lucide, Phosphor, Tabler, Pixelarticons and Codicons are bundled as curated, pinned, license-tracked subsets; the theme's new icons profile picks the pack (blueprint tabler, editorial lucide, paper-ink and crimson-press phosphor, terminal-mono and data-console codicons), with ordered fallback and a warning. A page embeds only the glyphs it uses as same-document SVG symbols: offline, deterministic, no inline style. Codicons attribution ships in THIRD_PARTY_NOTICES.md. See docs/icons.md.

  • ak-render icons search|describe|packs and the search-icons, describe-icon and icon-packs MCP tools, on the local and hosted servers, with English and Vietnamese search and size-limited replies that never contain SVG.

  • Editorial blocks for publication-quality pages: publication-header (masthead with date, issue, edition and a section nav), story (lead, feature or brief, with an optional photo, byline, summary and body), digest-list (a dated rail of short items) and editorial-layout (a broadsheet grid: three columns from 1100px, two from 700px, one below, with the DOM reading order kept). New newspaper built-in preset and recipe values cards: unboxed, sections: newspaper, media: press-photo, plus the page (wide, broadsheet) and atmosphere (print) surfaces. fixtures/pages/newspaper-frontpage.yaml and the newspaper page recipe show the whole page. Existing presets render the same bytes.

  • hero takes optional actions: up to three link buttons (label, href, variant), the same shape as the cta band, rendered under the description.

  • Prose text renders a **double-asterisk** pair as bold, alongside backtick inline code. A bold pair can wrap code spans, code spans keep their asterisks literal, and a marker inside a code span never pairs with one outside it. A marker that is unpaired, empty, or padded with whitespace (2 ** 8) stays literal, and the content is escaped like any other text. A prose prop's description now reads "Plain text; code and bold spans render inline." Block titles (and the page outline), step, timeline, card and callout titles, heading text, table cells, comparison items, risk areas and key-value values render the same spans, so a class or path name in a title or a cell reads as code. meta.title, code blocks and terminal lines stay literal.

  • crimson-press built-in preset: cream paper, black ink and a crimson accent, Fraunces display over Inter Tight body and JetBrains Mono labels, square corners, no card shadow, and the cards: flat, tables: ledger, metrics: headline and callouts: outlined recipes. Every built-in list now names eleven presets.

  • Gallery theme preview at docs/gallery/themes/ (live at https://render.agentkit.best/gallery/themes/): the theme-showcase spec compiled under every built-in preset, one standalone page each, plus a viewer whose dropdown switches the framed preset. The viewer keeps the choice in the address (#crimson-press), makes no network request, and falls back to a plain list of links without JavaScript. The landing and the gallery index link to it.

  • The landing page at https://render.agentkit.best/ carries search and social metadata: canonical URL, a 1200×630 social card for Open Graph and X, favicons and a web manifest, light and dark theme-color, and JSON-LD for the site, the software and AgentKit. The site root also serves robots.txt, sitemap.xml and an llms.txt summary for AI answer engines. The site build adds these to the landing head (scripts/site-head-metadata.mjs); compiled pages are unchanged. scripts/generate-site-images.mjs regenerates the icons and the card.

  • The landing hero links to the GitHub repository, the demos and the MCP setup, and the landing prose marks URLs, commands and identifiers as inline code and key phrases as bold.

  • The landing page explains how to connect the hosted MCP server from Claude, ChatGPT, Claude Code, Cursor, VS Code, Codex or any client with an API key, states that the hosted endpoint is for AgentKit customers, and points everyone else to the local MCP server or a self-hosted Cloudflare deploy.

  • The hosted MCP server at https://render.agentkit.best/mcp supports OAuth. An MCP client added with only the URL signs in to agentkit.best in the browser and refreshes on its own: access tokens last an hour, and each refresh slides the grant to 365 days. The worker verifies the tokens locally against the issuer's JWKS and serves RFC 9728 protected-resource metadata. A personal AgentKit API key (ck_live_…) also works as a static bearer and lasts until revoked.

  • MCP protocol revision 2026-07-28, next to the legacy revisions, over stdio (ak-render mcp) and remote HTTP. server/discover, per-request _meta revision and client capabilities, resultType: "complete", list cache hints, the MCP-Protocol-Version/Mcp-Method/Mcp-Name header checks (-32020) and -32022 with the supported revisions for an unknown one. initialize still negotiates the legacy era.

  • GET /v1/version on the cloud renderer reports the deployed commit, package version, MCP revisions and remote tool names. The deploy workflow stamps the commit, and the smoke script fails when the deployed build or its MCP tool list drifts from it.

Changed

  • An unknown block type in validate, render and patch now reports up to three near types in details.closest (typo matches first, then search-catalog hits) instead of every registered type in details.known, so the diagnostic shrinks from about 1.1 kB to under 300 bytes. Its code, path and fix hints are unchanged; catalog and search-catalog list every type. Breaking for any client that read details.known from this diagnostic.
  • An unsupported MCP-Protocol-Version header now answers JSON-RPC -32022 with data: { supported, requested } instead of -32600 (still HTTP 400).
  • The remote MCP instructions name motions and audit-motion, so every remote tool appears in them.
  • The ak-render skill opens a page only when it writes the file for the first time. On a recompile it tells the user to refresh instead, so an updated page no longer opens one more browser tab.
  • Breaking for anonymous remote MCP use. With OAuth enabled (OAUTH_RESOURCE, as on render.agentkit.best), a remote MCP request without a bearer gets HTTP 401 with a resource_metadata challenge, which is what starts a client's sign-in. Before, it was served, and only validate and render refused it. A deployment without OAuth keeps anonymous discovery.

Fixed

  • The Content Security Policy no longer lists remote origins the page's provider allowlist blocks. img-src and media-src now take only origins whose references pass the same gate as the renderer, and a video or audio source that names a provider adds none, since the page only links to it (#187).

  • The render summary's bytes is the UTF-8 size of the emitted file. It used to count UTF-16 code units, so a page with any non-ASCII character reported fewer bytes than --out wrote.

  • A tab panel or fade-swap block now fades in even when the main thread is busy right after the change. The fallback that clears the entering mark used to fall due before the first frame and skip the fade.

  • diagram-panel without an adapter (including every hosted render) shows typed workflow, sequence, lifecycle and dataflow diagrams in full. The fallback read only components, nodes and connections, so steps, participants, states, transitions, messages and flows were dropped with no warning. Groups list their members, sequence messages keep their order, and validate warns at the exact path of an undeclared reference (#128).

  • Charts no longer draw at NaN or stop compiling on extreme or near-equal numbers. A dataset value such as 1e308 used to pass validate while the chart's range overflowed to Infinity, so the page carried NaN coordinates, and some kinds (bar, line, area, waterfall) never finished compiling. Two values a few ulps apart (0.3 and 0.30000000000000004) could also collapse a scatter axis to zero width (NaN) or loop the histogram ticks forever; ticks are now counted by index and a collapsed axis keeps the raw range. A flat range above 2⁵³ is padded so scatter and sparkline axes keep a width.

  • Validation is stricter: every dataset number, and every inline number a chart plots (series value, target, overlay position, axis bound), must be 0 or have a magnitude from 1e-100 to 1e100. Anything else is a SPEC_BOUNDS_ERROR at the cell or prop path. This also applies to datasets only a table reads, so a spec that held such a value and validated before now fails. The published schema bounds dataCell and the chart number props the same way; filter and visibleWhen operands are unchanged. A derived field (transform.derive) whose result falls outside those bounds, such as chained ratios of in-range cells, is null instead of a number a chart cannot scale.

  • Highlighting stays linear on a line full of unclosed openers such as ${${${ in Bash or #[#[ in Rust, which took about ten seconds per 100k-character block before. A language named after an Object property, such as constructor, renders plain.

  • A second click on the theme toggle while its view transition still runs no longer raises an uncaught Transition was skipped error. The skipped transition's rejected ready promise is now handled; the theme applies as before.

  • The accordion-expand recipe animates only on screen. A section opened just before printing used to print mid-growth and partly clipped, because its ::details-content transition also ran in print (#48).

  • Chart data tables scroll inside their own box instead of widening the page on a phone when the chart's table is opened, the y-axis title no longer starts outside the chart, and the kanban board no longer overflows the printed page.

  • A table row-width warning now names the authored row. An invalid row is dropped during normalization, so later warnings used to shift onto an earlier index (rows[0] instead of rows[1]), which misled agents fixing by path.

  • Every cross-field diagnostic about a list item now names the authored item. An invalid item is dropped during normalization, and checks on chart series, decision options, kanban cards and columns, roadmap entries, references, data-table columns, calendar events, pricing plans, feature-matrix rows, asset policy checks and other item lists reported later items one index too early. Nested item blocks are matched to their authored item the same way.

  • Feature-matrix row, chart series and table row-width checks count the items the author wrote. A dropped plan, label, value or column used to add a spurious "expected N values" error, "has N values for M labels" warning or row-width warning on top of its own error, or hide a real table row-width mismatch. A plans list rejected outright no longer makes every row report "expected 0 values".

  • feature-matrix compares the authored number of plans and values, so a plan or value dropped as invalid no longer adds a width error to every row, and a real width mismatch is still reported alongside it.

  • ak-render validate lists each warning once. A spec with an error used to print every warning twice in text mode; --json was not affected.

  • Malformed YAML no longer compiles silently. A duplicate key, an unterminated scalar, a second document or a recovered indentation error now fails with SPEC_PARSE_ERROR and its line and column, instead of producing a different page.

  • A toggle action on an open dialog now closes it. It used to open the dialog again, which moved focus back to its first control.

  • A theme action now works on a page compiled with themeToggle: false. It used to throw applyTheme is not defined, because the theme runtime shipped only with the toggle. The page still emits no toggle or toggle CSS.

  • A scripted page compiled with themeToggle: false no longer throws restoreTheme is not defined on load, which left every block after it unwired. The runtime restores a stored theme only when it ships the theme runtime.

  • motion-policy: reduced now restrains motion as documented: colour, shadow and opacity transitions keep the theme duration, anything that would move (hover lifts, image zoom) jumps to its end state, and entrances, loops, parallax, smooth scrolling, count-up and the theme view transition stay off. The reader's reduced-motion setting still wins over every policy. See ADR 0002.

  • The dialog entrance now respects reduced motion, and it no longer shares the ak-rise keyframes name with the hero word reveal, which made one of the two play the other's animation on pages with a dialog.

  • Print settles every animation and transition.

  • The compiler now fails a page whose stylesheet has an animation outside the reduced-motion guard, a fixed-duration transition outside it, or a keyframes name defined twice.

  • Diagram adapter markup with SMIL animation (animate, animateTransform, animateMotion, set, discard) or a marquee is refused, since no stylesheet can stop it under reduced motion or in print. Adapter motion belongs in its stylesheet.

[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...> --compact). Block types are read from the compiler IR.
  • pnpm bench:spec (benchmarks/spec-compression.mjs) records, per composition fixture, the spec bytes, the bytes with every dataRef inlined, the HTML bytes, and the catalog and compact-describe bytes an agent reads, in docs/artifacts/spec-compression.{json,md}. The output is deterministic.
  • Six composition fixtures: complex-dashboard, benchmark-report, research-report, product-case-study, interactive-data-explorer and incident-report. Each validates with no warnings and compiles to identical bytes three times. fixtures/rejected/validation/ holds well-formed but wrong specs that must fail validation at a located path, optionally pinned by a first line # expect: CODE $.path.
  • tests/browser/composition-matrix.spec.ts checks every fixture page for horizontal overflow at 320, 375, 768 and 1440 in light and dark, running animation under reduced motion, script-off readability, print, keyboard focus, network requests and critical axe violations. @axe-core/playwright is a new devDependency.
  • scripts/capture-demo-media.mjs captures five more page shots and four component crops (KPI, terminal, checklist, file tree), and --only <names> recaptures a subset without the walkthrough video.
  • A pair of backticks in prose text renders as inline code, so `ak-render catalog` in a text, a step, a list item, a description or a caption reads as a command. The text is escaped before the span is wrapped, nothing else is parsed as markup, and an unpaired backtick stays literal. Titles, code blocks, terminal lines and the chart summary are unchanged, and describe and the JSON Schema say which props do this.

Changed

  • catalog text is grouped by category under ## <category> headers, one type — summary line per block, without the kind column. catalog --json and the MCP catalog add category and tags to each entry and print one block and one action per line; the parsed value is otherwise unchanged. A single-type describe <type> is byte-identical.
  • The MCP describe input no longer requires type: pass type or types, plus optional compact. Every local tool description is at most 200 characters.
  • URL props declare the network capability of the asset they load, so the CSP origins and the validation gate come from one schema walk at any depth.
  • When a oneOf value fails, diagnostics come from the option the author meant, chosen by JSON shape and then by type.
  • A tab's select event passes the tab id as its value, so set-value without its own value stores the selected tab.
  • Chart labels is optional in the schema; a chart without bound data still requires it, with the same message and path.
  • The cloud Worker is routed at render.agentkit.best/mcp and render.agentkit.best/v1/*, beside the site's Custom Domain on the same hostname.
  • 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 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.

Fixed

  • Tab panels and carousel slides are readable without scripts and in print: every panel ships visible with its title until the runtime marks the container ready.
  • Accordion sections print open, nested blocks included.
  • Accordion and carousel styles apply only to their own sections and slides, so a nested block keeps its own look.
  • The runtime escapes embedded state, so a value such as </script> cannot close the script element.
  • An event stops at the nearest block, so it no longer reaches an enclosing block's bindings.
  • A set-value action without value takes the event's value, for example a slider's. With no event value it does nothing; before, it set undefined.
  • The cloud Worker validates bearers against the canonical AgentKit endpoint, GET https://agentkit.best/api/agentkit/entitlements, instead of an unreachable host, so authenticated render, share and export can succeed. It fails closed on a rejected token (401), an inactive account (403), and an upstream error, redirect, timeout or malformed body (502). An active app or kit entitlement grants the render and share scopes, which stay separate checks.
  • Screenshot and PDF export call the Browser Run binding's Quick Actions with the compiled HTML inline and caching off, and wrangler.jsonc attaches the BROWSER binding.
  • Remote MCP bounds its anonymous surface: a JSON-RPC batch carries at most 16 members, never initialize, and is refused (400) under protocol revision 2025-06-18 or later, which removed batching. catalog, search-catalog, describe, recipes, recipe and themes stay anonymous but count per client IP (anon-ip, 120/min).
  • A remote MCP request that presents a rejected bearer answers HTTP 401 with WWW-Authenticate: Bearer, whatever the method, instead of a tool error; REST 401s carry the same challenge. A request without a bearer is still served, and validate/render still answer a tool error with UNAUTHENTICATED.
  • Cloud rate limits use the Workers Rate Limiting binding, one per route class, instead of KV counters that could fail on rapid writes; a limiter fault refuses the call with RATE_LIMITED. An MCP render with share: true counts against share only, as POST /v1/share does, and a call refused by authorization consumes nothing.
  • The cloud Worker caches entitlements answers in memory under a SHA-256 digest of the bearer (60 s accepted, 10 s rejected), and limits uncached bearer checks per client IP (30/min) before contacting the entitlements endpoint.
  • Remote MCP reports a storage or runtime fault as a generic INTERNAL_ERROR tool error, and the REST routes answer such a fault with a generic 500, so no internal message reaches a caller.
  • Hosted shares and artifacts are served with content-security-policy: sandbox …; frame-ancestors 'none': they run in an opaque origin and cannot be framed.
  • The expiry sweep pages through every listed object with the cursor, reads expiry from listing metadata instead of downloading bodies, and deletes in batches; R2 lifecycle rules (apps/cloud/r2-lifecycle.json, applied on deploy) delete artifacts after 1 day and shares after the retention period plus a day.
  • A remote video poster that the network policy blocks now fails validate with a POLICY_VIOLATION at the block's poster path, naming the reason. Before, validate passed and compile failed at $ with "emitted a remote resource reference". A poster is gated by the images capability, an allowed remote poster's origin joins the CSP, and the renderer drops a blocked poster even for an IR that skipped validation.
  • Diagram adapter <style> elements now receive the page style nonce, so styled adapter SVG renders as drawn instead of in default black. The policy stays nonce-only: inline style attributes are removed from adapter output with a warning. Adapter CSS is scoped with @scope to its own diagram canvas, so it cannot restyle the page, and it cannot load anything: escapes, character references, url() other than a fragment reference such as url(#grad), image-set(), every at-rule except @media, @keyframes and @supports, and @keyframes that redefine the page's own reject the output to the structured fallback. Comments and !important are removed. Adapter markup that writes a nonce or any data-ak-* attribute, or an href, xlink:href, src, srcset, poster, action, formaction, background, data, codebase or ping that is not a same-document #fragment, or SVG animation whose attributeName is one of those, is rejected too, and so is markup that is not a self-contained fragment: a stray or missing end tag, a raw-text element such as plaintext or textarea, an element that merges into the page document such as body or meta, an HTML element inside SVG, or a comment. Output from the ak:diagram compiler passes these checks. Adapter animation stops under reduced motion, motion-policy: none and print. docs/diagram-adapter.md lists what adapter CSS may use.
  • Checking adapter markup is linear in its size. An unterminated tag repeated to the 256 KB bound took minutes; it now takes milliseconds.
  • A long unbroken token, such as a path or an env var list, no longer widens the page on a phone. Key-value values, list items, text and callouts break the token inside their own line, so the reported key-value page no longer scrolls sideways at 375px.
  • A diagram-panel shows adapter SVG at its natural size. A wide diagram scrolls sideways inside its panel, a named region that scrolls from the keyboard, instead of shrinking its labels until they are unreadable. In print it is scaled to the page width.
  • A diagram-panel whose adapter rendered no longer shows the structured description beside the drawing. The description stays in the document behind a closed "Text description" disclosure, which opens in print, with or without script.
  • A long terminal session no longer leaves its last lines blank in a capture. Lines now stagger 80ms apart instead of 340ms, lines past the twelfth share its delay, and the whole session is drawn about 1.4s after it arrives.
  • A wide table or adapter diagram now shows a soft shade on each edge that has more content beyond it, so a frame that scrolls sideways no longer looks clipped. A frame that fits shows none.
  • A data-table row that a filter hides stays hidden at phone widths, where rows become cards.
  • Blocks inside or after a visibleWhen view keep the normal block gap and the section-break gaps.
  • A thinned category axis always labels the last category, so a series never reads as ending early.
  • Chart ticks finer than 0.01 keep the decimals the step needs instead of all printing the same value, and only floating-point noise is removed before a value is formatted.
  • A histogram over huge, close values (such as 1e16 and 1e16 + 4) keeps finite, increasing bin edges: when clean steps cannot separate the values it draws one bin.
  • The page outline skips a section behind visibleWhen, so it never links to a hidden section.
  • Dataset field names __proto__, constructor and prototype are refused at validation, and a log-viewer level named like an object property gets the neutral tone.
  • date-input accepts ISO dates in the years 0001–0099.

[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 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.
  • The night band now uses the same tint, focus ring and sheen as dark mode; it had drifted to stronger values.
  • Font verification checks every source of every @font-face, and rejects local(), instead of only the first url().
  • 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.
  • 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.
  • 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.
  • --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".
  • 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.

[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.

[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/.