bestagentkits/ak-render
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-3dandproduct-3dis 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-3ddoes 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-postandsocial-feedblocks: 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 (imageunder theimagescapability,videoundermedia), 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 adenypage still validates.validatewarns 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,redditandhackernewsforpolicy.network.providers. A provider may now declare asset hosts, the CDNs its avatars, images and video files come from (youtubegainsytimg.comandyt3.ggpht.com); an asset that names no provider passes a declared allowlist from those hosts too. The new names are also accepted by theproviderprop ofvideoandaudio, 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/aliasfix thatrepairapplies, such asplatform: twittertox. -
Claude plugin folder.
plugins/ak-render/is a self-contained plugin for the Claude plugin directory: a manifest that starts the pinned@bestagentkits/renderMCP 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:pluginsmoke-tests it against the published package. See docs/claude-plugin.md. -
shader-3dblock: five closed shader presets (noise, fresnel, hologram, distortion, dissolve) on a sphere, torus, torus knot or plane, with typedintensity,scale,progressandspeeddials, 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 abindmap to state, change uniforms live and firechange. 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-3dblock: 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-3dblock: 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.export3dPosterSvgexports that poster with its night sky, and the gallery's 3D section shows the galaxy. See docs/3d-effects.md. -
globe-3dblock: 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. CompactmarkerListandarcListlines 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-3dblock: 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 therounded-boxandcapsuleshapes. See docs/3d-scenes.md. -
point-cloud-3dblock: a scanned point cloud at true proportions from a local.xyz/.csv/.txtfile (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 axismin/max, a compile-time level-of-detail order and abudgetthe status line always reports, spatial picking that writesbindand shows the authored coordinates with units, and aCut abovesection 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-3dblock: 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 abindstate 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-3dblock: 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, withsmooth,spring,snaporlineareasing, aloop,onceormanualtimeline, and target buttons, canvas keys and abindstate 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-3dblock: 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 abindstate path) flies to it and firesselect. 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 aheightsgrid and its rows reach 256 items. See docs/3d-data.md. -
edge-flownow 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-flowdiagram 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-3dblock: 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 doctorreports the browser and its WebGL 2 support. -
exportDiagramSvgwrites 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-activationandsequence-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: 2may 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 owndata-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 athttps://render.agentkit.best/mcpwith AgentKit OAuth, so no Node or npm is needed; the local stdio manifests are unchanged.pnpm plugin:chatgptchecks 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 theOPENAI_APPS_CHALLENGEsecret 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, statesreadOnlyHint,destructiveHintandopenWorldHint. -
Remote artifact export. The hosted MCP server adds
artifact-export: given anartifactUrl, 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. RemoterendertakesretainSpec: trueto keep the spec source with the page's owner and expiry; revoking a share deletes its spec and exports. Deployments need theDOWNLOAD_SIGNING_KEYsecret; without it the tool answersDOWNLOAD_UNAVAILABLE. See apps/cloud/README.md. -
Visual audit.
ak-render audit-ui <spec|page.html>checks the compiled artifact. Thequickpreset (default) reads the resolved theme and the markup without a browser: theme text contrast, wide tables and long chart labels.--preset publicationadds 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-ongates CI and an incomplete run fails the gate. The MCP servers addaudit-ui(quick only remotely); the library exportsauditUi,auditUiQuickandUI_RULES. See docs/audit-ui.md. -
Derived metrics and KPI citations.
transform.deriveadds fields from a closed list of operations (ratio,percentOf,delta,percentChange,share,cumulative), and on adata-tabletransform.rollupadds a sum or mean total row as the table footer; neither accepts an expression. Value formats takesigned: truefor a leading+(not the benchmark and breakdown widgets, which sign their own differences). Akpiitem maycitea dataset field with an aggregate: the compiler fills an omittedvaluefrom it, or warns (rule: kpi-cite) when the written value disagrees with the data.valueis now optional on akpiitem that has acite. See docs/data-and-state.md. -
Compose.
ak-render compose input.yaml --out page.htmlbuilds a whole page from a typed intent and content slots, with no Page Spec to write. The first intent isinvestment-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 samecompile(), so the HTML is byte-identical to rendering the emitted spec (--spec-out,--dry-run).compose intents --jsonlists intents and their content schemas. The library exportscompose(),composeSpec(),composeIntents()andcomposeInputJsonSchema(), and both MCP servers gain acomposetool (dryRun,returnSpec; remote stores it likerender). Additive:renderandvalidateare 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 authoridat 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-hashrefuses 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. ThepatchMCP tool (local:fileunder the working directory, orspec; remote:spec, authenticated likevalidate) and the librarypatch,patchSpecTextandspecHashexpose 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.RenderErrorCodegainsSPEC_PATCH_ERRORandSPEC_PATCH_CONFLICT, so an exhaustiveswitchover it needs two cases;tools/listgainspatchafterrepair. -
Suggested fixes and a safe repair mode.
validate(spec, { suggest: true })(CLIvalidate --suggest, MCPvalidatewithsuggest: true) attachesfixesto diagnostics: RFC 6902 patches that start with atestof the current value, with a rule id, the diagnostic path and asafeorambiguousclassification.repair(spec, { mode: 'safe' })(CLIak-render repair, MCPrepair) 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. Withoutsuggest, diagnostics are unchanged. -
Vietnamese intent search.
search-catalog(CLI, MCP andsearchCatalog) 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 motionslists the motion recipes,motions search <terms>ranks them by intent andmotions describe <id>(--compactfor 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-ongates CI,--baselinegates only on new findings and standing errors, and the score is advisory. The MCP servers addmotions(no bearer remotely) andaudit-motion(bearer, likevalidate); the library exports the same functions. See docs/motion.md. -
Blocks can opt into a named motion recipe with
motion: <recipe>(ormotion: { preset }):reveal-soft,stagger,figure-roll,fade-swap,tabs-slide,accordion-expandanddialog-pop. Recipes are compiler-owned CSS behind the reduced-motion guard, timed from a scale that derives frommotion-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 thanpresetwith a JSON path. The JSON Schema,describe --compactand the library exports (MOTION_RECIPES,getMotionRecipe,motionPresetsFor) carry the registry. See docs/motion.md. -
Code blocks and
api-endpointbodies 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 asts,py,shandyml. Colours come from theme tokens through the newsyntaxfeature sheet, which ships only on pages with a highlighted token, and keep WCAG AA contrast in every preset. Other languages render plain, as before. Thelanguageprop's description lists the highlighted languages. -
Code blocks also highlight
html(withxmlandsvg, and embedded<script>and<style>bodies),cssandmarkdown(md), and TypeScript (ts,tsx) now has its own grammar so type words such asstringandnumberare colored. -
decisionandfeedbackblocks let a reader answer a plan inside the page. Adecisionis a question with up to six options, one of which may berecommended(it starts checked), and a note. Onefeedbackblock 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. Adecisionneeds afeedbackblock on the page. The newplan-reviewgallery 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,stepsandtimelinetake anicon(gauge,phosphor:rocket, or{ name, pack, size, label }), and a newiconblock shows one glyph with a caption. Lucide, Phosphor, Tabler, Pixelarticons and Codicons are bundled as curated, pinned, license-tracked subsets; the theme's newiconsprofile picks the pack (blueprinttabler,editoriallucide,paper-inkandcrimson-pressphosphor,terminal-monoanddata-consolecodicons), 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 inTHIRD_PARTY_NOTICES.md. Seedocs/icons.md. -
ak-render icons search|describe|packsand thesearch-icons,describe-iconandicon-packsMCP 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) andeditorial-layout(a broadsheet grid: three columns from 1100px, two from 700px, one below, with the DOM reading order kept). Newnewspaperbuilt-in preset and recipe valuescards: unboxed,sections: newspaper,media: press-photo, plus thepage(wide,broadsheet) andatmosphere(print) surfaces.fixtures/pages/newspaper-frontpage.yamland thenewspaperpage recipe show the whole page. Existing presets render the same bytes. -
herotakes optionalactions: up to three link buttons (label,href,variant), the same shape as thectaband, 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;codeand bold spans render inline." Block titles (and the page outline), step, timeline, card and callout titles,headingtext, 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-pressbuilt-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 thecards: flat,tables: ledger,metrics: headlineandcallouts: outlinedrecipes. Every built-in list now names eleven presets. -
Gallery theme preview at
docs/gallery/themes/(live athttps://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 darktheme-color, and JSON-LD for the site, the software and AgentKit. The site root also servesrobots.txt,sitemap.xmland anllms.txtsummary 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.mjsregenerates 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/mcpsupports 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_metarevision and client capabilities,resultType: "complete", list cache hints, theMCP-Protocol-Version/Mcp-Method/Mcp-Nameheader checks (-32020) and-32022with the supported revisions for an unknown one.initializestill negotiates the legacy era. -
GET /v1/versionon 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,renderandpatchnow reports up to three near types indetails.closest(typo matches first, thensearch-cataloghits) instead of every registered type indetails.known, so the diagnostic shrinks from about 1.1 kB to under 300 bytes. Its code, path and fix hints are unchanged;catalogandsearch-cataloglist every type. Breaking for any client that readdetails.knownfrom this diagnostic. - An unsupported
MCP-Protocol-Versionheader now answers JSON-RPC-32022withdata: { supported, requested }instead of-32600(still HTTP 400). - The remote MCP instructions name
motionsandaudit-motion, so every remote tool appears in them. - The
ak-renderskill 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 onrender.agentkit.best), a remote MCP request without a bearer gets HTTP 401 with aresource_metadatachallenge, which is what starts a client's sign-in. Before, it was served, and onlyvalidateandrenderrefused 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-srcandmedia-srcnow take only origins whose references pass the same gate as the renderer, and avideooraudiosource that names aprovideradds none, since the page only links to it (#187). -
The render summary's
bytesis 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--outwrote. -
A tab panel or
fade-swapblock 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-panelwithout an adapter (including every hosted render) shows typedworkflow,sequence,lifecycleanddataflowdiagrams in full. The fallback read onlycomponents,nodesandconnections, so steps, participants, states, transitions, messages and flows were dropped with no warning. Groups list their members, sequence messages keep their order, andvalidatewarns at the exact path of an undeclared reference (#128). -
Charts no longer draw at
NaNor stop compiling on extreme or near-equal numbers. A dataset value such as1e308used to passvalidatewhile the chart's range overflowed toInfinity, so the page carriedNaNcoordinates, and some kinds (bar, line, area, waterfall) never finished compiling. Two values a few ulps apart (0.3and0.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 be0or have a magnitude from1e-100to1e100. Anything else is aSPEC_BOUNDS_ERRORat 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 boundsdataCelland the chart number props the same way; filter andvisibleWhenoperands are unchanged. A derived field (transform.derive) whose result falls outside those bounds, such as chained ratios of in-range cells, isnullinstead 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 anObjectproperty, such asconstructor, renders plain. -
A second click on the theme toggle while its view transition still runs no longer raises an uncaught
Transition was skippederror. The skipped transition's rejectedreadypromise is now handled; the theme applies as before. -
The
accordion-expandrecipe animates only on screen. A section opened just before printing used to print mid-growth and partly clipped, because its::details-contenttransition 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 ofrows[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-matrixcompares 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 validatelists each warning once. A spec with an error used to print every warning twice in text mode;--jsonwas 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_ERRORand its line and column, instead of producing a different page. -
A
toggleaction on an open dialog now closes it. It used to open the dialog again, which moved focus back to its first control. -
A
themeaction now works on a page compiled withthemeToggle: false. It used to throwapplyTheme 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: falseno longer throwsrestoreTheme is not definedon load, which left every block after it unwired. The runtime restores a stored theme only when it ships the theme runtime. -
motion-policy: reducednow 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-risekeyframes 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 amarqueeis 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 thethemerender option) now replaces the spec'stheme.recipesas well as its tokens. Before, spec recipes applied regardless.- Every
gallerythumbnail 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
selectfor the initial tab when the page loads, so page state keeps its declared initial values. - A remote video
posterthat the network policy blocks is avalidateerror (POLICY_VIOLATIONat theposterpath), 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.
catalogtext is grouped by category, andcatalog --jsonprints one block per line with newcategoryandtagsfields.- 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--slidesonly), so its per-task mean is ~25.0k tokens, not ~33.7k.render-benchmark.mjsmeasures theak-renderskill route per task: the AgentKit shared HTML contract, the skill,catalog, anddescribe --jsonfor 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% withdescribe --compact, which counts the shared contract too (previously 65% and 75%).agent-token-cost.mjs --reuse-legacyreruns 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 exceptpage,sectionandhero, and tabs may nest in tabs. An item'stext, and a bento tile'stitle, are optional when the item has blocks; an item with neither is an error at its path. - Nested slots with
acceptsandparentsrules. Diagnostics carry the nested JSON path, and nested blocks count toward the block limit. grid-itemplaces blocks on a 12-track grid withspan,tabletSpan,mobileSpan,rowSpan,startandalign.grid.columnstakes 1–12 orauto(withminItemWidth), grids takegapandalign, andstacktakesalign.- Semantic page layouts:
sidebar-layout(asidebarbeside the mainblocks, on eitherside),main-aside(anasidethat stays in view on wide screens) andrail-layout(a compactrail, a labelled<nav>when it holds only links or toolbars). - Datasets: top-level
datasets, anddataRef, inlinedataand a boundedtransform(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);percenttakes87for "87%". See docs/data-and-state.md. visibleWhenshows 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-inputanddate-input. Each has a visible label, writes one value tostate.<key>throughbind, and fireschangewith its value. filter-barfilters adata-table,kanbanorlog-viewerwith 1–8 controls, each naming a rowfieldand amatch. It adds an announced result count and a Reset button;selectandradio-groupcan list the target's values withoptionsFrom. Adata-tablethat 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 asearchchild.data-table: a typed, sortable table bound to a dataset. Column typestext,number,percent(aliaspercentage),currency,date,badge,link,progressandsparkline; 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,gaugeandtreemap. A chart can bind rows and read them through thex,y,series: { field }andvalueencodings, and takesmarkers,annotations,sortand a gaugetarget. A bound chart's fallback table comes from the bound rows. Charts that uselabelsandseriesrender the same markup as before. - Engineering widgets:
kanban,roadmap,test-results,log-viewer,api-endpointandschema-viewer. - Evidence widgets:
benchmark-comparison(computed delta, change and verdict;currencyis set once for the whole block, not per metric),metric-breakdown,annotated-imageandreferences(stable#ref-<id>anchors). - Product widgets:
pricing,feature-matrix,testimonial(two or more quotes form a grid),logo-cloud,peopleandcalendar(weeks start on Monday;weekStart: sundaychanges 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.recipesselects them. See docs/themes.md. - Four built-in presets:
data-console,executive-report,product-studioandresearch-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, andak-render describe <type...> --compactreturns up to 12 contracts with one line per prop; a shape repeated within a contract readslike <field>and a repeated long enumenum as <field>. Row-filtering words rankfilter-barfirst. MCP gainssearch-catalog,catalog{category}anddescribe{types, compact}, on the stdio and the remote server; the remotesearch-catalogneeds no token. The library exportssearchCataloganddescribeMany. - 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), andak-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 asrecipesandrecipe{name}on the stdio and the remote server, and the library asrecipes(),recipe(name)and thePageRecipeandPageRecipeSummarytypes; an unknown name throwsSPEC_VALIDATION_ERRORat pathnamewithdetails.allowed. pnpm recipes:generateembeds the recipe YAML insrc/recipes/recipes.generated.ts, andpnpm recipes:check, part ofpnpm verify, fails when that module is stale.- The library exports
BLOCK_CATEGORIES,THEME_RECIPE_SPECS,VALUE_FORMATSand theMaterializedData,DataRowandDataScalartypes. - Remote MCP over Streamable HTTP at
https://render.agentkit.best/mcp, served by the cloud Worker. It lists the same tools asak-render mcp:catalog,search-catalog,describe,recipes,recipe,validate,renderandthemes. A remoterendertakes noout: it compiles through the same path asPOST /v1/render(byte-identical HTML), stores the page and returns the summary plusartifactUrlandexpiresAt, never the HTML. The artifact lives one hour, or becomes an expiring share withshare: true(needs the share scope).catalog,search-catalog,describe,recipes,recipeandthemesanswer without a token;validateandrenderneed 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 mcpanswers byte for byte as before. GET /v1/artifact/:idserves the short-lived artifact a remote MCP render stored.scripts/cloud-smoke.mjssmoke-tests a deployed renderer (MCP and REST, share lifecycle, exports) withBASE_URLand an optionalTOKEN; the manual cloud deploy workflow runs it after deploying.benchmarks/agent-token-cost.mjsestimates 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 indocs/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 everydataRefinlined, the HTML bytes, and the catalog and compact-describe bytes an agent reads, indocs/artifacts/spec-compression.{json,md}. The output is deterministic.- Six composition fixtures:
complex-dashboard,benchmark-report,research-report,product-case-study,interactive-data-explorerandincident-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.tschecks 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/playwrightis a new devDependency.scripts/capture-demo-media.mjscaptures 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 atext, 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,codeblocks,terminallines and the chart summary are unchanged, anddescribeand the JSON Schema say which props do this.
Changed
catalogtext is grouped by category under## <category>headers, onetype — summaryline per block, without the kind column.catalog --jsonand the MCPcatalogaddcategoryandtagsto each entry and print one block and one action per line; the parsed value is otherwise unchanged. A single-typedescribe <type>is byte-identical.- The MCP
describeinput no longer requirestype: passtypeortypes, plus optionalcompact. 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
oneOfvalue fails, diagnostics come from the option the author meant, chosen by JSON shape and then bytype. - A tab's
selectevent passes the tab id as its value, soset-valuewithout its ownvaluestores the selected tab. - Chart
labelsis 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/mcpandrender.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-valueaction withoutvaluetakes the event's value, for example a slider's. With no event value it does nothing; before, it setundefined. - 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 therenderandsharescopes, 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.jsoncattaches theBROWSERbinding. - 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,recipeandthemesstay 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, andvalidate/renderstill answer a tool error withUNAUTHENTICATED. - 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 MCPrenderwithshare: truecounts againstshareonly, asPOST /v1/sharedoes, 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_ERRORtool 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
posterthat the network policy blocks now failsvalidatewith aPOLICY_VIOLATIONat the block'sposterpath, naming the reason. Before, validate passed and compile failed at$with "emitted a remote resource reference". A poster is gated by theimagescapability, 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: inlinestyleattributes are removed from adapter output with a warning. Adapter CSS is scoped with@scopeto 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 asurl(#grad),image-set(), every at-rule except@media,@keyframesand@supports, and@keyframesthat redefine the page's own reject the output to the structured fallback. Comments and!importantare removed. Adapter markup that writes anonceor anydata-ak-*attribute, or anhref,xlink:href,src,srcset,poster,action,formaction,background,data,codebaseorpingthat is not a same-document#fragment, or SVG animation whoseattributeNameis 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 asplaintextortextarea, an element that merges into the page document such asbodyormeta, an HTML element inside SVG, or a comment. Output from theak:diagramcompiler passes these checks. Adapter animation stops under reduced motion,motion-policy: noneand print.docs/diagram-adapter.mdlists 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-panelshows 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-panelwhose 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
terminalsession 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
tableor 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-tablerow that a filter hides stays hidden at phone widths, where rows become cards. - Blocks inside or after a
visibleWhenview 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__,constructorandprototypeare refused at validation, and alog-viewerlevel named like an object property gets the neutral tone. date-inputaccepts 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-scaletoken. - 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.
- Heading sizes now follow the
- 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:descriptionandtwitter:cardfrom 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
imagesnow add their origin toimg-srcfor every image-bearing block. Before, onlyimageandgallerydid; onlyvideoandaudiouse themediacapability. - Feature stylesheets moved to
src/render/feature-styles.ts;styles.tsre-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 offont-src 'none'. Verification fails on any@font-facesource 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
AKfamily embeds nothing. - The licences ship in
assets/fonts/<family>/OFL.txtand in the npm package. Each@font-facecarries a notice comment.
- The face is inlined as a
- 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 mcpserves the compiler as an MCP server over stdio, withcatalog,describe,validate,renderandthemestools.renderwrites the HTML to theoutpath, which must end in.htmlor.htm, and returns only a summary.themesreturns 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-renderagent skill (skills/ak-render/SKILL.md), installable withnpx 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) anddocs/agent-guide.md: the agent loop, a minimal spec, and the MCP client config.sectiongainssurface: 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
ctablock: eyebrow, an oversized gradient title, text, and up to three link actions, on the night band. It is the newctaruntime feature. herogains optionalsrc,alt,addressandalign: start | center. Withsrc, a framed product shot sits below the copy and straightens from a tilt as the page scrolls.altis required whensrcis 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.mjsrecords element-level crops at 2x (crop-chart,crop-donut,crop-compare,crop-timeline,crop-diagram). The showcase bento uses them.pnpm fonts:generateandpnpm fonts:checkregenerate 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
outlineruntime feature, and sections now carry anidof the formak-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
codeblock now declares thecopyruntime 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 thebefore-afterruntime 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 byscripts/capture-demo-media.mjs. - A
showcaselanding 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: nonenow 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 carriesdata-motion="none".loadThemereports a non-objecttokensordarkvalue as aPOLICY_VIOLATIONrender error instead of throwing aTypeError.- 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
bentotile withsrcnow requiresalt; an explicitalt: ""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.
checklistandframeare 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 rejectslocal(), instead of only the firsturl(). - 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,gridorcomparisoncolumn no longer grows past a phone screen when a child holds a long code line; the line scrolls inside its frame. ak-render <command> --helpprints that command's usage instead of trying to read a file named--help;ak-render page.yaml --helpprints the compile usage instead of compiling.--outcreates missing folders, and a file that cannot be written exits2with a one-line reason instead of a stack trace and exit1, which agents read as "fix the spec".img-srcandmedia-srcinclude'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-renderCLI bin, and apack/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/.