TODO
What is planned for Popfold. Sizes: S under half a day, M one or two days, L a week or more. Popfold is alpha: anything here may break existing sites, and that is allowed before 1.0.0.
Next, in order of priority
As of 0.24.0. Each line is described in full in its section below.
Done on the way here: every site's homes are data (src/*.json: the story, the look or a tower's floors, the
pieces and their stories, a diorama's model parts), and the studio edits all of it without a reload, through one
command list that popfold mcp also offers an agent, with undo of saves; shells are plug-ins; the warm-up builds
only what is shown; the page without 3D is parsed, not pattern-matched; lint, credits and browser checks.
- The layout files go away (S). No site uses
public/layouts/any more (a home made from its file keeps its places in the file), so the engine's fetch of it, the studio's layout endpoint and the docs for it can go, and a home made in code says plainly that the studio cannot save it. - The visual test in CI (M), on Machine.dev's GPU runners:
popfold stills --checkon both templates and on every site, so an engine change that alters a picture is caught before a release. - Staged loading for a diorama's room and for homes made in code (M). The consulting room is one 1.7 MB model, so its first view waits for all of it.
- Studio gaps: add, remove and reorder beats (M; each needs its section in the page), stills for every home and not only the one a page names (S), a tower's wall, slab and pipe colours in the Look group (S).
- Small leftovers (section 2): the pnpm warning in every site, both case models in every build, one site's colours in the built-in pieces, the engine's fixed three badges, one lamp and 4-unit room.
- Later, larger:
popfold forge, Full mode (a chat panel in the studio on the command list), brief to site, a built package with a web component, other outputs (a story video, share images).
1. Living as its own repository
Popfold was split out of the monorepo it was grown in at 0.1.0. Sites hold it as a git submodule in popfold/,
pinned to a tag, and use it through a pnpm workspace.
- Site CI can read Popfold. A read-only deploy key here ("Site CI (read-only)"), with its private half in
each site as the secret
POPFOLD_DEPLOY_KEY. A new site needs the same secret, or its own key. -
popfold updatefor sites: moves the submodule to a release, installs, typechecks and builds. -
popfold stillslists and rewrites only the stills that really changed. - A visual test: captures are repeatable and
popfold stills --checkfails when a still differs. - CI opens the template in a browser and runs
popfold checkon it (software rendering, a few seconds). - Run the visual test in CI (M). CI has no GPU, so it draws in software: slow, and not pixel-identical to a GPU. It needs its own reference stills made on the same renderer, a smaller frame, and a measured tolerance.
- Release routine:
pnpm release <version>anddocs/releasing.md. - CI uses the current major versions of the checkout, Node and pnpm actions.
- After a build step exists (see "Reach"): publish Popfold as a package and drop the submodules.
2. Small things left from the split
- In a site, every pnpm command warns that
popfold/pnpm-workspace.yamlis ignored (Popfold is a project of the site's workspace there). Harmless, but noisy. Find a layout that keeps the template buildable here without that file being seen by sites. - Both case models (224 KB each since they were optimised) are copied into every site's
dist/, including sites that never load them. - Interchangeable shell parts. Let a home take its base, lid, drawers, walls and clasp from different models, and make the clasp (and the heart) a part of its own, so sites can mix end pieces.
- The template and docs import the stories in
vite.config.tswith their file extension. - The look is the site's: story card, story dots, badges, the lid's heart and the studio's theme are options.
- The built-in pieces (
P.sofa()and the rest) and the paletteCstill have one site's colours baked in. - Several story pages in one site:
popfoldFallback({ pages }), stills per page, one build. - A tower template,
templates/tower;popfold init --template towerstarts a site from it, and CI runspopfold checkon it. - A diorama template. It needs a modelled room (
.glb) that Popfold can ship. - The studio and the stills use the site's time of day only if the studio page passes
mood; the site sets its own withsetLighting(). One option on the recipe would say it once. -
tools/blender/room_to_glb.pystill assumes the room's orientation (back wall +y, right wall +x) and two walls. - Three badges, one lamp, a 4-unit room and the guide's standing height are constants in the engine.
3. Next for the engine
Roughly in this order. Each is its own piece of work.
- Homes as data (L, done by 0.24.0: every site's homes are kept in files). One file per home: zones, pieces with explicit ids, stories, beats with cameras.
This fixes three faults at once: a home is code (so the studio and an AI can only move pieces), piece keys
depend on the order of the code, and sections and beats are two lists matched by position.
- Keyframes and stop names are one list of beats, each carrying its section's id;
popfold checkcompares them with the page. - A piece can carry an id of its own (
piece(obj, id)), which fixes its key. Pieces placed in code without one are still numbered by order;popfold checkwarns when a story or a layout entry hangs on one. - A compact's recipe lists its pieces as data (
pieces), withkindsto build each kind: the registry that keeps code-built pieces working. - A listed piece carries its own story; the page without 3D reads the same list.
- Listed pieces for the tower's floors: the same
pieceslist, with a floor's id as the piece'sroom. - The home file is plain JSON,
src/home.json, with a JSON Schema andreadHome(), which names every mistake in it. It holds the home's id and name, a tower's floors, the pieces and their stories. - A compact's look is data (
look: colours, and each surface as a colour or a pattern), with the lid's emblem and the picker's swatches.homeFromFile(json, { kinds })makes the home and its story. - A tower's own colours (wall, slab, pipe) as data, and editing a look in the studio (S to M).
- The studio saves a moved, turned or resized listed piece into
home.json: only that piece's line changes. - Hiding a listed piece is saved in the home file, and the studio adds and removes pieces.
- Beats are in the home file (
beats), andbeatsOf()turns them into the story. - Layout files go away (S): they now hold only hidden pieces and pieces placed in code.
- Keyframes and stop names are one list of beats, each carrying its section's id;
- Shells as plug-ins (0.22.0). One
Shellinterface and a registry; the frame loop no longer knows about lids and drawers. The story's fields are still c / L / R / z:; naming every shell's zones freely is next. -
scene.dispose(): stops the loop, drops every listener and frees the GPU memory. - Draws less at rest, and steps quality down on slow devices (
quality: 'auto'). Not yet tested on a genuinely slow device. - Draw nothing at all when nothing moves: needs the ambient motion (float, sparkles, pulses) to be optional.
- Stories reachable by keyboard and screen reader in 3D mode.
- In 3D mode, Enter or Space on a focused story opens its card beside its piece.
- Point the camera at a story's piece when its card is opened from the keyboard and the piece is out of view.
-
popfold describe,popfold shot,popfold check. A home as JSON, a picture of any view, and errors an agent can act on. -
popfold init: a new site from the compact template, with Popfold as a submodule on a release. - Unit tests for
sample(), the link rule and the fallback writer, run in CI. - Tests for piece keys and layouts.
- Browser tests for the
popfoldcommand:pnpm test:browser(check, describe, shot, mcp). Not in CI yet. - The command reports a home that cannot be built at once, with the reason.
-
popfold optimize: makes models smaller (40 to 65%) without moving anything in them or changing a pixel. The engine reads meshopt-compressed models with WebP textures;popfold checksays when a site's models have not been through it. - Models load in stages (
lazyModels): the home appears with its first rooms' models and the rest follow. For a compact whose pieces are all listed. - The same for a tower (its top floors first), and a late piece springs in.
-
models: glow, no auto-loop and areadyhook for a model that is a listed kind, so a site's lamps and animated pieces need no code kind and still load in stages. - A smooth first scroll: a steady number of lights, and a warm-up that builds each beat's materials in the background.
- The warm-up builds only what each beat shows: three.js compiled hidden meshes too (48 programs down to 29 on a larger site, 22 to 18 on the compact template, none missed).
- A late model is warmed as it lands and a home before
setHomeshows it;warmUp: 'wait'for a site with a loader. - Staged loading for homes that place pieces in code, and for a diorama's one big model (M).
-
startScene({ onHome })tells a site which home is on show, and a piece'soptsmay hold lists. - A size budget for models that stops a build (
modelBudget). - A credits check in
popfold check(0.23.0). - Squeeze positions too, for another 10 to 15% (M): needs the shells to stop reading placement off model nodes, or the tool to put each part's transform back.
- The tower's first still is repeatable: the capture starts from the first beat at rest. (The pipes run faster as floors light up, so the first still used to carry over whatever the page was showing.)
- The three.js deprecation warnings are gone.
- A build fails when a story has no section to go under.
- Parse the HTML properly in the fallback plugin (0.23.0, parse5).
popfold checkstill finds sections by pattern. - Rename the code to the glossary in
docs/guide.md(S), once homes are data.Compactis still the type name for every shell's house. - A linter (Biome, 0.23.0). No formatter: reformatting would rewrap most lines of the hand-kept style.
4. Studio
- Drafts: unsaved layout changes survive a reload.
- In Free orbit the studio shows the camera's position and the point it looks at, and copies them as the two arrays of a beat.
- The studio sets a beat's camera from the current view and saves it into the home file.
- The studio saves what a beat does from the Fold sliders.
- Add, remove and reorder beats from the studio (M). A beat needs its
<section class="stage">in the page, so this means the studio editingindex.htmltoo, or the page's sections being made from the beats. - Edit everything, not only positions (L, 0.20.0): move, turn, resize, hide, add, remove and swap pieces, write their stories, set a beat's camera and every value it sets, and the look.
- Adding, removing, a story, a kind or a look change rebuild the home in place, without a reload (0.20.0).
- Undo and redo for unsaved piece edits (moves, turns, sizes, hiding).
- One command list that the studio and agents use, with undo and redo of saves (0.21.0).
- Save from anywhere (M): a small service behind sign-in that commits the home file to a branch, for editing through a tunnel or by someone else. The dev endpoint stays local-only.
- Capture stills for every home, not only the one named in the config (S). First decide where stills that no
page shows are kept: in
public/stills/they would ship in every build.
5. AI
- A local vision model that plans, picks and judges props (
tools/forge/director.py). - MCP server
popfold mcpon top of the command list (0.21.0). - An agent skill,
skills/popfold-site/SKILL.md: the order of work for making or changing a site. A fresh agent built a site from it alone; what tripped it up is fixed in the skill, the docs and the command. -
popfold forge(M to L): the pipeline as one command, with swappable back ends (local ComfyUI or a hosted service), provenance written into each model, and clean-up without Blender for the common case. - Full mode (L): a chat panel in the studio that uses the command list, sees snapshots, and can generate pieces and art into the scene. Start with a dev-server proxy so no key reaches the page.
- Brief to site (M): from a questionnaire or a resume to beats, copy, a shell and a first home.
- Check the licence of every generating model before anything goes public (S).
6. Reach
- A built package and a web component (
<popfold-home>), so Popfold works outside Vite (L). Today it runs only as TypeScript source inside a Vite site. - Other outputs from the same home: a story video, share images per beat, one animated
.glb, AR, and a print-and-fold paper compact. - Tools for visiting agents (go to a beat, list pieces, read a story), as browser support arrives.
- More shells: dollhouse, suitcase, shop window, a train of carriages.