Skip to main content

Changelog

Popfold is in alpha: nothing is stable and backwards compatibility is not kept before 1.0.0.

Unreleased​

0.25.0 (alpha), 2026-11-20​

  • A Studio link in the debug panel: Studio ↗ opens the site's studio in a new tab on the same home, story stop and light. It links to studio.html beside the page, shows only when that page exists, and a site points it elsewhere with startScene({ debugStudio }) or leaves it out with debugStudio: false.

0.24.1 (alpha), 2026-11-20​

  • A page open during a deploy recovers its 3D. A deploy removes the previous build's files, so a page left open (or cached) across one asked for a file that was gone and never started its 3D. Each story page now reloads itself once when one of the site's own files fails to load (another site's file, such as a blocked analytics script, does not count), and not again for 30 seconds, so a page whose files stay missing keeps the page without 3D instead of looping.

0.24.0 (alpha), 2026-11-20​

  • A tower kept in a home file can keep code per floor: homeFromFile(json, { tower: { build: { <floor id>: (ctx) => … } } }) runs after the floor's listed pieces, for pipes and a moved port. A build for a floor the file does not have is a mistake, named.

0.23.1 (alpha), 2026-11-20​

  • The studio says when a lamp's glow is not the story's. In evening light the engine keeps the lamp at full glow, so the Lamp glow slider is disabled and labelled there, and Use for leaves glow out of the beat.

0.23.0 (alpha), 2026-11-20​

  • The page without 3D is built from a parsed page. popfoldFallback reads each story page with parse5 to find its sections, headings, cards and head, then adds its stills, stories and head tags at those places; the rest of the page is left exactly as written. Nested sections, single-quoted or reordered attributes and a page without a written <head> no longer trip it. The built pages and llms.txt of both templates and two sites came out the same as before. (New dependency: parse5.) readPage(html) is exported for tools.
  • popfold check checks credits: a model in public/models/ that CREDITS.md does not name (by path, file name or a folder below public/models/) is a warning, and so is a site with models and no CREDITS.md.
  • A linter: pnpm lint (Biome, lint rules only; CI runs it). Browser tests for the popfold command: pnpm test:browser runs check, describe, shot and mcp on the compact template.

0.22.0 (alpha), 2026-11-20​

  • Shells as plug-ins. A Shell (shell.ts) builds a home and moves its own parts each frame (house.update(cur, frame)); the engine no longer knows about lids, drawers, walls or floors, and the diorama and tower no longer carry a stand-in lid and drawers. The studio takes its sliders, camera presets and fold styles from the shell, and the rooms a piece can be added to. registerShell() adds a site's own shell, which a recipe claims or names (shell: 'name'). The compact, diorama and tower are compactShell, dioramaShell and towerShell. A home's lamp is now house.lamp (optional); the Compact type extends House.

0.21.0 (alpha), 2026-11-20​

  • One command list for every edit to a home file: place, add, remove, story, camera, beat, look, places. The studio sends them; GET /__popfold/commands lists them with their arguments, and POST /__popfold/home/<id> takes { commands }, { undo: true } or { redo: true }. The dev server keeps each home file's saves, so Ctrl+Z in the studio steps back through saves once nothing unsaved is left.
  • popfold mcp: an MCP server (stdio) whose tools are that command list, plus read_home, undo, redo, check, describe and shot (a picture). An agent's edit reloads open pages; the studio's own do not.

0.20.0 (alpha), 2026-11-20​

  • The studio edits more of a home, without reloading. A Look group sets a compact's colours, surfaces (plain or patterned) and lid title, and a tower's floor colours and signs. A listed piece's Kind can be swapped. Every beat gets Side on wide screens and Float while closed sliders. Adding, removing, a story, a kind or a look change now rebuilds the home in place (scene.rebuildHome(recipe), and recipe.remake(json) from homeFromFile()), keeping the view and selection; the save endpoint hands the file back and stops Vite reloading the studio for its own write. GET /__popfold/home/<id> reads the file.

0.19.0 (alpha), 2026-11-20​

  • A diorama in a home file. A home file can describe a diorama ("diorama": its room model, scale, zones and lamp); the art and cover stay in code, passed to homeFromFile(json, { diorama: { art, cover } }). Stories of the model's parts are kept by key under "stories", and the studio's story editor writes them there.
  • No layout file for a home made from its file. Where the studio moves, turns, resizes or hides a piece the file does not list is saved in the file, under "places". public/layouts/ remains only for homes made in code.
  • The story card's close button is centred in every font. Its cross is drawn instead of typed (a site's own fix for this can go).

0.18.0 (alpha), 2026-11-20​

  • The warm-up builds only what is shown. three.js compiles every mesh under the root, hidden or not, so pieces that never appear cost shader programs nobody used. The warm-up, a late model and a home being switched to now compile only visible meshes: 48 programs down to 29 on a larger site, 22 to 18 on the compact template, 19 to 19 on the tower, and in each case none built later during the first pass.

0.17.0 (alpha), 2026-11-20​

  • startScene({ onScene }). Called with the scene before the warm-up starts, so a site's own lights and objects are in place when the warm-up builds its materials. With warmUp: 'wait' a light added after startScene() resolved used to undo the warm-up (a 362 ms frame on the compact template); added in onScene it costs nothing. The background warm-up also waits a tick, so code right after await startScene() runs before it begins.

0.16.0 (alpha), 2026-11-20​

  • The warm-up now covers the shadow pass. Building materials in the background missed the shaders that draw shadows, which a browser only builds on a real draw; a site with many shadow casters still stalled once or twice. Each beat is now also drawn once, unseen (the true view is drawn over it before the browser shows anything). On a site with two homes and 34 pieces: no warm-up, slowest first-pass frame 793 ms; this warm-up, 3 ms, with the page appearing at the same time.

  • Forge: Hyper3D Rodin through its MCP server. tools/forge/README.md says how to add and sign in to it, its tools and what they cost. It bills the signed-in workspace, so it works on a Creator plan, where rodin.py's REST API needs Business.

0.15.0 (alpha), 2026-11-20​

  • A Debug button beside Simple view. viewToggle() adds a small button that shows and hides the debug panel. viewToggle({ debug: false }) leaves it out; a site that switched the panel off has no button either. toggleDebug() does the same from a site's own control.

  • More warm-up. A model that arrives late is warmed as it lands, and a home is warmed before setHome() swaps it in (in a test with two homes, the slowest frame after a switch was 37 ms and the new home's first pass 5 ms). warmUp: 'wait' holds startScene() until the warm-up is over, for a site with a loader. The debug panel has a warm-up row.

0.14.0 (alpha), 2026-11-20​

  • A smooth first scroll. The story used to stall the first time each room opened, while the browser built the materials it was about to draw. Two fixes:

    • the compact's lamp light is no longer inside the lamp, which is hidden until its room opens. A light appearing changes the number of lights, and every material is then built again;
    • warm-up (warmUp, on by default on a site): once the home is on show, the engine has the browser build each beat's materials in the background, without drawing them. scene.warmed settles when it is done. On the compact template the slowest frame of a first pass went from 1,222 ms to 14 ms, and on the tower from 252 ms to 27 ms, with the page appearing no later than before.
  • A budget for models. popfoldFallback({ modelBudget: { each, total } }), in kilobytes: a build over it stops and lists the files, and popfold check reports the same.

  • startScene({ onHome }) is called with a home's id when it goes on show: at the start, and after each switch.

  • A piece's opts may hold lists of plain values (a shelf's items), not only single ones.

0.13.0 (alpha), 2026-11-20​

  • Forge: rodin.py sends pictures or a prompt to Hyper3D Rodin (paid, hosted) and downloads the textured model. Its API needs a Business or Enterprise plan. Settings: rodin.key_file and rodin.tier in forge.json.

  • popfoldFallback({ homeFile: 'src/home.json' }): the page without 3D reads the home file from disk when it needs it, and names the stills after the file's id. A site's vite.config.ts no longer imports the file, so the dev server keeps running when the studio saves; before, every save restarted it.

  • Docs: what to know about a model's ready (it runs once per build; clone the clip before changing it).

0.12.0 (alpha), 2026-11-20​

  • models: what a site says about a model file. A listed piece whose kind is a model can now glow (glow), keep its animation still for the site to drive (loop: false), and be finished in code once it is built (ready(piece, { clip, spec, ctx }), which may return the lamp's { group, bulb }). Such a model is still a model, so it still loads in stages; before, each of these needed a code kind, which loaded up front.

  • popfold describe covers every home a studio has, not only the homes a page shows (--home <id> for one), and popfold check checks their stories and models too.

  • Fixed: popfold describe counted a piece's story dot in its size, so a size could differ between two runs with nothing moved.

  • Undo and redo in the studio: Ctrl+Z and Ctrl+Shift+Z (and two buttons) step back and forward through unsaved changes to pieces: moves, turns, sizes, hiding.

  • Staged loading for towers too. lazyModels now covers a tower whose pieces are all listed: its first floors' models come first. In the same test as for the compact, 1.3 s against 5.3 s.

  • A piece whose model arrives after its room has opened springs in, where it used to appear at once.

0.11.0 (alpha), 2026-11-20​

  • Models can load in stages. startScene({ lazyModels: true }) shows the home as soon as the models of its first rooms are in; each later model brings its pieces in when it arrives. It applies to a compact whose pieces are all listed in its home file. With two side-room models held back four seconds, the home was on screen in 1.3 s, where it took 5.4 s waiting for all of them.

  • A compact's look is data. home.json can hold look (the case's colours, and each floor and wall as a colour or a pattern: checker, stripes, dots, waves, terrazzo), emblem and swatch. readHome() checks them.

  • homeFromFile(json, { kinds }) makes a home and its story from its file in one call. Both templates use it: their home.ts now holds only how each kind of piece is built. A look written in code still works.

0.10.0 (alpha), 2026-11-20​

  • Fixed: the first still of a tower differed slightly from one capture to the next, so popfold stills --check failed about one time in three on an unchanged site. The capture now starts from the first beat at rest. A tower's first still changes once when it is next captured.

  • The studio sets what a beat does. With Manual on in the Fold group, Use for "" writes the sliders (how far each room or floor is open, the glow, the badges) into that beat in home.json.

  • The studio writes stories. Select a listed piece, open Story, and write its title, text and tags; it is saved into the piece's entry in home.json, which is also what the page without 3D shows.

  • The studio adds and removes pieces. With a home file, Add a piece puts a piece of any of the home's kinds into a room, and Remove… takes a listed piece off the list; both are written into home.json.

  • Hiding a listed piece is saved in the home file ("hidden": true), not in the layout file. A layout file now holds only pieces placed in code.

0.9.0 (alpha), 2026-11-20​

  • A debug panel on every page. ?debug in the address, or Alt+Shift+D, opens a panel with what build this is (the site's commit, when it was built, the versions of the site, Popfold and three.js) and how the page is running (the home and beat, models fetched, frames drawn, draw calls, triangles, the graphics card). It works on the page without 3D and on a deployed site, and its code is fetched only when it is opened. On by default: startScene({ debug: false }) and markFallback({ debug: false }) take it away, and debugRows adds rows of the site's own.

  • The story is in the home file. home.json can hold beats: one per page section, each with its camera and what the home does there. beatsOf(home) turns them into what startScene() and mountStudio() take, and readHome() checks them. Both templates keep their story there; src/beats.ts is gone from them. Beats written in code with beat() still work.

  • The studio sets a beat's camera. In Free orbit, Use for "" writes the view into that beat in the home file and returns to the story camera.

  • The studio saves into the home file. With layoutSaver({ home: 'src/home.json' }), Save layout writes a moved, turned or resized listed piece back into home.json, changing only that piece's line. Pieces placed in code, and which pieces are hidden, still go to public/layouts/. A site that does not name a home file saves as before.

  • A listed piece can have a scale.

0.8.2 (alpha), 2026-11-20​

  • Fixed: popfold optimize merged materials that were the same but for their names. A site that paints art or swaps colours by material name then got one picture on every poster. Materials and meshes with different names now stay apart, and the command refuses a model if any part would end up on a different material. If you optimised models with 0.8.0 or 0.8.1, restore the originals from git and run it again.

0.8.1 (alpha), 2026-11-20​

  • Fixed: popfold describe gave different places and sizes each time it ran, by up to 20 cm for pieces on a diorama's folding walls, because it measured whatever frame the page was on. It now measures a settled scene, so two runs can be compared.
  • Fixed: popfold optimize in a site with no public/models folder stopped with an error. It now says there is nothing to do.

0.8.0 (alpha), 2026-11-20​

  • popfold optimize makes a site's models smaller without changing how they look: usually 40 to 65%. It removes duplicate data, packs geometry with meshopt and saves textures as WebP, and leaves every position and every node where it was, which Popfold depends on. Run it in a site, then popfold stills --check.
  • The engine loads meshopt-compressed models with WebP textures.
  • Popfold's own case models are optimised: 495 KB each before, 224 KB now. Nothing looks different.
  • popfold check warns when a site ships models that are not compressed.

0.7.0 (alpha), 2026-11-20​

  • Fixed: the gold rim of the modelled case flickered between gold and the base colour along the floor's edge, most visibly on the 'crisp' case. The rim's top face lay in the same plane as the base's; it now sits a hair above it. Both case models are rebuilt.
  • The home is a JSON file. The templates keep what is in a home (its id and name, a tower's floors, the pieces and their stories) in src/home.json, with a JSON Schema (schema/home.schema.json) that editors check as you type. readHome(json) checks the file when the site loads and names every mistake in it, with the piece it is in. home.ts keeps only code: the look and how each kind of piece is built. Lists written in TypeScript still work.
  • The studio shows the camera. In Free orbit, the panel gives the camera's position and the point it looks at, and Copy for a beat copies them as the two arrays a beat takes. No browser console needed.
  • A tower template, templates/tower: a studio in a four-floor building, six sections, no model files. popfold init <folder> --template tower starts a site from it.
  • A tower lists its pieces as data too. The same recipe.pieces and recipe.kinds as a compact; a piece's room is its floor's id, and a kind is told which floor it is building for (ctx.color). Pieces on a floor's back wall are keyed <floor>-wall/<id>. A floor's build() is now optional and runs after its listed pieces.
  • mountStudio({ mood: 'evening' }): the studio opens, and captures the stills, in the time of day the site shows its home in.
  • The README that popfold init writes takes its table of files from the template it copied.

0.6.0 (alpha), 2026-11-20​

  • A skill for AI agents, skills/popfold-site/SKILL.md: the order of work for making or changing a site, how to build a piece, and how to check and look at the result.
  • popfold init: a failed run removes what it made, so it can be run again; --from accepts a folder on this machine. popfold check warns about stills of a home no page shows. popfold shot --out makes the folder it is given.
  • A compact home can list its pieces as data. recipe.pieces is a list of { id, room, kind, at, … } and recipe.kinds says how to build each kind (a kind that names a model file in props needs no entry). Every listed piece has the key <room>/<id>. furnish() is now optional and runs after the list. The template is written this way; its keys and its stills are unchanged.
  • A listed piece carries its own story (story: { title, text, tags }), so a story can no longer point at a piece that is not there. popfoldFallback({ pieces }) writes those stories into the page without 3D; stories by key still works, for pieces placed in code. The template's stories.ts is now pieces.ts: the pieces, where they stand and their stories in one plain-data file.
  • The popfold command says at once why a home could not be built (a mistyped kind, say). It used to wait two minutes and report a timeout.
  • CI opens the template in a browser and runs popfold check on it. POPFOLD_GPU=off makes the command draw in software, as a machine without a GPU does.
  • Fixed: the README that popfold init writes named src/keyframes.ts, which is src/beats.ts since 0.5.0.
  • Pieces can have an id of their own. piece(obj, 'reading-lamp') makes the piece's key <room>/reading-lamp whatever is added or removed around it, so its story and its layout entry stay on it. A diorama piece takes its id from a custom property id in the model. Pieces without an id keep their generated keys. popfold check warns when a story or a layout entry hangs on a numbered piece, and fails when two pieces in a room share an id; popfold describe lists each piece's id and whether a layout moved it.

0.5.0 (alpha), 2026-11-20​

  • Stories can be reached without a mouse in 3D mode. The written-out stories are no longer removed when 3D starts: a screen reader reads them under their section, and the Tab key reaches each one and brings its section's list into view. The Simple view button now comes first in the page, not last.

  • The scene draws less when little is happening (quality: 'auto', the default on a site). While the story is at rest it draws every other frame, and goes back to full rate the moment the page scrolls or the pointer moves. On a device that cannot keep up it steps the picture down (fewer pixels, then a smaller shadow map); each step is undone if it does not help. quality: 'high' switches this off, and the studio always uses it.

  • The story is one list of beats. startScene({ beats }) and mountStudio({ beats }) replace keyframes and stopNames. A beat is beat('section-id', 'Name', values, camera, lookAt, zones?): the section it belongs to, the name the studio shows, and the keyframe. popfold check compares the beats with the page's sections by id and names the one that is missing or out of order. To move a site over: wrap each keyframe(…) in beat(id, name, …), pass beats, and drop the stop names.

  • scrollStage() in popfold/fallback gives getStage from the scroll position, replacing fifteen lines every site's main.ts carried.

  • Three commands for seeing and checking a site without opening a browser, made for agents and useful to people:

    • popfold check looks for the mistakes that fail silently: sections, keyframes and stop names that do not line up, a story or a layout entry that matches no piece (with the key it probably meant), a story whose section the page does not have, a model that did not load, missing stills, heavy models. It exits 1 on an error; --json prints the list as data.
    • popfold describe [--home id] prints every home as JSON: each piece with its key, room, place, size and story. scene.describe() returns the same for one home.
    • popfold shot [--home id] [--stage n] [--cam name] [--light evening] [--out file.png] saves a picture of any view, not only the story stops.
  • popfold init <folder> starts a new site: its own git repository, Popfold inside it as a submodule on the newest release, and the compact template from that same release as its first pages. --name, --port and --ref choose the package name, the dev port and the Popfold release.

  • Enter or Space on a focused story opens its card in 3D, beside its piece, and closing the card gives the keyboard focus back to the story. The written stories carry their key as data-pf-story.

  • A build now fails when a story has no section to go under (it was a warning that was easy to miss). The message names the stories and the missing section. The dev server still only warns.

  • Unit tests for piece keys and layouts.

  • pnpm test names its test files with a pattern, so it also runs on Linux (it failed in CI on 0.4.0).

0.4.0 (alpha), 2026-11-20​

  • Several story pages in one site. popfoldFallback({ pages: [{ html, stories, sections, stillsHome }, …] }). Each page gets its own stories and stills (paths work from a sub-folder), llms.txt and the sitemap cover every page, and popfold stills captures each page's home from that page's own studio. A site with one page changes nothing.
  • scene.dispose() stops a scene for good: its loop, its listeners and its GPU memory.
  • No more three.js deprecation warnings (the clock, the shadow type, the iridescence range). No visual change.
  • Unit tests (pnpm test) for the story blending, the story-link rule and the page writer; CI runs them.
  • Template: vite.config.ts imports the stories with their file extension, which Vite's next config loader needs. Sites copied from it: do the same and add "allowImportingTsExtensions": true to tsconfig.json.

0.3.0 (alpha), 2026-11-19​

Sites have to act on this release.

  • The compact's case is part of a home's look. look.shell is 'round' (the default, as before), 'crisp' (a new modelled shell with nearly square edges), 'code' (simple shapes) or { url } (your own model). look.corner, from 0 to 1, sets how round the code-built case is. The scene option shellUrl is gone: use look.shell: 'code' where you passed shellUrl: null, and look.shell: { url } where you passed a url.
  • No heart unless a home asks. emblem: { heart: true } puts the heart on the lid; the default is none.
  • tools/blender/build_compact.py takes --corner, --no-heart and --out, so a site can build its own shell.

0.2.1 (alpha), 2026-11-19​

  • Story links can point within the site (docs/guide, ./tour/, #contact); they open in the same tab. http, https and mailto links still open in a new one. Anything else (javascript:, data:, //host) is dropped, as before.

0.2.0 (alpha), 2026-11-19​

Sites have to act on this release. Popfold no longer carries one site's colours. Defaults are neutral, and a site that wants its own look sets it:

  • Story card: its colours and fonts are CSS variables on :root (--pf-card-bg, --pf-card-ink, --pf-card-accent, --pf-card-tag, --pf-card-focus, --pf-card-font, --pf-card-display). Default: white card, ink outline, yellow accents.

  • Story dots: startScene({ storyDot }) and mountStudio({ storyDot }). Default: blue.

  • Step badges: look.badges and look.badgeRing. The default ring is ink, not wine.

  • The heart: emblem: { heart: false } now also hides the raised heart on the shell model.

  • Studio: a neutral theme; mountStudio({ theme }) restyles it. The default backdrop is Paper, and the pink one is called Blush (?bg=blush).

  • Template: a neutral favicon.

  • base option on startScene() and mountStudio(): where the site's models, layouts and art are, as seen from the page. A page in a sub-folder passes '../'. The studio's save endpoints no longer depend on it.

  • pnpm release dates a release by the local calendar, not UTC.

  • Stills: the capture waits for the page's pictures to finish loading, so a cold first run matches later ones.

  • Template: the scene no longer runs a section behind the text. templates/compact/src/main.ts measured the sections only at start, on resize and on load. When 3D starts the written-out stories are hidden, so a section that was taller than the window shrinks and the stored positions go stale; late web fonts do the same. It now measures again whenever <main> changes height. Sites copied from the template: add the same line to your own src/main.ts, after the resize and load listeners: new ResizeObserver(measure).observe(document.getElementById('main') as HTMLElement);

0.1.3 (alpha), 2026-11-20​

  • Docs: how to change the engine from a site's own popfold/ copy, on a branch, so several sessions can work from different sites at once (docs/releasing.md, AGENTS.md).
  • pnpm release fetches first and refuses to run when main is behind origin/main.

0.1.2 (alpha), 2026-11-20​

  • Repeatable stills. The scene has hold(on) and step(n): holding stops its own clock and puts every moving part back to its starting pose. The studio holds before each still, so the same scene gives the same picture. Light pipes start at a fixed phase instead of a random one.
  • popfold stills rewrites only the stills that changed (more than 0.02% of pixels), and lists them. Git stays quiet when nothing changed.
  • popfold stills --check captures and compares without changing a file, and fails if any still differs.
  • Sites: the first capture after this release rewrites most stills once, because the old ones were taken at an arbitrary moment. Commit them; after that only real changes show up.

0.1.1 (alpha), 2026-11-20​

  • popfold update [tag]: in a site, moves the popfold/ submodule to a release (the newest by default), then installs, typechecks and builds to prove the site still works. Nothing is committed for you.
  • pnpm release <version>: cuts a Popfold release locally: changelog, versions, typecheck, build, commit, tag.
  • Docs: docs/releasing.md describes both sides of a release. TODO.md holds the backlog.
  • CI: moved to the current versions of the checkout, Node and pnpm actions.

0.1.0 (alpha), 2026-11-19​

The first version of Popfold in its own repository. It was grown inside a monorepo next to the first sites built on it; that history stays there.

  • Engine: scroll-driven 3D pocket homes with three shells: the compact (or pop-up book), the diorama and the tower. Lighting, room names and page-click handling are options of the site.
  • Studio: a workbench on each site to scrub the story, fold by hand, lay out pieces and capture stills.
  • Page without 3D: stories, stills, structured data, llms.txt, robots and sitemap built into the HTML.
  • Command: popfold build and popfold stills, with headless capture.
  • Template: templates/compact, a complete small site to copy.
  • Model tools: Blender scripts (tools/blender) and the AI model pipeline (tools/forge).
  • Docs: a guide, a site walkthrough, model docs and agent docs in docs/.