Skip to content

armgit / kiln

Public Imported from GitHub
0

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.

chore: shrink the clone and serve gallery images from R2 (#63)

Matthew Kissingerfdcd76d9760f
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index c46b3460..ab5b9dbb 100644
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/pages.yml
@@ -53,6 +53,14 @@ jobs:
- name: Install the engine
run: 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 site
run: bun install --frozen-lockfile
working-directory: site
diff --git a/.gitignore b/.gitignore
index 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.md
index 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/kiln
cd kiln
bun install --frozen-lockfile
bun 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.md
index 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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&#39;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 &middot; 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 &middot; 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 &middot; 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&#39;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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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 &middot; 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.md
index 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/kiln
cd kiln
bun install --frozen-lockfile
bun run build:runtime
node 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 are
available before writing the workspace. It does not install an agent or sign in on
your 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.md
new file mode 100644
index 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.json
index 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.ts
index 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.ts
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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-pr
console.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.mjs
new file mode 100644
index 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.mjs
index 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.ts
index 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);