Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
chore: shrink the clone and serve gallery images from R2 (#63)
Matthew Kissingerfdcd76d9760f
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.ymlindex c46b3460..ab5b9dbb 100644--- a/.github/workflows/pages.yml+++ b/.github/workflows/pages.yml@@ -53,6 +53,14 @@ jobs:- name: Install the enginerun: bun install --frozen-lockfile+ # Before the build, deliberately: the gallery images live in R2 now, and+ # whether they are still served and still byte-identical to their receipts+ # has nothing to do with whether the GLBs rebuild. Running it first means a+ # broken bucket reports as a broken bucket rather than hiding behind a+ # build failure.+ - name: Verify the published gallery images+ run: bun scripts/verify-posters.mjs+- name: Install the siterun: bun install --frozen-lockfileworking-directory: sitediff --git a/.gitignore b/.gitignoreindex 9d287dce..ac4de1b5 100644--- a/.gitignore+++ b/.gitignore@@ -41,3 +41,24 @@ site/dist/# Local agent config (launch profiles, per-machine settings). The shipped# plugin manifest lives in .claude-plugin/, which is tracked..claude/++# Gallery posters are fetched from R2 by site/scripts/verify-assets.mjs and cached here.+.poster-cache/++# Gallery images are rendered here and published to R2 by scripts/upload-posters.mjs.+.posters/++# Local wrangler simulator state. `wrangler r2 object put` without --remote+# writes uploads here instead of the bucket; none of it belongs in git.+.wrangler/++# Removed from history on 2026-09-10 and served from R2 instead; see+# docs/plans/repo-size-and-r2-migration-2026-09-10.md. The 83 JSON receipts in+# examples/renders/ stay tracked -- they are the provenance record. The images+# they attest do not, because 117 MB of history bought nothing the tools need.+examples/renders/*.png+examples/renders/*.gif++# Social-media masters. Archived at ~/kiln-media-archive/ and referenced by no+# file in the repository; the README video is served by GitHub's asset CDN.+assets/video/diff --git a/README.md b/README.mdindex f8a9f4d1..bdc69260 100644--- a/README.md+++ b/README.md@@ -70,12 +70,16 @@ real-world setup reports and GPU checks remain welcome from contributors.Install [Bun](https://bun.sh), then:```sh-git clone https://github.com/matthew-kissinger/kiln+git clone --filter=blob:none https://github.com/matthew-kissinger/kilncd kilnbun install --frozen-lockfilebun run kiln render examples/crate.kiln.js --out crate.glb --views sheet.png```+`--filter=blob:none` checks out the current tree in full and leaves historical+file contents on the server, fetching them only if you ask for an old revision.+A plain `git clone` also works and gives you the whole history up front.+This writes a GLB and a six-view image of an existing program. It makes no model call.Rendering uses the CPU unless a compatible local GPU service is available.Use `--render cpu` to select the CPU explicitly.diff --git a/docs/examples.md b/docs/examples.mdindex cf143071..ebf7b57f 100644--- a/docs/examples.md+++ b/docs/examples.md@@ -9,110 +9,110 @@ Browse the [interactive gallery](https://kilnstudio.tools/#/gallery), or open a<table><tr>- <td width="33%" valign="top"><a href="../examples/renders/mechanical-peacock.png"><img src="../examples/renders/mechanical-peacock.png" alt="Brass mechanical peacock with an articulated jewel-colored fan"></a><br><b><a href="../examples/mechanical-peacock.kiln.js">mechanical-peacock</a></b><br>44,688 tris · Claude Opus 5<br><sub>Articulated enamel fan; neck connection repaired by a Codex maintainer agent</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/mechanical-peacock.png"><img src="https://assets.kilnstudio.tools/renders/mechanical-peacock.png" alt="Brass mechanical peacock with an articulated jewel-colored fan"></a><br><b><a href="../examples/mechanical-peacock.kiln.js">mechanical-peacock</a></b><br>44,688 tris · Claude Opus 5<br><sub>Articulated enamel fan; neck connection repaired by a Codex maintainer agent</sub></td></tr><tr>- <td width="33%" valign="top"><a href="../examples/renders/orbital-station.png"><img src="../examples/renders/orbital-station.png" alt="a rotating-torus orbital station with lit window bands, four spokes, a docking hub and solar wings, generated by Kiln"></a><br><b><a href="../examples/orbital-station.kiln.js">orbital-station</a></b><br>15,040 tris · GPT-6 Astra<br><sub>Habitat ring, solar arrays and docking modules</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/abyssal-surveyor.png"><img src="../examples/renders/abyssal-surveyor.png" alt="Custom curved hull, guarded thrusters and articulated sampling arm"></a><br><b><a href="../examples/abyssal-surveyor.kiln.js">abyssal-surveyor</a></b><br>34,456 tris · GPT-6 Astra<br><sub>Custom curved hull, guarded thrusters and articulated sampling arm</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/kestrel-rescue-craft.png"><img src="../examples/renders/kestrel-rescue-craft.png" alt="Sculpted rescue aircraft with articulated tilt rotors"></a><br><b><a href="../examples/kestrel-rescue-craft.kiln.js">kestrel-rescue-craft</a></b><br>54,272 tris · GPT-6 Astra<br><sub>Sculpted rescue aircraft with articulated tilt rotors</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/orbital-station.png"><img src="https://assets.kilnstudio.tools/renders/orbital-station.png" alt="a rotating-torus orbital station with lit window bands, four spokes, a docking hub and solar wings, generated by Kiln"></a><br><b><a href="../examples/orbital-station.kiln.js">orbital-station</a></b><br>15,040 tris · GPT-6 Astra<br><sub>Habitat ring, solar arrays and docking modules</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/abyssal-surveyor.png"><img src="https://assets.kilnstudio.tools/renders/abyssal-surveyor.png" alt="Custom curved hull, guarded thrusters and articulated sampling arm"></a><br><b><a href="../examples/abyssal-surveyor.kiln.js">abyssal-surveyor</a></b><br>34,456 tris · GPT-6 Astra<br><sub>Custom curved hull, guarded thrusters and articulated sampling arm</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/kestrel-rescue-craft.png"><img src="https://assets.kilnstudio.tools/renders/kestrel-rescue-craft.png" alt="Sculpted rescue aircraft with articulated tilt rotors"></a><br><b><a href="../examples/kestrel-rescue-craft.kiln.js">kestrel-rescue-craft</a></b><br>54,272 tris · GPT-6 Astra<br><sub>Sculpted rescue aircraft with articulated tilt rotors</sub></td></tr><tr>- <td width="33%" valign="top"><a href="../examples/renders/solar-sail-courier.png"><img src="../examples/renders/solar-sail-courier.png" alt="Faceted gold sails on four trussed spars"></a><br><b><a href="../examples/solar-sail-courier.kiln.js">solar-sail-courier</a></b><br>27,756 tris · Gemini 3.8 Flash<br><sub>Faceted gold sails on four trussed spars</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/orrery.png"><img src="../examples/renders/orrery.png" alt="a brass orrery with an emissive sun and planets on arms, generated by Kiln"></a><br><b><a href="../examples/orrery.kiln.js">orrery</a></b><br>15,720 tris · Gemini 3.8 Flash<br><sub>Geared arms and orbiting planetary spheres</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/typewriter.png"><img src="../examples/renders/typewriter.png" alt="a cast-iron typewriter with a fan of type bars, brass trim and a sheet in the platen, generated by Kiln"></a><br><b><a href="../examples/typewriter.kiln.js">typewriter</a></b><br>14,128 tris · Muse Spark 1.3<br><sub>Rows of keys and typebars arranged on an arc</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/solar-sail-courier.png"><img src="https://assets.kilnstudio.tools/renders/solar-sail-courier.png" alt="Faceted gold sails on four trussed spars"></a><br><b><a href="../examples/solar-sail-courier.kiln.js">solar-sail-courier</a></b><br>27,756 tris · Gemini 3.8 Flash<br><sub>Faceted gold sails on four trussed spars</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/orrery.png"><img src="https://assets.kilnstudio.tools/renders/orrery.png" alt="a brass orrery with an emissive sun and planets on arms, generated by Kiln"></a><br><b><a href="../examples/orrery.kiln.js">orrery</a></b><br>15,720 tris · Gemini 3.8 Flash<br><sub>Geared arms and orbiting planetary spheres</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/typewriter.png"><img src="https://assets.kilnstudio.tools/renders/typewriter.png" alt="a cast-iron typewriter with a fan of type bars, brass trim and a sheet in the platen, generated by Kiln"></a><br><b><a href="../examples/typewriter.kiln.js">typewriter</a></b><br>14,128 tris · Muse Spark 1.3<br><sub>Rows of keys and typebars arranged on an arc</sub></td></tr><tr>- <td width="33%" valign="top"><a href="../examples/renders/twisting-canopy.png"><img src="../examples/renders/twisting-canopy.png" alt="Twisting canopy with curved ribs and offset supports"></a><br><b><a href="../examples/twisting-canopy.kiln.js">twisting-canopy</a></b><br>5,168 tris · Gemini 3.8 Flash<br><sub>Twisting roof surface with curved ribs and offset supports</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/bench-refractor.png"><img src="../examples/renders/bench-refractor.png" alt="Lofted pedestal, recessed optical opening and focusing slide"></a><br><b><a href="../examples/bench-refractor.kiln.js">bench-refractor</a></b><br>7,388 tris · Muse Spark 1.3<br><sub>Lofted pedestal, recessed optical opening and focusing slide</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/research-vessel.png"><img src="../examples/renders/research-vessel.png" alt="Workboat hull with an offset crane and sliding service platform"></a><br><b><a href="../examples/research-vessel.kiln.js">research-vessel</a></b><br>24,306 tris · GPT-6 Astra<br><sub>Workboat hull with an offset crane and sliding service platform</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/twisting-canopy.png"><img src="https://assets.kilnstudio.tools/renders/twisting-canopy.png" alt="Twisting canopy with curved ribs and offset supports"></a><br><b><a href="../examples/twisting-canopy.kiln.js">twisting-canopy</a></b><br>5,168 tris · Gemini 3.8 Flash<br><sub>Twisting roof surface with curved ribs and offset supports</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/bench-refractor.png"><img src="https://assets.kilnstudio.tools/renders/bench-refractor.png" alt="Lofted pedestal, recessed optical opening and focusing slide"></a><br><b><a href="../examples/bench-refractor.kiln.js">bench-refractor</a></b><br>7,388 tris · Muse Spark 1.3<br><sub>Lofted pedestal, recessed optical opening and focusing slide</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/research-vessel.png"><img src="https://assets.kilnstudio.tools/renders/research-vessel.png" alt="Workboat hull with an offset crane and sliding service platform"></a><br><b><a href="../examples/research-vessel.kiln.js">research-vessel</a></b><br>24,306 tris · GPT-6 Astra<br><sub>Workboat hull with an offset crane and sliding service platform</sub></td></tr><tr>- <td width="33%" valign="top"><a href="../examples/renders/field-gun.png"><img src="../examples/renders/field-gun.png" alt="a Napoleonic field gun on a wooden carriage, generated by Kiln"></a><br><b><a href="../examples/field-gun.kiln.js">field-gun</a></b><br>15,544 tris · Claude Opus 5<br><sub>Cut breech geometry and repeated wheel spokes</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/cathedral.png"><img src="../examples/renders/cathedral.png" alt="a Gothic cathedral with flying buttresses and lit stained glass, generated by Kiln"></a><br><b><a href="../examples/cathedral.kiln.js">cathedral</a></b><br>19,842 tris · Claude Opus 5<br><sub>Repeated stone bays and recessed window openings</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/mech.png"><img src="../examples/renders/mech.png" alt="a walking mech with plated limbs, generated by Kiln"></a><br><b><a href="../examples/mech.kiln.js">mech</a></b><br>18,398 tris · Claude Opus 5<br><sub>Articulated limbs with fitted armour panels</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/field-gun.png"><img src="https://assets.kilnstudio.tools/renders/field-gun.png" alt="a Napoleonic field gun on a wooden carriage, generated by Kiln"></a><br><b><a href="../examples/field-gun.kiln.js">field-gun</a></b><br>15,544 tris · Claude Opus 5<br><sub>Cut breech geometry and repeated wheel spokes</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/cathedral.png"><img src="https://assets.kilnstudio.tools/renders/cathedral.png" alt="a Gothic cathedral with flying buttresses and lit stained glass, generated by Kiln"></a><br><b><a href="../examples/cathedral.kiln.js">cathedral</a></b><br>19,842 tris · Claude Opus 5<br><sub>Repeated stone bays and recessed window openings</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/mech.png"><img src="https://assets.kilnstudio.tools/renders/mech.png" alt="a walking mech with plated limbs, generated by Kiln"></a><br><b><a href="../examples/mech.kiln.js">mech</a></b><br>18,398 tris · Claude Opus 5<br><sub>Articulated limbs with fitted armour panels</sub></td></tr><tr>- <td width="33%" valign="top"><a href="../examples/renders/diving-helmet.png"><img src="../examples/renders/diving-helmet.png" alt="a brass standard diving helmet, generated by Kiln"></a><br><b><a href="../examples/diving-helmet.kiln.js">diving-helmet</a></b><br>16,416 tris · Claude Opus 5<br><sub>Brass housing, glass ports and copper fittings</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/cafe-racer.png"><img src="../examples/renders/cafe-racer.png" alt="a cafe racer motorcycle, generated by Kiln"></a><br><b><a href="../examples/cafe-racer.kiln.js">cafe-racer</a></b><br>16,962 tris · Claude Opus 5<br><sub>Curved frame tubes and a tapered fuel tank</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/penny-farthing.png"><img src="../examples/renders/penny-farthing.png" alt="a penny-farthing bicycle, generated by Kiln"></a><br><b><a href="../examples/penny-farthing.kiln.js">penny-farthing</a></b><br>12,450 tris · Claude Opus 5<br><sub>Curved frame and radial wire spokes</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/diving-helmet.png"><img src="https://assets.kilnstudio.tools/renders/diving-helmet.png" alt="a brass standard diving helmet, generated by Kiln"></a><br><b><a href="../examples/diving-helmet.kiln.js">diving-helmet</a></b><br>16,416 tris · Claude Opus 5<br><sub>Brass housing, glass ports and copper fittings</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/cafe-racer.png"><img src="https://assets.kilnstudio.tools/renders/cafe-racer.png" alt="a cafe racer motorcycle, generated by Kiln"></a><br><b><a href="../examples/cafe-racer.kiln.js">cafe-racer</a></b><br>16,962 tris · Claude Opus 5<br><sub>Curved frame tubes and a tapered fuel tank</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/penny-farthing.png"><img src="https://assets.kilnstudio.tools/renders/penny-farthing.png" alt="a penny-farthing bicycle, generated by Kiln"></a><br><b><a href="../examples/penny-farthing.kiln.js">penny-farthing</a></b><br>12,450 tris · Claude Opus 5<br><sub>Curved frame and radial wire spokes</sub></td></tr><tr>- <td width="33%" valign="top"><a href="../examples/renders/sushi-store.png"><img src="../examples/renders/sushi-store.png" alt="a two-storey Japanese sushi shopfront with a tiled roof, generated by Kiln"></a><br><b><a href="../examples/sushi-store.kiln.js">sushi-store</a></b><br>24,082 tris · Claude Opus 5<br><sub>Layered shopfront, awning and recessed display</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/street-lamp.png"><img src="../examples/renders/street-lamp.png" alt="a cast-iron gas street lamp, generated by Kiln"></a><br><b><a href="../examples/street-lamp.kiln.js">street-lamp</a></b><br>13,036 tris · Claude Opus 5<br><sub>Revolved metal profiles and glass lanterns</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/arcade-cabinet.png"><img src="../examples/renders/arcade-cabinet.png" alt="an upright arcade cabinet, generated by Kiln"></a><br><b><a href="../examples/arcade-cabinet.kiln.js">arcade-cabinet</a></b><br>19,916 tris · Gemini 3.8 Flash<br><sub>Swept cabinet profile with recessed controls</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/sushi-store.png"><img src="https://assets.kilnstudio.tools/renders/sushi-store.png" alt="a two-storey Japanese sushi shopfront with a tiled roof, generated by Kiln"></a><br><b><a href="../examples/sushi-store.kiln.js">sushi-store</a></b><br>24,082 tris · Claude Opus 5<br><sub>Layered shopfront, awning and recessed display</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/street-lamp.png"><img src="https://assets.kilnstudio.tools/renders/street-lamp.png" alt="a cast-iron gas street lamp, generated by Kiln"></a><br><b><a href="../examples/street-lamp.kiln.js">street-lamp</a></b><br>13,036 tris · Claude Opus 5<br><sub>Revolved metal profiles and glass lanterns</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/arcade-cabinet.png"><img src="https://assets.kilnstudio.tools/renders/arcade-cabinet.png" alt="an upright arcade cabinet, generated by Kiln"></a><br><b><a href="../examples/arcade-cabinet.kiln.js">arcade-cabinet</a></b><br>19,916 tris · Gemini 3.8 Flash<br><sub>Swept cabinet profile with recessed controls</sub></td></tr><tr>- <td width="33%" valign="top"><a href="../examples/renders/robot-arm.png"><img src="../examples/renders/robot-arm.png" alt="a six-axis industrial robot arm with a parallel gripper, generated by Kiln"></a><br><b><a href="../examples/robot-arm.kiln.js">robot-arm</a></b><br>15,324 tris · Claude Opus 5<br><sub>Animated chain of articulated joints</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/carousel.png"><img src="../examples/renders/carousel.png" alt="a fairground carousel with a striped canopy and horses, generated by Kiln"></a><br><b><a href="../examples/carousel.kiln.js">carousel</a></b><br>16,356 tris · Gemini 3.8 Flash<br><sub>Rotating platform with repeated horses and supports</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/ferris-wheel.png"><img src="../examples/renders/ferris-wheel.png" alt="a ferris wheel with lit gondolas on a braced frame, generated by Kiln"></a><br><b><a href="../examples/ferris-wheel.kiln.js">ferris-wheel</a></b><br>10,452 tris · Gemini 3.8 Flash<br><sub>Radial steel lattice and suspended cabins</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/robot-arm.png"><img src="https://assets.kilnstudio.tools/renders/robot-arm.png" alt="a six-axis industrial robot arm with a parallel gripper, generated by Kiln"></a><br><b><a href="../examples/robot-arm.kiln.js">robot-arm</a></b><br>15,324 tris · Claude Opus 5<br><sub>Animated chain of articulated joints</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/carousel.png"><img src="https://assets.kilnstudio.tools/renders/carousel.png" alt="a fairground carousel with a striped canopy and horses, generated by Kiln"></a><br><b><a href="../examples/carousel.kiln.js">carousel</a></b><br>16,356 tris · Gemini 3.8 Flash<br><sub>Rotating platform with repeated horses and supports</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/ferris-wheel.png"><img src="https://assets.kilnstudio.tools/renders/ferris-wheel.png" alt="a ferris wheel with lit gondolas on a braced frame, generated by Kiln"></a><br><b><a href="../examples/ferris-wheel.kiln.js">ferris-wheel</a></b><br>10,452 tris · Gemini 3.8 Flash<br><sub>Radial steel lattice and suspended cabins</sub></td></tr><tr>- <td width="33%" valign="top"><a href="../examples/renders/longcase-clock.png"><img src="../examples/renders/longcase-clock.png" alt="a mahogany longcase clock with a painted dial, generated by Kiln"></a><br><b><a href="../examples/longcase-clock.kiln.js">longcase-clock</a></b><br>12,600 tris · Gemini 3.8 Flash<br><sub>Panelled wooden case and an exposed clock face</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/radio-telescope.png"><img src="../examples/renders/radio-telescope.png" alt="a steerable parabolic radio telescope on a pedestal, generated by Kiln"></a><br><b><a href="../examples/radio-telescope.kiln.js">radio-telescope</a></b><br>16,532 tris · Gemini 3.8 Flash<br><sub>Tracking dish with a supporting truss</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/anglerfish.png"><img src="../examples/renders/anglerfish.png" alt="a deep-sea anglerfish with warty skin, a gaping jaw of needle teeth and a glowing lure on an arched illicium, generated by Kiln"></a><br><b><a href="../examples/anglerfish.kiln.js">anglerfish</a></b><br>19,108 tris · Claude Opus 5<br><sub>Curved body, tapered fins and an illuminated lure</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/longcase-clock.png"><img src="https://assets.kilnstudio.tools/renders/longcase-clock.png" alt="a mahogany longcase clock with a painted dial, generated by Kiln"></a><br><b><a href="../examples/longcase-clock.kiln.js">longcase-clock</a></b><br>12,600 tris · Gemini 3.8 Flash<br><sub>Panelled wooden case and an exposed clock face</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/radio-telescope.png"><img src="https://assets.kilnstudio.tools/renders/radio-telescope.png" alt="a steerable parabolic radio telescope on a pedestal, generated by Kiln"></a><br><b><a href="../examples/radio-telescope.kiln.js">radio-telescope</a></b><br>16,532 tris · Gemini 3.8 Flash<br><sub>Tracking dish with a supporting truss</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/anglerfish.png"><img src="https://assets.kilnstudio.tools/renders/anglerfish.png" alt="a deep-sea anglerfish with warty skin, a gaping jaw of needle teeth and a glowing lure on an arched illicium, generated by Kiln"></a><br><b><a href="../examples/anglerfish.kiln.js">anglerfish</a></b><br>19,108 tris · Claude Opus 5<br><sub>Curved body, tapered fins and an illuminated lure</sub></td></tr><tr>- <td width="33%" valign="top"><a href="../examples/renders/hot-air-balloon.png"><img src="../examples/renders/hot-air-balloon.png" alt="a hot-air balloon with a striped envelope and a wicker basket, generated by Kiln"></a><br><b><a href="../examples/hot-air-balloon.kiln.js">hot-air-balloon</a></b><br>9,816 tris · Gemini 3.8 Flash<br><sub>Twenty-four envelope gores above a suspended basket</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/vending-machine.png"><img src="../examples/renders/vending-machine.png" alt="a lit drinks vending machine behind glass, generated by Kiln"></a><br><b><a href="../examples/vending-machine.kiln.js">vending-machine</a></b><br>12,468 tris · Claude Opus 5<br><sub>Recessed product rows and illuminated controls</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/gramophone.png"><img src="../examples/renders/gramophone.png" alt="an acoustic gramophone with a faceted brass horn on a hinged mahogany case, generated by Kiln"></a><br><b><a href="../examples/gramophone.kiln.js">gramophone</a></b><br>10,724 tris · Gemini 3.8 Flash<br><sub>Brass horn, wooden cabinet and hinged lid</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/hot-air-balloon.png"><img src="https://assets.kilnstudio.tools/renders/hot-air-balloon.png" alt="a hot-air balloon with a striped envelope and a wicker basket, generated by Kiln"></a><br><b><a href="../examples/hot-air-balloon.kiln.js">hot-air-balloon</a></b><br>9,816 tris · Gemini 3.8 Flash<br><sub>Twenty-four envelope gores above a suspended basket</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/vending-machine.png"><img src="https://assets.kilnstudio.tools/renders/vending-machine.png" alt="a lit drinks vending machine behind glass, generated by Kiln"></a><br><b><a href="../examples/vending-machine.kiln.js">vending-machine</a></b><br>12,468 tris · Claude Opus 5<br><sub>Recessed product rows and illuminated controls</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/gramophone.png"><img src="https://assets.kilnstudio.tools/renders/gramophone.png" alt="an acoustic gramophone with a faceted brass horn on a hinged mahogany case, generated by Kiln"></a><br><b><a href="../examples/gramophone.kiln.js">gramophone</a></b><br>10,724 tris · Gemini 3.8 Flash<br><sub>Brass horn, wooden cabinet and hinged lid</sub></td></tr><tr>- <td width="33%" valign="top"><a href="../examples/renders/lighthouse.png"><img src="../examples/renders/lighthouse.png" alt="a stone lighthouse with a copper-domed lantern, a gallery rail and a keeper's cottage on a rocky islet, generated by Kiln"></a><br><b><a href="../examples/lighthouse.kiln.js">lighthouse</a></b><br>16,492 tris · Muse Spark 1.3<br><sub>Tower, keeper’s buildings and a rocky base</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/steam-locomotive.png"><img src="../examples/renders/steam-locomotive.png" alt="a green 4-4-0 steam locomotive with a cowcatcher, brass domes and side rods, generated by Kiln"></a><br><b><a href="../examples/steam-locomotive.kiln.js">steam-locomotive</a></b><br>19,256 tris · Muse Spark 1.3<br><sub>Coupled driving wheels and connecting rods</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/windmill.png"><img src="../examples/renders/windmill.png" alt="a Dutch tower windmill in brick with a shingled cap, a stage gallery and four lattice sails, generated by Kiln"></a><br><b><a href="../examples/windmill.kiln.js">windmill</a></b><br>9,872 tris · DeepSeek V4 Flash<br><sub>Masonry tower with a rotating sail assembly</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/lighthouse.png"><img src="https://assets.kilnstudio.tools/renders/lighthouse.png" alt="a stone lighthouse with a copper-domed lantern, a gallery rail and a keeper's cottage on a rocky islet, generated by Kiln"></a><br><b><a href="../examples/lighthouse.kiln.js">lighthouse</a></b><br>16,492 tris · Muse Spark 1.3<br><sub>Tower, keeper’s buildings and a rocky base</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/steam-locomotive.png"><img src="https://assets.kilnstudio.tools/renders/steam-locomotive.png" alt="a green 4-4-0 steam locomotive with a cowcatcher, brass domes and side rods, generated by Kiln"></a><br><b><a href="../examples/steam-locomotive.kiln.js">steam-locomotive</a></b><br>19,256 tris · Muse Spark 1.3<br><sub>Coupled driving wheels and connecting rods</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/windmill.png"><img src="https://assets.kilnstudio.tools/renders/windmill.png" alt="a Dutch tower windmill in brick with a shingled cap, a stage gallery and four lattice sails, generated by Kiln"></a><br><b><a href="../examples/windmill.kiln.js">windmill</a></b><br>9,872 tris · DeepSeek V4 Flash<br><sub>Masonry tower with a rotating sail assembly</sub></td></tr><tr>- <td width="33%" valign="top"><a href="../examples/renders/aircraft-carrier.png"><img src="../examples/renders/aircraft-carrier.png" alt="an aircraft carrier with an angled flight deck, deck markings and an island superstructure, generated by Kiln"></a><br><b><a href="../examples/aircraft-carrier.kiln.js">aircraft-carrier</a></b><br>17,904 tris · Claude Opus 5<br><sub>Flight deck, island and aircraft at ship scale</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/air-defense-radar.png"><img src="../examples/renders/air-defense-radar.png" alt="a truck-mounted air-defence phased-array radar with the panel raised, generated by Kiln"></a><br><b><a href="../examples/air-defense-radar.kiln.js">air-defense-radar</a></b><br>16,094 tris · Claude Opus 5<br><sub>Modelled antenna grid on a mobile platform</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/fighter-jet.png"><img src="../examples/renders/fighter-jet.png" alt="a single-seat multirole fighter on its landing gear with canted tails and open nozzles, generated by Kiln"></a><br><b><a href="../examples/fighter-jet.kiln.js">fighter-jet</a></b><br>18,172 tris · Claude Opus 5<br><sub>Lofted fuselage and tapered wing sections</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/aircraft-carrier.png"><img src="https://assets.kilnstudio.tools/renders/aircraft-carrier.png" alt="an aircraft carrier with an angled flight deck, deck markings and an island superstructure, generated by Kiln"></a><br><b><a href="../examples/aircraft-carrier.kiln.js">aircraft-carrier</a></b><br>17,904 tris · Claude Opus 5<br><sub>Flight deck, island and aircraft at ship scale</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/air-defense-radar.png"><img src="https://assets.kilnstudio.tools/renders/air-defense-radar.png" alt="a truck-mounted air-defence phased-array radar with the panel raised, generated by Kiln"></a><br><b><a href="../examples/air-defense-radar.kiln.js">air-defense-radar</a></b><br>16,094 tris · Claude Opus 5<br><sub>Modelled antenna grid on a mobile platform</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/fighter-jet.png"><img src="https://assets.kilnstudio.tools/renders/fighter-jet.png" alt="a single-seat multirole fighter on its landing gear with canted tails and open nozzles, generated by Kiln"></a><br><b><a href="../examples/fighter-jet.kiln.js">fighter-jet</a></b><br>18,172 tris · Claude Opus 5<br><sub>Lofted fuselage and tapered wing sections</sub></td></tr><tr>- <td width="33%" valign="top"><a href="../examples/renders/comms-satellite.png"><img src="../examples/renders/comms-satellite.png" alt="a geostationary communications satellite with gold thermal blankets, two solar wings and three dish antennas, generated by Kiln"></a><br><b><a href="../examples/comms-satellite.kiln.js">comms-satellite</a></b><br>18,824 tris · Claude Opus 5<br><sub>Solar arrays extending from a compact satellite bus</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/gothic-gatehouse.png"><img src="../examples/renders/gothic-gatehouse.png" alt="a Gothic castle gatehouse with two drum towers, machicolations and a lowered drawbridge, generated by Kiln"></a><br><b><a href="../examples/gothic-gatehouse.kiln.js">gothic-gatehouse</a></b><br>10,428 tris · Gemini 3.8 Flash<br><sub>Twin towers, arched passage and approach bridge</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/comms-satellite.png"><img src="https://assets.kilnstudio.tools/renders/comms-satellite.png" alt="a geostationary communications satellite with gold thermal blankets, two solar wings and three dish antennas, generated by Kiln"></a><br><b><a href="../examples/comms-satellite.kiln.js">comms-satellite</a></b><br>18,824 tris · Claude Opus 5<br><sub>Solar arrays extending from a compact satellite bus</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/gothic-gatehouse.png"><img src="https://assets.kilnstudio.tools/renders/gothic-gatehouse.png" alt="a Gothic castle gatehouse with two drum towers, machicolations and a lowered drawbridge, generated by Kiln"></a><br><b><a href="../examples/gothic-gatehouse.kiln.js">gothic-gatehouse</a></b><br>10,428 tris · Gemini 3.8 Flash<br><sub>Twin towers, arched passage and approach bridge</sub></td></tr><tr>- <td width="33%" valign="top"><a href="../examples/renders/cable-stayed-bridge.png"><img src="../examples/renders/cable-stayed-bridge.png" alt="a cable-stayed road bridge with a portal pylon and fanned stay cables, generated by Kiln"></a><br><b><a href="../examples/cable-stayed-bridge.kiln.js">cable-stayed-bridge</a></b><br>7,580 tris · Omen Alpha<br><sub>Deck segments, pylons and individual stay cables</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/tram.png"><img src="../examples/renders/tram.png" alt="a 1920s city tram on rails with a trolley pole reaching up to the overhead wire, generated by Kiln"></a><br><b><a href="../examples/tram.kiln.js">tram</a></b><br>12,540 tris · Gemini 3.8 Flash<br><sub>Windowed passenger body with roof-mounted fittings</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/tugboat.png"><img src="../examples/renders/tugboat.png" alt="a harbour tugboat with a rope fender belt, an orange funnel and a raised wheelhouse, generated by Kiln"></a><br><b><a href="../examples/tugboat.kiln.js">tugboat</a></b><br>9,856 tris · Gemini 3.8 Flash<br><sub>Lofted hull, deck equipment and raised wheelhouse</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/cable-stayed-bridge.png"><img src="https://assets.kilnstudio.tools/renders/cable-stayed-bridge.png" alt="a cable-stayed road bridge with a portal pylon and fanned stay cables, generated by Kiln"></a><br><b><a href="../examples/cable-stayed-bridge.kiln.js">cable-stayed-bridge</a></b><br>7,580 tris · Omen Alpha<br><sub>Deck segments, pylons and individual stay cables</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/tram.png"><img src="https://assets.kilnstudio.tools/renders/tram.png" alt="a 1920s city tram on rails with a trolley pole reaching up to the overhead wire, generated by Kiln"></a><br><b><a href="../examples/tram.kiln.js">tram</a></b><br>12,540 tris · Gemini 3.8 Flash<br><sub>Windowed passenger body with roof-mounted fittings</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/tugboat.png"><img src="https://assets.kilnstudio.tools/renders/tugboat.png" alt="a harbour tugboat with a rope fender belt, an orange funnel and a raised wheelhouse, generated by Kiln"></a><br><b><a href="../examples/tugboat.kiln.js">tugboat</a></b><br>9,856 tris · Gemini 3.8 Flash<br><sub>Lofted hull, deck equipment and raised wheelhouse</sub></td></tr><tr>- <td width="33%" valign="top"><a href="../examples/renders/deep-sea-diver.png"><img src="../examples/renders/deep-sea-diver.png" alt="an atmospheric diving suit with a copper helmet, jointed limbs and weighted boots, generated by Kiln"></a><br><b><a href="../examples/deep-sea-diver.kiln.js">deep-sea-diver</a></b><br>10,876 tris · Gemini 3.8 Flash<br><sub>Jointed pressure suit with a rigid helmet</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/pumpjack.png"><img src="../examples/renders/pumpjack.png" alt="an oilfield pumpjack with a walking beam, horsehead and counterweights on a skid, generated by Kiln"></a><br><b><a href="../examples/pumpjack.kiln.js">pumpjack</a></b><br>10,236 tris · Gemini 3.8 Flash<br><sub>Walking beam and crank-driven linkage</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/drilling-rig.png"><img src="../examples/renders/drilling-rig.png" alt="a land drilling rig with a derrick over its substructure, mud tanks and a pipe rack, generated by Kiln"></a><br><b><a href="../examples/drilling-rig.kiln.js">drilling-rig</a></b><br>11,048 tris · Gemini 3.8 Flash<br><sub>Derrick, pipework and raised operating platforms</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/deep-sea-diver.png"><img src="https://assets.kilnstudio.tools/renders/deep-sea-diver.png" alt="an atmospheric diving suit with a copper helmet, jointed limbs and weighted boots, generated by Kiln"></a><br><b><a href="../examples/deep-sea-diver.kiln.js">deep-sea-diver</a></b><br>10,876 tris · Gemini 3.8 Flash<br><sub>Jointed pressure suit with a rigid helmet</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/pumpjack.png"><img src="https://assets.kilnstudio.tools/renders/pumpjack.png" alt="an oilfield pumpjack with a walking beam, horsehead and counterweights on a skid, generated by Kiln"></a><br><b><a href="../examples/pumpjack.kiln.js">pumpjack</a></b><br>10,236 tris · Gemini 3.8 Flash<br><sub>Walking beam and crank-driven linkage</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/drilling-rig.png"><img src="https://assets.kilnstudio.tools/renders/drilling-rig.png" alt="a land drilling rig with a derrick over its substructure, mud tanks and a pipe rack, generated by Kiln"></a><br><b><a href="../examples/drilling-rig.kiln.js">drilling-rig</a></b><br>11,048 tris · Gemini 3.8 Flash<br><sub>Derrick, pipework and raised operating platforms</sub></td></tr><tr>- <td width="33%" valign="top"><a href="../examples/renders/harbour-crane.png"><img src="../examples/renders/harbour-crane.png" alt="a rail-mounted harbour crane with a luffing jib and a spreader on the hoist, generated by Kiln"></a><br><b><a href="../examples/harbour-crane.kiln.js">harbour-crane</a></b><br>10,568 tris · Gemini 3.8 Flash<br><sub>Braced steel frame with suspended lifting gear</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/crawler-crane.png"><img src="../examples/renders/crawler-crane.png" alt="a lattice-boom crawler crane on tracks with the hook block hanging, generated by Kiln"></a><br><b><a href="../examples/crawler-crane.kiln.js">crawler-crane</a></b><br>12,660 tris · MiniMax M3<br><sub>Repeated lattice boom sections on a tracked base</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/excavator.png"><img src="../examples/renders/excavator.png" alt="a tracked hydraulic excavator with the boom, stick and bucket curled in, generated by Kiln"></a><br><b><a href="../examples/excavator.kiln.js">excavator</a></b><br>12,400 tris · Omen Alpha<br><sub>Articulated boom, bucket and hydraulic rams</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/harbour-crane.png"><img src="https://assets.kilnstudio.tools/renders/harbour-crane.png" alt="a rail-mounted harbour crane with a luffing jib and a spreader on the hoist, generated by Kiln"></a><br><b><a href="../examples/harbour-crane.kiln.js">harbour-crane</a></b><br>10,568 tris · Gemini 3.8 Flash<br><sub>Braced steel frame with suspended lifting gear</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/crawler-crane.png"><img src="https://assets.kilnstudio.tools/renders/crawler-crane.png" alt="a lattice-boom crawler crane on tracks with the hook block hanging, generated by Kiln"></a><br><b><a href="../examples/crawler-crane.kiln.js">crawler-crane</a></b><br>12,660 tris · MiniMax M3<br><sub>Repeated lattice boom sections on a tracked base</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/excavator.png"><img src="https://assets.kilnstudio.tools/renders/excavator.png" alt="a tracked hydraulic excavator with the boom, stick and bucket curled in, generated by Kiln"></a><br><b><a href="../examples/excavator.kiln.js">excavator</a></b><br>12,400 tris · Omen Alpha<br><sub>Articulated boom, bucket and hydraulic rams</sub></td></tr><tr>- <td width="33%" valign="top"><a href="../examples/renders/printing-press.png"><img src="../examples/renders/printing-press.png" alt="a wooden hand printing press with a screw platen, type cases and ink balls, generated by Kiln"></a><br><b><a href="../examples/printing-press.kiln.js">printing-press</a></b><br>10,188 tris · Gemini 3.8 Flash<br><sub>Rollers, drive wheels and an exposed feed mechanism</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/pipe-organ.png"><img src="../examples/renders/pipe-organ.png" alt="a church pipe organ with ranks of display pipes above a console and pedalboard, generated by Kiln"></a><br><b><a href="../examples/pipe-organ.kiln.js">pipe-organ</a></b><br>10,340 tris · Gemini 3.8 Flash<br><sub>Pipe ranks, wooden casework and keyboard console</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/planetarium-projector.png"><img src="../examples/renders/planetarium-projector.png" alt="a dumbbell planetarium projector with two star globes on a trunnion mount, generated by Kiln"></a><br><b><a href="../examples/planetarium-projector.kiln.js">planetarium-projector</a></b><br>10,932 tris · Gemini 3.8 Flash<br><sub>Dark optical housings on a central support</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/printing-press.png"><img src="https://assets.kilnstudio.tools/renders/printing-press.png" alt="a wooden hand printing press with a screw platen, type cases and ink balls, generated by Kiln"></a><br><b><a href="../examples/printing-press.kiln.js">printing-press</a></b><br>10,188 tris · Gemini 3.8 Flash<br><sub>Rollers, drive wheels and an exposed feed mechanism</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/pipe-organ.png"><img src="https://assets.kilnstudio.tools/renders/pipe-organ.png" alt="a church pipe organ with ranks of display pipes above a console and pedalboard, generated by Kiln"></a><br><b><a href="../examples/pipe-organ.kiln.js">pipe-organ</a></b><br>10,340 tris · Gemini 3.8 Flash<br><sub>Pipe ranks, wooden casework and keyboard console</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/planetarium-projector.png"><img src="https://assets.kilnstudio.tools/renders/planetarium-projector.png" alt="a dumbbell planetarium projector with two star globes on a trunnion mount, generated by Kiln"></a><br><b><a href="../examples/planetarium-projector.kiln.js">planetarium-projector</a></b><br>10,932 tris · Gemini 3.8 Flash<br><sub>Dark optical housings on a central support</sub></td></tr><tr>- <td width="33%" valign="top"><a href="../examples/renders/astronomical-clock.png"><img src="../examples/renders/astronomical-clock.png" alt="an astronomical clock with a gilt astrolabe dial in a carved stone case, generated by Kiln"></a><br><b><a href="../examples/astronomical-clock.kiln.js">astronomical-clock</a></b><br>9,324 tris · Gemini 3.8 Flash<br><sub>Layered astronomical dial and exposed mechanisms</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/espresso-machine.png"><img src="../examples/renders/espresso-machine.png" alt="a three-group commercial espresso machine with portafilters, steam wands and cups warming on top, generated by Kiln"></a><br><b><a href="../examples/espresso-machine.kiln.js">espresso-machine</a></b><br>19,080 tris · GLM 5.3 Flash<br><sub>Polished metal housing, fittings and group heads</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/pinball-machine.png"><img src="../examples/renders/pinball-machine.png" alt="a pinball machine with a lit backbox, a glassed playfield and a rear cabinet bay, generated by Kiln"></a><br><b><a href="../examples/pinball-machine.kiln.js">pinball-machine</a></b><br>8,700 tris · GLM 5.3 Flash<br><sub>Sloped playfield cabinet and raised backbox</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/astronomical-clock.png"><img src="https://assets.kilnstudio.tools/renders/astronomical-clock.png" alt="an astronomical clock with a gilt astrolabe dial in a carved stone case, generated by Kiln"></a><br><b><a href="../examples/astronomical-clock.kiln.js">astronomical-clock</a></b><br>9,324 tris · Gemini 3.8 Flash<br><sub>Layered astronomical dial and exposed mechanisms</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/espresso-machine.png"><img src="https://assets.kilnstudio.tools/renders/espresso-machine.png" alt="a three-group commercial espresso machine with portafilters, steam wands and cups warming on top, generated by Kiln"></a><br><b><a href="../examples/espresso-machine.kiln.js">espresso-machine</a></b><br>19,080 tris · GLM 5.3 Flash<br><sub>Polished metal housing, fittings and group heads</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/pinball-machine.png"><img src="https://assets.kilnstudio.tools/renders/pinball-machine.png" alt="a pinball machine with a lit backbox, a glassed playfield and a rear cabinet bay, generated by Kiln"></a><br><b><a href="../examples/pinball-machine.kiln.js">pinball-machine</a></b><br>8,700 tris · GLM 5.3 Flash<br><sub>Sloped playfield cabinet and raised backbox</sub></td></tr><tr>- <td width="33%" valign="top"><a href="../examples/renders/trebuchet.png"><img src="../examples/renders/trebuchet.png" alt="a counterweight trebuchet with a slung beam, a ballast box and the sling laid out on the ground, generated by Kiln"></a><br><b><a href="../examples/trebuchet.kiln.js">trebuchet</a></b><br>2,652 tris · Gemini 3.8 Flash<br><sub>Timber frame, counterweight and throwing arm</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/rigid-airship.png"><img src="../examples/renders/rigid-airship.png" alt="a 1930s rigid passenger airship moored at its mast, with a promenade window row, engine cars and a cruciform tail, generated by Kiln"></a><br><b><a href="../examples/rigid-airship.kiln.js">rigid-airship</a></b><br>11,764 tris · GPT-6 Astra<br><sub>Lofted envelope with gondola and tail surfaces</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/blast-furnace.png"><img src="../examples/renders/blast-furnace.png" alt="a blast furnace with three hot-blast stoves, downcomer piping, galleries and a cast house, generated by Kiln"></a><br><b><a href="../examples/blast-furnace.kiln.js">blast-furnace</a></b><br>11,964 tris · GPT-6 Astra<br><sub>Furnace stack, hot-blast stoves and connecting pipework</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/trebuchet.png"><img src="https://assets.kilnstudio.tools/renders/trebuchet.png" alt="a counterweight trebuchet with a slung beam, a ballast box and the sling laid out on the ground, generated by Kiln"></a><br><b><a href="../examples/trebuchet.kiln.js">trebuchet</a></b><br>2,652 tris · Gemini 3.8 Flash<br><sub>Timber frame, counterweight and throwing arm</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/rigid-airship.png"><img src="https://assets.kilnstudio.tools/renders/rigid-airship.png" alt="a 1930s rigid passenger airship moored at its mast, with a promenade window row, engine cars and a cruciform tail, generated by Kiln"></a><br><b><a href="../examples/rigid-airship.kiln.js">rigid-airship</a></b><br>11,764 tris · GPT-6 Astra<br><sub>Lofted envelope with gondola and tail surfaces</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/blast-furnace.png"><img src="https://assets.kilnstudio.tools/renders/blast-furnace.png" alt="a blast furnace with three hot-blast stoves, downcomer piping, galleries and a cast house, generated by Kiln"></a><br><b><a href="../examples/blast-furnace.kiln.js">blast-furnace</a></b><br>11,964 tris · GPT-6 Astra<br><sub>Furnace stack, hot-blast stoves and connecting pipework</sub></td></tr><tr>- <td width="33%" valign="top"><a href="../examples/renders/clock-tower.png"><img src="../examples/renders/clock-tower.png" alt="a Gothic clock tower with gilt dials, a louvred belfry, crocketed pinnacles and a leaded spire, generated by Kiln"></a><br><b><a href="../examples/clock-tower.kiln.js">clock-tower</a></b><br>11,664 tris · GPT-6 Astra<br><sub>Four clock faces within a detailed tower housing</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/nautilus-habitat.png"><img src="../examples/renders/nautilus-habitat.png" alt="Spiral shell roof around an open two-level habitat"></a><br><b><a href="../examples/nautilus-habitat.kiln.js">nautilus-habitat</a></b><br>41,380 tris · GPT-6 Astra<br><sub>Spiral shell roof around an open two-level habitat</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/clock-tower.png"><img src="https://assets.kilnstudio.tools/renders/clock-tower.png" alt="a Gothic clock tower with gilt dials, a louvred belfry, crocketed pinnacles and a leaded spire, generated by Kiln"></a><br><b><a href="../examples/clock-tower.kiln.js">clock-tower</a></b><br>11,664 tris · GPT-6 Astra<br><sub>Four clock faces within a detailed tower housing</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/nautilus-habitat.png"><img src="https://assets.kilnstudio.tools/renders/nautilus-habitat.png" alt="Spiral shell roof around an open two-level habitat"></a><br><b><a href="../examples/nautilus-habitat.kiln.js">nautilus-habitat</a></b><br>41,380 tris · GPT-6 Astra<br><sub>Spiral shell roof around an open two-level habitat</sub></td></tr><tr>- <td width="33%" valign="top"><a href="../examples/renders/ribbon-tea-pavilion.png"><img src="../examples/renders/ribbon-tea-pavilion.png" alt="Curved timber roof over an open tea pavilion"></a><br><b><a href="../examples/ribbon-tea-pavilion.kiln.js">ribbon-tea-pavilion</a></b><br>15,980 tris · Gemini 3.8 Flash<br><sub>Curved timber roof over an open tea pavilion</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/seed-vault.png"><img src="../examples/renders/seed-vault.png" alt="Open seed-pod shell around a specimen carousel"></a><br><b><a href="../examples/seed-vault.kiln.js">seed-vault</a></b><br>33,632 tris · Gemini 3.8 Flash<br><sub>Open seed-pod shell around a specimen carousel</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/kinetic-wave.png"><img src="../examples/renders/kinetic-wave.png" alt="Articulated teal and bronze fins on a dark plinth"></a><br><b><a href="../examples/kinetic-wave.kiln.js">kinetic-wave</a></b><br>18,960 tris · Gemini 3.8 Flash<br><sub>Articulated teal and bronze fins on a dark plinth</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/ribbon-tea-pavilion.png"><img src="https://assets.kilnstudio.tools/renders/ribbon-tea-pavilion.png" alt="Curved timber roof over an open tea pavilion"></a><br><b><a href="../examples/ribbon-tea-pavilion.kiln.js">ribbon-tea-pavilion</a></b><br>15,980 tris · Gemini 3.8 Flash<br><sub>Curved timber roof over an open tea pavilion</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/seed-vault.png"><img src="https://assets.kilnstudio.tools/renders/seed-vault.png" alt="Open seed-pod shell around a specimen carousel"></a><br><b><a href="../examples/seed-vault.kiln.js">seed-vault</a></b><br>33,632 tris · Gemini 3.8 Flash<br><sub>Open seed-pod shell around a specimen carousel</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/kinetic-wave.png"><img src="https://assets.kilnstudio.tools/renders/kinetic-wave.png" alt="Articulated teal and bronze fins on a dark plinth"></a><br><b><a href="../examples/kinetic-wave.kiln.js">kinetic-wave</a></b><br>18,960 tris · Gemini 3.8 Flash<br><sub>Articulated teal and bronze fins on a dark plinth</sub></td></tr><tr>- <td width="33%" valign="top"><a href="../examples/renders/alpine-cable-terminal.png"><img src="../examples/renders/alpine-cable-terminal.png" alt="Timber station with an exposed pulley and suspended cabin"></a><br><b><a href="../examples/alpine-cable-terminal.kiln.js">alpine-cable-terminal</a></b><br>9,968 tris · Gemini 3.8 Flash<br><sub>Timber station with an exposed pulley and suspended cabin</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/deco-radio.png"><img src="../examples/renders/deco-radio.png" alt="Stepped walnut cabinet with a brass grille and tuning controls"></a><br><b><a href="../examples/deco-radio.kiln.js">deco-radio</a></b><br>13,216 tris · Gemini 3.8 Flash<br><sub>Stepped walnut cabinet with a brass grille and tuning controls</sub></td>- <td width="33%" valign="top"><a href="../examples/renders/polar-rover.png"><img src="../examples/renders/polar-rover.png" alt="Tracked expedition rover with folding solar panels and instruments"></a><br><b><a href="../examples/polar-rover.kiln.js">polar-rover</a></b><br>22,478 tris · Gemini 3.8 Flash<br><sub>Tracked expedition rover with folding solar panels and instruments</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/alpine-cable-terminal.png"><img src="https://assets.kilnstudio.tools/renders/alpine-cable-terminal.png" alt="Timber station with an exposed pulley and suspended cabin"></a><br><b><a href="../examples/alpine-cable-terminal.kiln.js">alpine-cable-terminal</a></b><br>9,968 tris · Gemini 3.8 Flash<br><sub>Timber station with an exposed pulley and suspended cabin</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/deco-radio.png"><img src="https://assets.kilnstudio.tools/renders/deco-radio.png" alt="Stepped walnut cabinet with a brass grille and tuning controls"></a><br><b><a href="../examples/deco-radio.kiln.js">deco-radio</a></b><br>13,216 tris · Gemini 3.8 Flash<br><sub>Stepped walnut cabinet with a brass grille and tuning controls</sub></td>+ <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/polar-rover.png"><img src="https://assets.kilnstudio.tools/renders/polar-rover.png" alt="Tracked expedition rover with folding solar panels and instruments"></a><br><b><a href="../examples/polar-rover.kiln.js">polar-rover</a></b><br>22,478 tris · Gemini 3.8 Flash<br><sub>Tracked expedition rover with folding solar panels and instruments</sub></td></tr></table>@@ -133,12 +133,12 @@ backwards, or an arm that swings through its own base gets caught before the GLB<table><tr>- <td width="50%" valign="top"><img src="../examples/renders/robot-arm.gif" alt="an industrial robot arm running a pick-and-place cycle"><br><b><a href="../examples/robot-arm.kiln.js">robot-arm</a></b><br><sub>a six-axis pick-and-place cycle</sub></td>- <td width="50%" valign="top"><img src="../examples/renders/carousel.gif" alt="a fairground carousel turning, with horses rising and falling"><br><b><a href="../examples/carousel.kiln.js">carousel</a></b><br><sub>a turn, with the horses on their own phase</sub></td>+ <td width="50%" valign="top"><img src="https://assets.kilnstudio.tools/renders/robot-arm.gif" alt="an industrial robot arm running a pick-and-place cycle"><br><b><a href="../examples/robot-arm.kiln.js">robot-arm</a></b><br><sub>a six-axis pick-and-place cycle</sub></td>+ <td width="50%" valign="top"><img src="https://assets.kilnstudio.tools/renders/carousel.gif" alt="a fairground carousel turning, with horses rising and falling"><br><b><a href="../examples/carousel.kiln.js">carousel</a></b><br><sub>a turn, with the horses on their own phase</sub></td></tr><tr>- <td width="50%" valign="top"><img src="../examples/renders/orrery.gif" alt="an orrery with planets orbiting a lit sun"><br><b><a href="../examples/orrery.kiln.js">orrery</a></b><br><sub>planets on nested arms off one drive</sub></td>- <td width="50%" valign="top"><img src="../examples/renders/radio-telescope.gif" alt="a radio telescope dish slewing in azimuth and elevation"><br><b><a href="../examples/radio-telescope.kiln.js">radio-telescope</a></b><br><sub>a slew in azimuth and elevation</sub></td>+ <td width="50%" valign="top"><img src="https://assets.kilnstudio.tools/renders/orrery.gif" alt="an orrery with planets orbiting a lit sun"><br><b><a href="../examples/orrery.kiln.js">orrery</a></b><br><sub>planets on nested arms off one drive</sub></td>+ <td width="50%" valign="top"><img src="https://assets.kilnstudio.tools/renders/radio-telescope.gif" alt="a radio telescope dish slewing in azimuth and elevation"><br><b><a href="../examples/radio-telescope.kiln.js">radio-telescope</a></b><br><sub>a slew in azimuth and elevation</sub></td></tr></table>diff --git a/docs/install.md b/docs/install.mdindex 14171e65..dbc3cace 100644--- a/docs/install.md+++ b/docs/install.md@@ -92,13 +92,19 @@ by the package smoke alongside the native image dependency.## Install from the repository```sh-git clone https://github.com/matthew-kissinger/kiln+git clone --filter=blob:none https://github.com/matthew-kissinger/kilncd kilnbun install --frozen-lockfilebun run build:runtimenode scripts/create-workspace.mjs ../my-assets --harness opencode```+`--filter=blob:none` checks out the current tree in full and leaves historical+file contents on the server, so the clone transfers less and finishes sooner.+Git fetches an old file version on demand the first time something asks for one,+which needs network access. Use a plain `git clone` if you want the entire+history available offline.+Setup checks that the Node runtime, bundles, dependencies and selected skills areavailable before writing the workspace. It does not install an agent or sign in onyour behalf. Open the generated `START.md` for the selected harness's launch steps.diff --git a/docs/plans/repo-size-and-r2-migration-2026-09-10.md b/docs/plans/repo-size-and-r2-migration-2026-09-10.mdnew file mode 100644index 00000000..4637ba9b--- /dev/null+++ b/docs/plans/repo-size-and-r2-migration-2026-09-10.md@@ -0,0 +1,480 @@+# Repository size reduction and site-asset migration++A fresh clone of this repository costs 440 MB and 79 seconds. The owner noticed+this after open-sourcing the project, and the cause is site and social media+material carried in git history rather than anything the tools need. This plan+removes that material, moves the gallery posters to Cloudflare R2 without+changing their bytes, and fixes the setup rough edges found while installing+Kiln as an MCP server from a clean checkout.++This document is the reference for that work. Each task carries a state. Any+deviation from the invariants below is a defect in the execution, not a+judgement call to make mid-flight.++## Measured baseline++Every number here was measured on 2026-09-10 against `main` at `5b903fb`. They+are the comparison set for verifying the work, and they should not be re-derived+from memory later.++| Measurement | Value |+| --- | --- |+| Full clone, wall clock | 79 s |+| Full clone, on disk | 440 MB (227 MB `.git` + 214 MB checkout) |+| Packed history | 226.06 MiB, 3206 objects, 2244 blobs |+| Uncompressed history | 355.4 MB across 176 commits |+| `git clone --depth=1` | 54 s, 325 MB |+| `git clone --filter=blob:none` | 36 s, 325 MB |+| `--depth=1 --filter=blob:none --sparse` | 1 s, 616 KB |++History bytes by directory:++| Path | History | Checkout | Notes |+| --- | --- | --- | --- |+| `assets/video/` | 171.3 MB | 69 MB | 37 blobs; four stored revisions of `kiln-launch.mp4` (27, 35, 38, 43 MB). Referenced by no file in the repository. |+| `examples/renders/` | 117.1 MB | 107.9 MB | 84 PNG at 1024x1024, average 1316 KB; 4 GIF at 1.9 MB; 83 JSON receipts |+| `dist/` | 29.2 MB | 11 MB | 22 blobs of committed build output |+| `assets/gallery/` | 9.3 MB | 7.4 MB | README-facing grid and three GIFs |+| everything else | 28.5 MB | — | source, docs, example programs |++Plugin install cost, measured by installing from GitHub and inspecting+`~/.claude/plugins`:++| Component | Size |+| --- | --- |+| Marketplace clone | 325 MB |+| Plugin cache, repository files | 214 MB |+| Plugin cache, `node_modules` (189 packages, installed automatically) | 414 MB |+| Total for one install | 953 MB |++The repository is counted twice per install, once in the marketplace clone and+once in the versioned cache copy. 539 MB of the 953 MB is repository content.+The whole `~/.claude/plugins` directory measured 958 MB during the check; the+extra 6.3 MB is the pre-existing `claude-plugins-official` marketplace and is+not attributable to this repository.++## Targets++| Outcome | Now | Target |+| --- | --- | --- |+| Uncompressed history | 355.4 MB | ~29 MB |+| Full clone wall clock | 79 s | a few seconds |+| One plugin install | 953 MB | ~480 MB |++The residual 414 MB of `node_modules` is inherent to the dependency set and is+not in scope.++## Invariants++These must hold at every checkpoint. A task that would break one is wrong.++| ID | Invariant | How it is checked |+| --- | --- | --- |+| I1 | Poster PNG bytes never change | Each file's sha256 still equals the `imageHash` in its `examples/*.provenance.json`. All 83 provenance files carry a `posterReceipt`, and the receipt also names the capturing GPU and driver, so a re-encode would silently void a provenance claim the project makes publicly. |+| I2 | `dist/mcp-server.mjs` at HEAD is byte-identical to a fresh build | `bun run build:runtime` leaves `git status` clean. This held at baseline and must keep holding. |+| I3 | The MCP server exposes 13 tools | `tools/list` over stdio returns 13 for `[email protected]` on protocol `2025-06-18`. |+| I4 | The README video keeps playing | The `user-attachments` URL on README line 16 is GitHub CDN content outside the git object database. It must remain the README's video source and must never be repointed at an in-repo file. |+| I5 | The gallery site still verifies | `site/scripts/verify-assets.mjs` passes, including its poster hash checks. It runs in `pages.yml`. |+| I6 | Tests and lint pass | `bun run test` and `bun run lint`. Lint is an error-level gate in CI. |+| I7 | Plugin installs keep resolving dependencies | `package.json` and `bun.lock` must both remain at the repository root. Claude Code runs `bun install --frozen-lockfile --ignore-scripts` only when both are present; committed `dist/` is required because no build step ever runs during an install. |++## Decisions++| ID | Decision | State |+| --- | --- | --- |+| D1 | Local archive path for the video | Open; default `~/kiln-media-archive/` |+| D2 | R2 bucket name and custom domain | Open; default bucket `kiln-assets`, domain `assets.kilnstudio.tools` |+| D3 | Move `assets/gallery/` to R2, or keep in repository | Open; default keep, so the README stays self-contained |+| D4 | New write target for `scripts/hero-shots.ts` and `scripts/anim-gifs.ts`, which currently write into `examples/renders/` | Open; default a gitignored local directory plus a separate upload step |+| D5 | Force-push approval | Deferred to the moment of pushing, task 3.11 |++## Phase 0 — Preserve++Nothing here is destructive. It runs first because the owner intends to post the+launch video to LinkedIn and an AI game development subreddit the same day.++| ID | Task | State |+| --- | --- | --- |+| 0.1 | Create the archive directory outside the repository, per D1 | Done |+| 0.2 | Copy `assets/video/` to the archive: `kiln-launch.mp4` 43 MB, `gallery-take.mp4` 10 MB, `showcase/` 15 MB, poster 1.3 MB | Done |+| 0.3 | Verify every copied file by sha256 against its original | Done |+| 0.4 | Confirm the README `user-attachments` video URL resolves independently of the repository | Done |+| 0.5 | Take a `git clone --mirror` backup to a safe location | Done |+| 0.6 | Verify the mirror: commit count and pack size match the baseline | Done |+| 0.7 | Record HEAD sha, commit count and pack size for post-rewrite comparison | Done |+| 0.8 | Confirm fork count, open PR count and star count with `gh`, establishing the real blast radius | Done |++## Phase 1 — Reductions that need no rewrite++Independently shippable. Task 1.1 alone takes a clone from 79 s to 36 s.++| ID | Task | State |+| --- | --- | --- |+| 1.1 | Document `git clone --filter=blob:none` as the recommended clone in `README.md` | Done |+| 1.2 | Document the same in `docs/install.md` | Done |+| 1.3 | Verify links and rendering are unaffected | Done |++## Phase 2 — Site assets to Cloudflare R2++Additive until task 2.8. The posters move byte-for-byte, which is what keeps I1+intact; this is the reason the plan uploads rather than optimizes.++| ID | Task | State |+| --- | --- | --- |+| 2.1 | Create the R2 bucket, per D2 | Done |+| 2.2 | Configure public access and the custom domain, including DNS | Done |+| 2.3 | Upload the 84 poster PNGs byte-for-byte, with no re-encode | Done |+| 2.4 | Upload the 4 GIFs | Done |+| 2.5 | Verify each uploaded object's sha256 equals the local file's | Done |+| 2.6 | Verify each poster's sha256 equals the `imageHash` in its provenance sidecar. This is the I1 gate | Done |+| 2.7 | Verify CDN URLs return 200 with correct `content-type` | Done |+| 2.8 | Repoint `docs/examples.md` at absolute CDN URLs | Done |+| 2.9 | Update `site/scripts/verify-assets.mjs` to fetch posters, preserving the hash check, with a local cache so CI does not depend on network availability | Done |+| 2.10 | Audit and update `site/scripts/build-example-poster.mjs`, which reads `examples/renders` | Done |+| 2.11 | Update the write targets in `scripts/hero-shots.ts` and `scripts/anim-gifs.ts`, per D4 | Done |+| 2.12 | Run `verify-assets.mjs` locally; it must pass | Done; green on CI run against PR #63 |+| 2.13 | Run `bun run test` and `bun run lint`; both must pass | Done |+| 2.14 | Push to a branch and confirm `pages.yml` passes, before any rewrite | Done; green on CI run against PR #63 |+| 2.15 | Repoint `site/scripts/build-assets.mjs`, which reads posters through a `RENDERS` constant and scrapes poster hrefs out of `docs/examples.md`. Added during execution: a literal search for `examples/renders` did not find it | Done |+| 2.16 | Extract the poster source into `site/scripts/posters.mjs` so the build and the verifier share one fetch-and-cache path. Added during execution | Done |+| 2.17 | Add `scripts/upload-posters.mjs` to publish `.posters/` to the bucket, refusing any image whose hash disagrees with an existing receipt. Added during execution | Done |+| 2.18 | Fix `src/__tests__/examples.test.ts`, whose GIF check matched a repository-relative `src=` attribute. Added during execution: this was a regression from task 2.8 | Done |++## Phase 3 — History rewrite++The only irreversible phase. One pass, never two: each rewrite invalidates every+commit sha, so batching all removals into a single pass costs contributors one+disruption instead of several.++| ID | Task | State |+| --- | --- | --- |+| 3.1 | Install `git-filter-repo`. `pipx` and `pip3` are both absent on this machine, so it came from the distribution package instead: `pacman -S git-filter-repo`, version 2.47.0-3 | Done |+| 3.2 | Commit all Phase 1 and Phase 2 changes first, so the rewrite carries them | Pending |+| 3.3 | Re-verify fork and PR counts immediately before proceeding | Done; 0 forks, 0 open pull requests, 0 open issues, 21 stars, unchanged from the Phase 0 reading |+| 3.4 | Add `.gitignore` guards for the removed paths | Done; `examples/renders/*.png`, `examples/renders/*.gif` and `assets/video/` are ignored, inert while the files are still tracked and effective the moment 3.5 removes them |+| 3.4a | Move the render-existence assertions off `readdir`. Added during execution; resolved by splitting the check across the two layers that can each honestly make it. See the Phase 3 record | Done |+| 3.5 | Single `git filter-repo` pass removing `assets/video/`, `examples/renders/*.png` and `examples/renders/*.gif` | Done in rehearsal; see the Phase 3 rehearsal record |+| 3.6 | Handle `dist/` separately. `filter-repo` removes a path from all history and cannot retain only the newest blob, so purge `dist/` entirely and re-add the current `dist/` in one fresh commit, leaving it stored once | Done in rehearsal; see the Phase 3 rehearsal record |+| 3.7 | Verify `dist/mcp-server.mjs` at the new HEAD is byte-identical to the pre-rewrite file, then that `bun run build:runtime` still leaves the tree clean. This is the I2 gate | Done in rehearsal; see the Phase 3 rehearsal record |+| 3.8 | Verify pack size, commit count, and that HEAD content matches the pre-rewrite checkout except for removed paths | Done in rehearsal; see the Phase 3 rehearsal record |+| 3.9 | Run `bun run test` and `bun run lint` on the rewritten tree | Done in rehearsal; see the Phase 3 rehearsal record |+| 3.10 | Clone from the local rewritten repository; record time and size | Done in rehearsal; see the Phase 3 rehearsal record |+| 3.11 | Force-push. Requires explicit approval at this moment, per D5 | Pending |+| 3.12 | Clone from GitHub; record the real-world time and size against the targets | Pending |+| 3.13 | Confirm `ci.yml` and `pages.yml` are green on the new `main` | Pending |+| 3.14 | Re-validate the plugin path end to end: marketplace add, install, `tools/list` returns 13, then uninstall and clear the cache. Mandatory because 3.6 changed how `dist/` reaches HEAD. This is the I3 and I7 gate | Pending |++## Phase 4 — Setup and error-legibility fixes++Found by installing Kiln from a clean checkout and driving its MCP server. These+are independent of Phases 0 to 3 and can ship at any time. The engine itself was+sound throughout: a clean-room workspace authored, validated, rendered and saved+a 96-triangle workbench, and a separate CLI process resolved the same+content-addressed ref and reused the build.++| ID | Task | State |+| --- | --- | --- |+| 4.0 | Independently reproduce findings 4.5 to 4.9 before editing. They came from a delegated run and are not yet personally confirmed | Pending |+| 4.1 | `--harness claude` writes skills to `./skills/`, so the harness registers none of them; they work only because `CLAUDE.md` instructs the agent to read them. Either install to `.claude/skills/` or correct `START.md`, which currently states they are installed | Pending |+| 4.2 | `kiln_render` reports only "Generated asset execution was rejected." on a syntax error, while `kiln_validate` on the same source reports `Syntax error: Unexpected token (2:39)`. Surface the underlying message | Pending |+| 4.3 | The same rejection for an unknown helper never names the identifier. Name it and point at `kiln_list_primitives` | Pending |+| 4.4 | The MCP server sends an empty `instructions` field, so a client reading only `.mcp.json` gets 13 tools with no indication that `programRef` should be reused rather than re-sending source | Pending |+| 4.5 | `.mcp.json` records an absolute `node` path, which breaks for `nvm` users after `nvm use`. `--repair` fixes it; `START.md` frames repair as relocation-only | Pending |+| 4.6 | `scripts/create-workspace.mjs` exits 0 on a usage error and names `kiln-init`, which the caller did not invoke | Pending |+| 4.7 | `START.md` offers no copy-pasteable first command | Pending |+| 4.8 | Reconcile metric naming: top-level `materials: 8` against `qaReport` `materialCount: 2` and `drawCalls: 8` for one render | Pending |+| 4.9 | Reconsider `kiln_validate` returning `valid: true` for a program using an undefined helper | Pending |++## Phase 5 — Test-artifact cleanup++| ID | Task | State |+| --- | --- | --- |+| 5.1 | Remove 2.3 GB of scratchpad test clones | Held until Phase 3 verifies |+| 5.2 | Remove the test plugin install and marketplace entry | Done; `claude plugin list` reports none and only `claude-plugins-official` remains |++## Rollback++Phases 0, 1, 4 and 5 are ordinary commits or local file operations and revert+normally. Phase 2 is additive until task 2.8, and 2.8 to 2.11 are revertible+commits. Phase 3 is recoverable only from the task 0.5 mirror, which is why 0.5+precedes everything and why 3.11 carries its own approval gate.++## Rejected approaches++Recorded so they are not reintroduced.++**Re-encoding the poster PNGs.** The files are written by+`render-service/src/renderer.mjs` with `deflateLevel: 1, filterType: 0`, a+deliberate choice noted in that file as roughly ten times faster to encode. A+lossless re-encode would take 108 MB to about 7 MB. It was rejected because+image tokens are `ceil(width / 28) * ceil(height / 28)` visual tokens and do not+depend on file size at all, so the change saves no context; because it would+alter every `imageHash` and void all 83 poster receipts, breaking I1; and+because the remaining benefit, transfer latency, was never measured against the+encode-time cost it would reintroduce. Revisit only with that measurement in+hand.++**Treating committed `dist/` as a packaging defect.** A bundle built with+`--packages=external` does fail from a bare `git clone` with no `node_modules`.+That is not what a plugin install does. A real install from GitHub was verified:+Claude Code ran `bun install --frozen-lockfile --ignore-scripts`, produced 189+packages including `sharp`, `manifold-3d` and `gltf-validator`, and the server+started and listed 13 tools. Committing `dist/` is correct and required, since+no build step runs during an install. See I7.++**Lossy formats for agent-facing renders.** WebP or JPEG would shrink the+gallery further, but the vision documentation warns that lossy artifacts are+detrimental to model performance, especially across repeated passes. Any lossy+encoding stays confined to site presentation and never reaches tool output.++## Execution record++Appended as work completes, so the plan doubles as the audit trail. Figures here+are observed, not predicted.++### Phase 0 results++| Item | Recorded value |+| --- | --- |+| Decision D1 taken | `~/kiln-media-archive/` |+| Video archive | 31 files, 72,246,516 bytes; all 31 verified byte-identical by sha256 against source |+| Social-post masters preserved | `kiln-launch.mp4` 43 MB, `gallery-take.mp4` 11 MB, `kiln-launch-poster.png` 1.3 MB |+| README video URL (I4) | HTTP 200, 64,712,834 bytes, `video/mp4`, served from `github-production-user-asset` S3 |+| Mirror backup | `~/kiln-backup-2026-09-10.git`, 227 MB, `fsck` clean |+| Mirror verification | 176 commits, HEAD `5b903fbf5119`, 3206 objects; all three match source |+| Baseline HEAD | `5b903fbf5119` on `main` |+| Forks | 0 |+| Open pull requests | 0 |+| Open issues | 0 |+| Stars | 21 |++Two findings worth carrying forward. The published README video is 64.7 MB,+larger than the 43 MB copy that was in `assets/video/`, which confirms the+in-repository file was never the artifact the README served and can be removed+without touching the README. And the force-push blast radius is zero: no forks,+no open pull requests, no open issues. The rewrite in Phase 3 disrupts nobody+except clones already on disk.++### Phase 1 results++`--filter=blob:none` documented in `README.md` and `docs/install.md`, worded so+it stays accurate after Phase 3 shrinks the history. Committed as `82c9805`.++### Phase 2 results++| Item | Recorded value |+| --- | --- |+| Decision D2 taken | bucket `kiln-assets`, domain `assets.kilnstudio.tools`, zone `f5e56d7197cf2a23bcdd6e0cbc93d79b` |+| Decision D3 taken | `assets/gallery/` stays in the repository, so the README needs no network |+| Decision D4 taken | all three writers emit to a gitignored `.posters/`; `scripts/upload-posters.mjs` publishes it |+| Objects uploaded | 88 (84 PNG, 4 GIF), byte-for-byte, no re-encode |+| Upload integrity (2.5) | 88/88 sha256 identical after download from R2 |+| Receipt gate (2.6, I1) | 83/83 `posterReceipt.imageHash` values equal the stored object's sha256; 0 mismatches |+| CDN serving (2.7) | 88/88 return HTTP 200 with correct `content-type` over `https://assets.kilnstudio.tools`, each byte-identical |+| Doc rewrite (2.8) | 128 occurrences across 66 distinct posters; all 66 URLs return 200; the 68 `.kiln.js` program links left relative |+| Caption parity | 62 captions scraped before and after the rewrite |+| Lint (I6) | exit 0; 14 warnings, 11 infos, unchanged from baseline |+| Typecheck | engine and site both exit 0 |+| `tidal-observatory.png` | the one poster with no receipt: 84 PNGs, 83 receipts |++Three things were missed by the original plan and are recorded as tasks 2.15 to+2.18. `site/scripts/build-assets.mjs` reads posters through a `RENDERS`+constant, so searching for the literal string `examples/renders` did not find+it; it also scrapes poster `href`s out of `docs/examples.md` to build captions,+which task 2.8 broke until the pattern was loosened. `src/__tests__/examples.test.ts`+matched a repository-relative `src=` attribute for the GIF cells and failed for+the same reason. Both now key on the file name instead of the path, so either+form matches. The lesson worth keeping: `docs/examples.md` is machine-read in two+places, not just rendered.++#### Blocked, with cause++**Task 2.12 and 2.14.** `site/scripts/build-assets.mjs` exits 1 on this machine,+and this is pre-existing rather than caused by the migration. Verified by running+it on an untouched clone of the baseline commit, where it fails identically.++This entry previously described the failure as `artifactMatch: false` on+`abyssal-surveyor` and attributed it to baked texture encoding. Both details were+wrong and are corrected here. That JSON was a diagnostic written by hand while+debugging, not output any script in this repository emits, and it should not have+been recorded as though the tool reported it. The real error is+`Recorded poster is stale; regenerate it from the current gallery GLB.`, thrown by+`verifyRecordedPoster` in `site/scripts/provenance.mjs` from `build-assets.mjs:68`.+The scope was also far larger than one asset. Measured directly by re-rendering+every example on Linux and comparing all three recorded hashes:++| Receipts checked | Mismatched | Which field |+| --- | --- | --- |+| 83 | 75 | `artifactHash` only |++No `sourceHash` and no `imageHash` mismatched, on any asset. The poster bytes are+therefore intact and the R2 migration is clean; what diverges is the serialized+GLB. The meshes themselves are not diverging either: `src/__tests__/examples.test.ts`+asserts the README triangle counts by executing every program, and it passes 94 of+94 on Linux. Identical geometry with different serialized bytes on 75 of 83 assets+points at float formatting or precision in GLB serialization, not at different+models.++`pages.yml` pins `runs-on: windows-2022` with a comment recording that poster+receipts bind GLB bytes captured on Windows, which is how this has stayed+invisible. It is a genuine cross-platform gap in the maintainer pipeline and is+tracked as Phase 6. It does not affect the shipped tools, which do not verify+against these receipts, and it does not block Phase 3.++What was proven instead: the new fetch-and-cache path works against the live+bucket, and the poster it retrieved was byte-identical to the attested file, so+the migration's own behaviour is verified even though the surrounding build is+not. Confirming 2.12 and 2.14 needs either CI or the GPU machine.++**Pre-existing test failure.** The baseline clone also fails+`CLI saves, exports, imports, and restores a revision across independent stores`.+Unrelated to this work. Run counts also varied between 2 failures and 1 across+identical invocations, so at least one test in the suite is flaky. After the+task 2.18 fix, the working tree's only failure is that same pre-existing one,+and `src/__tests__/examples.test.ts` passes 94/94 on its own.++#### One trap worth naming++`wrangler r2 object put` defaults to a **local** simulator and needs `--remote`+to reach the bucket. It reports `Upload complete` either way. The first upload in+this work went nowhere real, and the simulator wrote 1.8 MB of sqlite state and a+copy of the image into `.wrangler/`, which was then briefly committed before+being caught and removed. `.wrangler/` is now in `.gitignore`. Anyone repeating+this work should confirm `Resource location: remote` in the output.++### Remaining work++Phase 3 is untouched and is the only irreversible phase. It gained task 3.4a+during Phase 2: `src/__tests__/examples.test.ts` asserts through `readdir` that+every hero and demo PNG exists in `examples/renders`, and those assertions fail+the moment the images leave the tree. Phase 4 is deferred by the owner for a+joint walk-through. Task 5.1 stays open deliberately: the pristine baseline clone+in the scratchpad is the comparison set for Phase 3 verification and should+outlive the rewrite.++### Phase 3 progress++Tasks 3.1, 3.3, 3.4 and 3.4a are complete. The rewrite itself, 3.5 onward, has+not started.++**Task 3.4a, and the standard it sets.** Three assertions in+`src/__tests__/examples.test.ts` proved that every hero, archive and demo had a+render, and one proved every README GIF existed, all four by reading+`examples/renders/`. None of them can survive the images leaving the tree. Two+replacements were considered and rejected. A generated manifest listing what had+been uploaded would assert only that an upload once happened, and would pass+while the bucket returned 404 -- a test that cannot fail when the thing it guards+is broken, which is worse than no test because it stops anyone looking. Folding+the check into `site/scripts/verify-assets.mjs` fails for a different reason:+that script reads `site/public/assets/index.json`, so it cannot run until the+entire gallery build has succeeded, and it iterates gallery rows rather than the+poster set, so it cannot see the animations or the archive entries at all.++What shipped instead splits the check by what each layer can observe.++| Layer | Asserts | Why it can be true there |+| --- | --- | --- |+| `src/__tests__/examples.test.ts` | heroes, archives and demos each have a poster receipt; the `GIFS` list, the README cells and the example programs agree | The 83 receipts stayed in the tree, so this remains a real local check and still catches a hero added without a render |+| `scripts/verify-posters.mjs` | every published image is served and, where attested, byte-identical to its receipt | Over HTTP against the bucket, the only place the published bytes exist |++The GIF assertion lost its third leg outright: animations are assembled from+frames and were never attested individually, so nothing local can speak to+whether one exists. That leg moved to the new script rather than being replaced+with a comparison of the declared list against itself.++The new script is deliberately standalone and deliberately runs *before*+`build-assets.mjs` in `pages.yml`. Whether the bucket still serves the attested+bytes has nothing to do with whether the GLBs rebuild, and running it first means+a broken bucket reports as a broken bucket instead of hiding behind a build+failure. It is wired into `pages.yml` and exposed as `bun run verify:posters`;+without that wiring this restructure would have been a downgrade, since the check+would have left `bun run test` and then never run again.++| Check | Result |+| --- | --- |+| `bun run verify:posters` | 88 images served; 83 byte-identical to their receipts; 5 present but unattested (`tidal-observatory.png` and the four GIFs) |+| `src/__tests__/examples.test.ts` | 94 pass, 0 fail, 647 assertions |+| `bun run lint` | exit 0; 14 warnings, 11 infos, unchanged from baseline |++**The blocker was re-measured, not assumed.** Chasing the Windows pin in+`pages.yml` led to re-running the build rather than trusting the earlier note, and+the earlier note was wrong in three ways: wrong error string, wrong failing+script, and wrong scope by a factor of seventy-five. The corrected finding is+recorded under Phase 2 above and is now tracked as Phase 6. CI remains the+correct place to settle 2.12 and 2.14, but only because CI runs Windows, which is+the workaround rather than the fix.++## Phase 6 -- GLB serialization is not byte-reproducible across platforms++Opened on 2026-09-10 from the measurement above, at the owner's clarification+that the project should work from Windows, macOS and Linux alike. It is+pre-existing, orthogonal to Phases 0 to 5, and deliberately not bundled into the+history rewrite.++Today a contributor on macOS or Linux cannot run `bun scripts/build-assets.mjs`+or `site/scripts/verify-assets.mjs` to completion, because 75 of 83 poster+receipts bind GLB bytes that only a Windows host reproduces. The shipped MCP+tools and CLI are unaffected: nothing an end user runs verifies against these+receipts, and `ci.yml` already exercises the engine on Ubuntu and both macOS+architectures.++| ID | Task | State |+| --- | --- | --- |+| 6.1 | Establish whether the divergence is float formatting, buffer padding, or accessor min/max precision, by diffing one small asset's GLB JSON chunk between a Linux and a Windows render | Pending |+| 6.2 | Decide the fix: make serialization deterministic across platforms, or make `artifactHash` cover geometry rather than serialized bytes | Pending |+| 6.3 | Re-record the affected receipts once serialization is settled, deliberately and in one pass | Pending |+| 6.4 | Unpin `pages.yml` from `windows-2022` and confirm the gallery builds on Ubuntu | Pending |++### Phase 3 rehearsal++The rewrite was executed in full on a throwaway clone before touching anything+that can reach GitHub, because `git filter-repo` rewrites a repository in place+and strips its remote. The clone used `--no-hardlinks` deliberately: a local+clone hardlinks objects by default, and rewriting hardlinked objects can reach+back into the source repository. The remote was then removed outright.++Tasks 3.5 through 3.10 are validated by this rehearsal. 3.11 onward, which begins+with the force-push, are not.++| Measurement | Baseline | After rewrite |+| --- | --- | --- |+| Packed history | 226.06 MiB | 16.62 MiB |+| `.git` on disk | 227 MB | 17 MB |+| Objects in pack | 3206 | 3020 |+| Commits | 180 | 180 |+| Clone, wall clock (local transport) | 79 s from GitHub | 203 ms |+| Clone, on disk | 440 MB | 35 MB (23 MB `.git` + 12 MB checkout) |++One pass removed `assets/video/`, `examples/renders/*.png`,+`examples/renders/*.gif` and `dist/`. All four are absent from every commit+afterwards, verified by searching the whole rewritten history for additions+rather than by inspecting HEAD. Every commit survived.++| Verification | Result |+| --- | --- |+| Files in tree | 1262 before, 1143 after; exactly 119 removed (31 under `assets/video/`, 88 under `examples/renders/`) |+| Unexpected additions | none |+| `dist/` re-added (3.6) | all 10 files byte-identical to the pre-rewrite blobs, by sha256 |+| `bun run build:runtime` (3.7, I2) | exit 0, working tree clean, `dist/` still byte-identical |+| `bun run lint` (3.9, I6) | exit 0; 14 warnings, 11 infos, unchanged from baseline |+| `bun run test` (3.9) | 1804 pass, 1 fail across 1807 tests in 206 files |++The single failure is `CLI saves, exports, imports, and restores a revision+across independent stores`, and it is pre-existing: the same test fails+identically in the untouched working repository, with+`SyntaxError: JSON Parse error: Unexpected EOF` at `src/asset-cli.test.ts:34`.+It passes on CI's Ubuntu runner, so it is a local environment fault rather than a+repository defect, and it is unrelated to this work.++### CI results on PR #63++Both workflows succeeded on the pull request, which resolves tasks 2.12 and+2.14. The Gallery workflow is the meaningful one: it ran `build-assets.mjs`,+`verify-assets.mjs` and the new `verify-posters.mjs` on `windows-2022`, so the+R2 poster path is confirmed end to end in the environment the receipts were+recorded in.++| Workflow | Conclusion |+| --- | --- |+| CI | success |+| Gallery | success |diff --git a/package.json b/package.jsonindex e687cff8..efa0701e 100644--- a/package.json+++ b/package.json@@ -1,34 +1,34 @@-{- "name": "@kiln/engine",- "private": true,- "version": "0.6.0",- "description": "Create and refine procedural 3D assets with JavaScript, image feedback, and reusable source revisions.",- "license": "MIT",- "author": "Matthew Kissinger",- "type": "module",- "packageManager": "[email protected]",- "engines": {- "bun": "1.3.14",- "node": "22.23.1",- "npm": "12.0.1"- },+{+ "name": "@kiln/engine",+ "private": true,+ "version": "0.6.0",+ "description": "Create and refine procedural 3D assets with JavaScript, image feedback, and reusable source revisions.",+ "license": "MIT",+ "author": "Matthew Kissinger",+ "type": "module",+ "packageManager": "[email protected]",+ "engines": {+ "bun": "1.3.14",+ "node": "22.23.1",+ "npm": "12.0.1"+ },"bin": {"kiln": "./dist/cli.mjs","kiln-init": "./scripts/create-workspace.mjs"- },+ },"exports": {"./assets": "./src/assets.ts","./assets/node": "./src/assets-node.ts",- ".": "./src/cli.ts",- "./agent": "./src/agent/index.ts",- "./tools": "./src/tools/registry.ts",- "./arena": "./src/arena/index.ts",- "./render": "./src/render.ts",- "./evaluator": "./src/evaluator/index.ts",- "./kit": "./src/kit.ts",- "./palette": "./src/palette.ts",- "./views": "./src/views/index.ts",- "./validation": "./src/validation.ts",+ ".": "./src/cli.ts",+ "./agent": "./src/agent/index.ts",+ "./tools": "./src/tools/registry.ts",+ "./arena": "./src/arena/index.ts",+ "./render": "./src/render.ts",+ "./evaluator": "./src/evaluator/index.ts",+ "./kit": "./src/kit.ts",+ "./palette": "./src/palette.ts",+ "./views": "./src/views/index.ts",+ "./validation": "./src/validation.ts","./primitives": "./src/primitives.ts","./geometry": "./src/geometry.ts","./deform": "./src/deform.ts",@@ -38,27 +38,27 @@"./programs/node": "./src/program-store-node.ts","./cache": "./src/build-cache.ts","./cache/node": "./src/build-cache-node.ts",- "./profile": "./src/profile.ts",- "./architecture": "./src/architecture.ts",- "./character": "./src/character.ts",- "./vehicle": "./src/vehicle.ts",- "./material-recipes": "./src/material-recipes.ts",- "./material-resources": "./src/material-resources.ts",- "./texture-resolver": "./src/texture-resolver.ts",- "./material-recipe-runtime": "./src/material-recipe-runtime.ts",- "./material-recipe-prompt": "./src/material-recipe-prompt.ts",- "./material-metrics": "./src/material-metrics.ts",- "./prompt": "./src/prompt.ts",- "./prompt-api": "./src/prompt-api.ts",- "./list-primitives": "./src/list-primitives.ts",- "./metrics": "./src/metrics.ts",- "./inspect": "./src/inspect.ts",- "./contracts": "./src/contracts/index.ts",- "./qa": "./src/qa/index.ts",- "./composer": "./src/composer/index.ts",- "./composer/agent": "./src/composer/agent/index.ts",- "./world-runtime": "./src/composer/terrain-runtime.ts"- },+ "./profile": "./src/profile.ts",+ "./architecture": "./src/architecture.ts",+ "./character": "./src/character.ts",+ "./vehicle": "./src/vehicle.ts",+ "./material-recipes": "./src/material-recipes.ts",+ "./material-resources": "./src/material-resources.ts",+ "./texture-resolver": "./src/texture-resolver.ts",+ "./material-recipe-runtime": "./src/material-recipe-runtime.ts",+ "./material-recipe-prompt": "./src/material-recipe-prompt.ts",+ "./material-metrics": "./src/material-metrics.ts",+ "./prompt": "./src/prompt.ts",+ "./prompt-api": "./src/prompt-api.ts",+ "./list-primitives": "./src/list-primitives.ts",+ "./metrics": "./src/metrics.ts",+ "./inspect": "./src/inspect.ts",+ "./contracts": "./src/contracts/index.ts",+ "./qa": "./src/qa/index.ts",+ "./composer": "./src/composer/index.ts",+ "./composer/agent": "./src/composer/agent/index.ts",+ "./world-runtime": "./src/composer/terrain-runtime.ts"+ },"files": ["dist/viewer/","src/**/*.ts",@@ -77,73 +77,74 @@"docs/","README.md","CONTRIBUTING.md",- "LICENSE",- "CHANGELOG.md"- ],- "scripts": {- "kiln": "bun src/cli.ts",- "check:toolchain": "bun scripts/check-toolchain.mjs",- "typecheck": "tsc --noEmit",- "build": "tsc --noEmit",+ "LICENSE",+ "CHANGELOG.md"+ ],+ "scripts": {+ "kiln": "bun src/cli.ts",+ "check:toolchain": "bun scripts/check-toolchain.mjs",+ "typecheck": "tsc --noEmit",+ "build": "tsc --noEmit","build:mcp": "node scripts/build-runtime.mjs mcp","build:cli": "node scripts/build-runtime.mjs cli","build:worker": "node scripts/build-runtime.mjs worker","build:runtime": "node scripts/build-viewer.mjs && node scripts/build-runtime.mjs all","build:viewer": "node scripts/build-viewer.mjs","docs:tools": "bun scripts/generate-tool-reference.ts",- "test": "KILN_SPIKE_LIVE=0 KILN_RENDER=cpu bun test src scripts",- "test:coverage": "KILN_SPIKE_LIVE=0 KILN_RENDER=cpu bun test src scripts --coverage && bun scripts/check-coverage.mjs",+ "test": "KILN_SPIKE_LIVE=0 KILN_RENDER=cpu bun test src scripts",+ "test:coverage": "KILN_SPIKE_LIVE=0 KILN_RENDER=cpu bun test src scripts --coverage && bun scripts/check-coverage.mjs","test:live": "KILN_SPIKE_LIVE=1 bun test","test:package": "node scripts/test-plugin-package.mjs && node scripts/smoke-package.mjs",- "lint": "biome check .",- "site:assets": "cd site && bun scripts/build-assets.mjs",- "site:dev": "bun run --cwd site dev",- "site:build": "bun run --cwd site build",- "smoke:harness": "node scripts/harness-smoke.mjs"- },- "dependencies": {- "@gltf-transform/core": "^4.4.1",- "@gltf-transform/extensions": "^4.4.1",- "@gltf-transform/functions": "^4.4.1",- "@modelcontextprotocol/client": "^2.0.0",- "@modelcontextprotocol/server": "^2.0.0",- "@openrouter/ai-sdk-provider": "^2.10.0",- "@types/three": "^0.185.1",- "acorn": "^8.17.0",- "acorn-walk": "^8.3.5",- "gltf-validator": "2.0.0-dev.3.10",- "manifold-3d": "^3.5.1",- "sharp": "^0.35.3",- "three": "0.185.1",- "three-subdivide": "^1.1.5",- "xatlasjs": "^0.2.0",- "zod": "^4.4.3"- },- "peerDependencies": {- "@ai-sdk/provider": "^3.0.0",- "@strands-agents/sdk": "^1.4.0"- },- "overrides": {- "sharp": "^0.35.3"- },- "peerDependenciesMeta": {- "@ai-sdk/provider": {- "optional": true- },- "@strands-agents/sdk": {- "optional": true- }- },- "devDependencies": {- "@ai-sdk/provider": "^3.0.14",- "@anthropic-ai/sdk": "^0.110.0",- "@aws-sdk/client-bedrock-runtime": "^3.1083.0",- "@biomejs/biome": "^2.5.3",- "@google/genai": "^2.17.1",- "@strands-agents/sdk": "1.13.0",- "@types/bun": "^1.3.14",- "ai": "^6.0.222",- "openai": "^6.46.0",- "typescript": "^7.0.2"- }-}+ "lint": "biome check .",+ "verify:posters": "bun scripts/verify-posters.mjs",+ "site:assets": "cd site && bun scripts/build-assets.mjs",+ "site:dev": "bun run --cwd site dev",+ "site:build": "bun run --cwd site build",+ "smoke:harness": "node scripts/harness-smoke.mjs"+ },+ "dependencies": {+ "@gltf-transform/core": "^4.4.1",+ "@gltf-transform/extensions": "^4.4.1",+ "@gltf-transform/functions": "^4.4.1",+ "@modelcontextprotocol/client": "^2.0.0",+ "@modelcontextprotocol/server": "^2.0.0",+ "@openrouter/ai-sdk-provider": "^2.10.0",+ "@types/three": "^0.185.1",+ "acorn": "^8.17.0",+ "acorn-walk": "^8.3.5",+ "gltf-validator": "2.0.0-dev.3.10",+ "manifold-3d": "^3.5.1",+ "sharp": "^0.35.3",+ "three": "0.185.1",+ "three-subdivide": "^1.1.5",+ "xatlasjs": "^0.2.0",+ "zod": "^4.4.3"+ },+ "peerDependencies": {+ "@ai-sdk/provider": "^3.0.0",+ "@strands-agents/sdk": "^1.4.0"+ },+ "overrides": {+ "sharp": "^0.35.3"+ },+ "peerDependenciesMeta": {+ "@ai-sdk/provider": {+ "optional": true+ },+ "@strands-agents/sdk": {+ "optional": true+ }+ },+ "devDependencies": {+ "@ai-sdk/provider": "^3.0.14",+ "@anthropic-ai/sdk": "^0.110.0",+ "@aws-sdk/client-bedrock-runtime": "^3.1083.0",+ "@biomejs/biome": "^2.5.3",+ "@google/genai": "^2.17.1",+ "@strands-agents/sdk": "1.13.0",+ "@types/bun": "^1.3.14",+ "ai": "^6.0.222",+ "openai": "^6.46.0",+ "typescript": "^7.0.2"+ }+}diff --git a/scripts/anim-gifs.ts b/scripts/anim-gifs.tsindex 0749ef91..d191866d 100644--- a/scripts/anim-gifs.ts+++ b/scripts/anim-gifs.ts@@ -1,5 +1,5 @@/**- * Render one looping GIF per animated example into `examples/renders/`.+ * Render one looping GIF per animated example into `.posters/`, for upload to R2.** A still cannot show that Kiln's animation path works, and the claim that a* model can write `animate()` and then watch its own motion deserves better@@ -41,7 +41,11 @@ import { measureBounds } from '../src/views/raster';const HERE = dirname(fileURLToPath(import.meta.url));const REPO = resolve(HERE, '..');const EXAMPLES = join(REPO, 'examples');-const OUT_DIR = join(EXAMPLES, 'renders');+// Gallery images are published from R2, not carried in git: they were 108 MB of+// PNG that no tool reads, and every clone and plugin install paid for them. This+// writes them to a gitignored directory; `bun scripts/upload-posters.mjs` pushes+// them to the bucket that `site/scripts/verify-assets.mjs` reads.+const OUT_DIR = join(REPO, '.posters');/*** Animated examples, with the clip each one is shown in.diff --git a/scripts/hero-shots.ts b/scripts/hero-shots.tsindex 0f6f56d0..3f8c626b 100644--- a/scripts/hero-shots.ts+++ b/scripts/hero-shots.ts@@ -1,5 +1,5 @@/**- * Render one beauty shot per hero example into `examples/renders/`.+ * Render one beauty shot per hero example into `.posters/`, for upload to R2.** The README used to carry a single stitched contact-sheet collage. That was* the wrong artifact for two reasons: every asset got the same 380 px cell no@@ -32,7 +32,11 @@ import { resolveEvaluatorPortV1 } from '../src/evaluator/protocol';const HERE = dirname(fileURLToPath(import.meta.url));const REPO = resolve(HERE, '..');const EXAMPLES = join(REPO, 'examples');-const OUT_DIR = join(EXAMPLES, 'renders');+// Gallery images are published from R2, not carried in git: they were 108 MB of+// PNG that no tool reads, and every clone and plugin install paid for them. This+// writes them to a gitignored directory; `bun scripts/upload-posters.mjs` pushes+// them to the bucket that `site/scripts/verify-assets.mjs` reads.+const OUT_DIR = join(REPO, '.posters');/*** The hero set, in the order the README presents them.diff --git a/scripts/upload-posters.mjs b/scripts/upload-posters.mjsnew file mode 100644index 00000000..cfe29d7a--- /dev/null+++ b/scripts/upload-posters.mjs@@ -0,0 +1,87 @@+/**+ * Publish rendered gallery images from `.posters/` to the R2 bucket that+ * `site/scripts/verify-assets.mjs` reads.+ *+ * The posters used to live in `examples/renders/`. That cost 117 MB of git+ * history for files no tool reads, and a plugin install paid for the repository+ * twice, so they moved to object storage. What did not change is that a poster's+ * bytes are attested: `examples/<name>.provenance.json` records the sha256 of the+ * exact PNG the renderer emitted. This script therefore uploads byte-for-byte,+ * never re-encoding, and refuses to publish an image whose hash disagrees with a+ * receipt that already exists for it.+ */+import { spawnSync } from 'node:child_process';+import { createHash } from 'node:crypto';+import { mkdtemp, readFile, readdir, rm } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import { dirname, join, resolve } from 'node:path';+import { fileURLToPath } from 'node:url';++const REPO = resolve(dirname(fileURLToPath(import.meta.url)), '..');+const SOURCE = join(REPO, '.posters');+const BUCKET = process.env.KILN_POSTER_BUCKET ?? 'kiln-assets';+const PREFIX = process.env.KILN_POSTER_PREFIX ?? 'renders';+const TYPES = { '.png': 'image/png', '.gif': 'image/gif' };++const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');++const wrangler = (args) => {+ const run = spawnSync('wrangler', args, { encoding: 'utf8', windowsHide: true });+ if (run.status !== 0) throw new Error(`wrangler ${args[0]} ${args[1]} failed:\n${run.stderr || run.stdout}`);+ return run.stdout;+};++/** A receipt exists only for attested posters; GIFs and previews have none. */+async function recordedImageHash(name) {+ try {+ const side = JSON.parse(await readFile(join(REPO, 'examples', `${name}.provenance.json`), 'utf8'));+ return side.provenance?.posterReceipt?.imageHash ?? null;+ } catch {+ return null;+ }+}++let files;+try {+ files = (await readdir(SOURCE)).filter((f) => Object.keys(TYPES).some((e) => f.endsWith(e))).sort();+} catch {+ console.log(`Nothing to publish: ${SOURCE} does not exist. Render first with scripts/hero-shots.ts or scripts/anim-gifs.ts.`);+ process.exit(0);+}+if (files.length === 0) {+ console.log(`Nothing to publish: ${SOURCE} holds no PNG or GIF.`);+ process.exit(0);+}++const staging = await mkdtemp(join(tmpdir(), 'kiln-posters-'));+let published = 0;+try {+ for (const file of files) {+ const name = file.replace(/\.(png|gif)$/, '');+ const extension = file.slice(file.lastIndexOf('.'));+ const bytes = await readFile(join(SOURCE, file));+ const digest = sha(bytes);++ const recorded = extension === '.png' ? await recordedImageHash(name) : null;+ if (recorded && recorded !== digest)+ throw new Error(+ `${file} does not match its recorded poster receipt.\n receipt: ${recorded}\n file: ${digest}\n` ++ 'Publishing it would void the provenance claim. Re-record the receipt deliberately, or restore the attested image.',+ );++ const key = `${BUCKET}/${PREFIX}/${file}`;+ wrangler(['r2', 'object', 'put', key, '--file', join(SOURCE, file), '--content-type', TYPES[extension], '--remote']);++ // Read it back rather than trusting the upload: these bytes are the artifact.+ const roundTrip = join(staging, file);+ wrangler(['r2', 'object', 'get', key, '--remote', '--file', roundTrip]);+ const stored = sha(await readFile(roundTrip));+ if (stored !== digest) throw new Error(`${file} changed in transit.\n local: ${digest}\n stored: ${stored}`);++ published += 1;+ console.log(`${file} ${digest}${recorded ? ' (matches receipt)' : ''}`);+ }+} finally {+ await rm(staging, { recursive: true, force: true });+}+console.log(`Published ${published} image${published === 1 ? '' : 's'} to ${BUCKET}/${PREFIX}, each verified byte-for-byte after upload.`);diff --git a/scripts/verify-posters.mjs b/scripts/verify-posters.mjsnew file mode 100644index 00000000..5f2db104--- /dev/null+++ b/scripts/verify-posters.mjs@@ -0,0 +1,88 @@+/**+ * Audit the gallery images that live in R2 rather than in git history.+ *+ * The counterpart to `scripts/upload-posters.mjs`: that script publishes and+ * refuses to void a receipt, this one checks afterwards that what is published+ * is still there and still the attested bytes. Both exist because the images+ * moved out of `examples/renders/` -- 117 MB of history for files no tool reads+ * -- while their provenance stayed behind. The 83 receipts in that directory are+ * the manifest: one per poster, each recording the sha256 of the exact PNG the+ * renderer emitted.+ *+ * Deliberately standalone rather than folded into `site/scripts/verify-assets.mjs`,+ * which reads `site/public/assets/index.json` and so cannot run until the whole+ * gallery build has succeeded. This check has no such precondition, and it is the+ * only place that can honestly assert an image exists: a local manifest would+ * only record that an upload once happened, and would pass while the bucket+ * returns 404.+ *+ * Existence is checked for every object. Hashes are checked wherever a receipt+ * exists, which is every poster but `tidal-observatory` -- an archive entry kept+ * for the docs that predates the receipts -- and none of the animations, since+ * GIFs are assembled from frames and were never attested individually.+ */+import { createHash } from 'node:crypto';+import { readFile, readdir } from 'node:fs/promises';+import { dirname, join, resolve } from 'node:path';+import { fileURLToPath } from 'node:url';++const REPO = resolve(dirname(fileURLToPath(import.meta.url)), '..');+const RECEIPTS = join(REPO, 'examples', 'renders');+const BASE = process.env.KILN_POSTER_BASE ?? 'https://assets.kilnstudio.tools/renders';++const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');++/** Images published without a receipt, named individually so the gap is visible. */+const UNATTESTED = ['tidal-observatory.png', 'carousel.gif', 'orrery.gif', 'radio-telescope.gif', 'robot-arm.gif'];++const entries = await readdir(RECEIPTS);+const attested = entries.filter((f) => f.endsWith('.json')).sort();+if (attested.length === 0) throw new Error(`No poster receipts found in ${RECEIPTS}`);++const failures = [];+let hashed = 0;+let present = 0;++for (const file of [...attested.map((f) => f.replace(/\.json$/, '.png')), ...UNATTESTED]) {+ const url = `${BASE}/${file}`;+ let response;+ try {+ response = await fetch(url);+ } catch (err) {+ failures.push(`${file}: unreachable (${err instanceof Error ? err.message : String(err)})`);+ continue;+ }+ if (!response.ok) {+ failures.push(`${file}: HTTP ${response.status} from ${url}`);+ continue;+ }+ const bytes = Buffer.from(await response.arrayBuffer());+ present += 1;++ const expected = /\.gif$/.test(file) ? '.gif' : '.png';+ const type = response.headers.get('content-type') ?? '';+ if (!type.startsWith(expected === '.gif' ? 'image/gif' : 'image/png'))+ failures.push(`${file}: served as ${type || 'no content-type'}`);++ if (UNATTESTED.includes(file)) continue;+ const receipt = JSON.parse(await readFile(join(RECEIPTS, file.replace(/\.png$/, '.json')), 'utf8'));+ if (!receipt.imageHash) {+ failures.push(`${file}: receipt records no imageHash`);+ continue;+ }+ const digest = sha(bytes);+ if (digest !== receipt.imageHash) {+ failures.push(`${file}: published bytes differ from the receipt.\n receipt: ${receipt.imageHash}\n served: ${digest}`);+ continue;+ }+ hashed += 1;+}++if (failures.length > 0) {+ console.error(`${failures.length} poster check${failures.length === 1 ? '' : 's'} failed:`);+ for (const failure of failures) console.error(` ${failure}`);+ process.exit(1);+}+console.log(+ `Verified ${present} published images at ${BASE}: ${hashed} byte-identical to their receipts, ${UNATTESTED.length} present but unattested (${UNATTESTED.join(', ')}).`,+);diff --git a/site/scripts/build-assets.mjs b/site/scripts/build-assets.mjsindex 349db2e1..ec255a09 100644--- a/site/scripts/build-assets.mjs+++ b/site/scripts/build-assets.mjs@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url';import sharp from 'sharp';import { createHash } from 'node:crypto';+import { posterBytes, posterFile } from './posters.mjs';import { exampleProvenance, recordedExampleCredit, verifyRecordedPoster } from './provenance.mjs';import { buildEditDemo } from './build-edit-demo.mjs';import { buildGeometryDemo } from './build-geometry-demo.mjs';@@ -19,7 +20,6 @@ import { resolveEvaluatorPortV1 } from '../../src/evaluator/protocol';const SITE = resolve(dirname(fileURLToPath(import.meta.url)), '..');const REPO = resolve(SITE, '..');const EXAMPLES = join(REPO, 'examples');-const RENDERS = join(EXAMPLES, 'renders');const OUT = join(SITE, 'public', 'assets');const THUMBS = join(SITE, 'public', 'thumbs');const buildInputs = await runtimeBuildIdentity(REPO);@@ -28,15 +28,14 @@ const buildInputs = await runtimeBuildIdentity(REPO);/** The one-line caption the README gives each asset, so both read alike. */function captions(readme) {const out = new Map();- const cell = /<a href="examples\/renders\/([a-z0-9-]+)\.png">.*?<br><sub>([^<]*)<\/sub>/gs;+ // Posters are linked absolutely from R2 now, so key on the file name rather+ // than a repository-relative path.+ const cell = /<a href="[^"]*renders\/([a-z0-9-]+)\.png">.*?<br><sub>([^<]*)<\/sub>/gs;for (const m of readme.matchAll(cell)) if (!out.has(m[1])) out.set(m[1], m[2].trim());return out;}-const readme = (await readFile(join(REPO, 'docs/examples.md'), 'utf8')).replaceAll(- '../examples/',- 'examples/',-);+const readme = await readFile(join(REPO, 'docs/examples.md'), 'utf8');const caption = captions(readme);const names = (await readdir(EXAMPLES))@@ -70,7 +69,7 @@ for (const name of names) {record.provenance.posterReceipt,src,r.glb,- await readFile(join(RENDERS, `${name}.png`)),+ await posterBytes(name),);if (record?.provenance?.posterReceipt)await writeFile(@@ -122,13 +121,13 @@ for (const name of names) {// The index shows the checked-in hero render and the stage shows the live// GLB, so the grid stays cheap: fifty 1000px PNGs is 3.6 MB of first paint,// and the same fifty at 560px of webp is a fifth of that.- await sharp(join(RENDERS, `${name}.png`))+ await sharp(await posterFile(name)).resize(560, 560, { fit: 'inside' }).webp({ quality: 82 }).toFile(join(THUMBS, `${name}.webp`));if (['orbital-station', 'abyssal-surveyor'].includes(name)) {- let posterPath = join(RENDERS, `${name}.png`);+ let posterPath = await posterFile(name);try {const record = JSON.parse(await readFile(join(SITE, `examples/${name}.poster.json`), 'utf8'));const image = await readFile(join(SITE, `examples/${name}.poster.png`));diff --git a/site/scripts/build-example-poster.mjs b/site/scripts/build-example-poster.mjsindex e5899b9f..6ce43437 100644--- a/site/scripts/build-example-poster.mjs+++ b/site/scripts/build-example-poster.mjs@@ -76,7 +76,8 @@ if (process.argv.includes('--preview') || process.argv.includes('--background-prconsole.log(JSON.stringify({ name, lightingPresetId, preview: true }));process.exit(0);}-await writeFile(`examples/renders/${name}.png`, png);+await mkdir('.posters', { recursive: true });+await writeFile(`.posters/${name}.png`, png);await writeFile(`examples/renders/${name}.json`, JSON.stringify(receipt, null, 2) + '\n');await writeFile(`site/public/assets/${name}.poster.json`, JSON.stringify(receipt, null, 2) + '\n');await sharp(png)diff --git a/site/scripts/posters.mjs b/site/scripts/posters.mjsnew file mode 100644index 00000000..69814fe6--- /dev/null+++ b/site/scripts/posters.mjs@@ -0,0 +1,47 @@+/**+ * Where gallery poster images come from.+ *+ * They used to sit in `examples/renders/`: 108 MB of PNG that no tool in the+ * engine reads, carried in git history forever and downloaded twice by every+ * plugin install. They now live in R2 and are fetched on demand.+ *+ * What did not change is that these bytes are attested. `examples/<name>.provenance.json`+ * records the sha256 of the exact image the renderer emitted, and the gallery+ * build still checks it. So nothing here may transform an image: it fetches,+ * caches and hands back the original bytes.+ *+ * Set `KILN_POSTER_BASE` to a `file://` URL, or pre-populate `KILN_POSTER_CACHE`,+ * to build offline.+ */+import { mkdir, readFile, writeFile } from 'node:fs/promises';+import { dirname, join, resolve } from 'node:path';+import { fileURLToPath } from 'node:url';++const SITE = resolve(dirname(fileURLToPath(import.meta.url)), '..');+const base = process.env.KILN_POSTER_BASE ?? 'https://assets.kilnstudio.tools/renders';+const cache = process.env.KILN_POSTER_CACHE ?? join(SITE, '..', '.poster-cache');++/**+ * Absolute path to a locally cached copy of a poster, fetching it once if needed.+ * Returns a path rather than bytes because `sharp` reads files.+ */+export async function posterFile(name) {+ const file = join(cache, `${name}.png`);+ try {+ await readFile(file);+ return file;+ } catch {+ // Not cached yet; fall through to the network.+ }+ const url = `${base}/${name}.png`;+ const response = await fetch(url);+ if (!response.ok) throw new Error(`Poster fetch failed (${response.status}): ${url}`);+ await mkdir(cache, { recursive: true });+ await writeFile(file, Buffer.from(await response.arrayBuffer()));+ return file;+}++/** The exact poster bytes, for hash comparison against a recorded receipt. */+export async function posterBytes(name) {+ return readFile(await posterFile(name));+}diff --git a/site/scripts/verify-assets.mjs b/site/scripts/verify-assets.mjsindex ccedaf94..ea5624c4 100644--- a/site/scripts/verify-assets.mjs+++ b/site/scripts/verify-assets.mjs@@ -2,10 +2,12 @@ import { createHash } from 'node:crypto';import { readFile } from 'node:fs/promises';import { resolve, dirname, join } from 'node:path';import { fileURLToPath } from 'node:url';+import { posterBytes } from './posters.mjs';import { verifyRecordedPoster } from './provenance.mjs';const root = resolve(dirname(fileURLToPath(import.meta.url)), '../public');const hash = (value) => createHash('sha256').update(value).digest('hex');+const rows = JSON.parse(await readFile(join(root, 'assets/index.json'), 'utf8'));for (const row of rows) {for (const [file, digest] of [@@ -37,7 +39,7 @@ for (const row of rows) {}}if (row.provenance?.posterReceipt) {- verifyRecordedPoster(row.provenance.posterReceipt, source, glb, await readFile(resolve(root, '../../examples/renders', `${row.name}.png`)));+ verifyRecordedPoster(row.provenance.posterReceipt, source, glb, await posterBytes(row.name));const publicReceipt = JSON.parse(await readFile(join(root, 'assets', `${row.name}.poster.json`), 'utf8'));if (publicReceipt.artifactHash !== row.artifactHash || publicReceipt.sourceHash !== row.sourceHash) throw new Error(`Public poster record mismatch: ${row.name}`);}diff --git a/src/__tests__/examples.test.ts b/src/__tests__/examples.test.tsindex c552c858..bcb8720b 100644--- a/src/__tests__/examples.test.ts+++ b/src/__tests__/examples.test.ts@@ -202,7 +202,7 @@ describe('hero gallery', () => {expect(Number(count![1])).toBe(publicNames.length);});- it('has a render for every public hero and only the explicitly retained archive', async () => {+ it('has a poster receipt for every public hero and only the explicitly retained archive', async () => {const publicHeroes = await heroes;const archives = ['tidal-observatory',@@ -211,19 +211,28 @@ describe('hero gallery', () => {'victorian-greenhouse',];for (const archive of archives) expect(publicHeroes).not.toContain(archive);- const expected = [...publicHeroes, ...archives].map((h) => `${h}.png`).sort();+ // The images are served from R2 and no longer sit in the tree, so this keys+ // on the poster receipts that stayed behind: one per attested render, and the+ // only leg of this check a local test can honestly make. `tidal-observatory`+ // is an archive entry predating the receipts and is the single exception.+ // That the published bytes exist and still match is checked by+ // `scripts/verify-posters.mjs`, the only layer that can see them.+ const expected = [...publicHeroes, ...archives]+ .filter((h) => h !== 'tidal-observatory')+ .map((h) => `${h}.json`)+ .sort();const actual = (await readdir(RENDERS))- .filter((f) => f.endsWith('.png') && !f.startsWith('demo-'))+ .filter((f) => f.endsWith('.json') && !f.startsWith('demo-')).sort();expect(actual).toEqual(expected);});- it('has a render for every curated demo addition', async () => {+ it('has a poster receipt for every curated demo addition', async () => {const demos = names.filter((n) => n.startsWith('demo-'));expect(demos.length).toBe(18);- const expected = demos.map((d) => `${d}.png`).sort();+ const expected = demos.map((d) => `${d}.json`).sort();const actual = (await readdir(RENDERS))- .filter((f) => f.startsWith('demo-') && f.endsWith('.png'))+ .filter((f) => f.startsWith('demo-') && f.endsWith('.json')).sort();expect(actual).toEqual(expected);});@@ -255,14 +264,15 @@ describe('hero gallery', () => {if (!block) throw new Error('could not find the GIFS list in scripts/anim-gifs.ts');const declared = [...block[1]!.matchAll(/name: '([^']+)'/g)].map((m) => m[1]!).sort();- const onDisk = (await readdir(RENDERS))- .filter((f) => f.endsWith('.gif'))- .map((f) => f.replace(/\.gif$/, ''))- .sort();- expect(onDisk).toEqual(declared);-+ // No third leg here. GIFs are assembled from frames and were never attested+ // individually, so once they moved to R2 nothing local can say whether one+ // exists; `scripts/verify-posters.mjs` checks that over HTTP instead. What is+ // still worth guarding locally is that the script, the README and the+ // programs agree, which is where the typos actually happen.const src = await readme;- const shown = [...src.matchAll(/src="examples\/renders\/([a-z0-9-]+)\.gif"/g)]+ // Posters and GIFs are linked absolutely from R2 now, so key on the file+ // name rather than a repository-relative path.+ const shown = [...src.matchAll(/src="[^"]*renders\/([a-z0-9-]+)\.gif"/g)].map((m) => m[1]!).sort();expect(shown).toEqual(declared);