Popfold
Status: alpha (0.25.0). Everything here is experimental and changes often. Backwards compatibility is not required (APIs, recipes, layout keys, file formats, folder layout) until a version 1.0.0 or later is tagged. Until then, expect breaking changes in any commit and don't depend on anything staying put.
Scroll-driven 3D "pocket homes" for the web: a little shell (a compact, or a pop-up book) that unfolds into three rooms as the visitor scrolls, with furniture that springs in, a camera that follows the story, clickable stories on pieces and an optional guide figure. Built on three.js; used as TypeScript source by Vite sites.
Guides (how it works, building a site, making models, working on it as an agent) are in docs/; start at
docs/README.md. This page is the API reference.
Use it in a site
import { startScene, createStoryCard, type HomeRecipe } from 'popfold';
const scene = await startScene({
canvas, // a full-window <canvas>
homes: [myHome], // HomeRecipe[]: every home the page can show
home: 'my-home', // the one to show first
beats: BEATS, // the story, one beat per page section: from homeFromFile(json, { kinds }), or beat('section-id', 'Name', values, camera, lookAt)
getStage: scrollStage(), // where the story is, from the scroll position (from 'popfold/fallback')
reducedMotion,
avatar: false, // or { url: 'models/figure.glb' } for a rigged guide (the built-in figure is the fallback)
// lighting: { day: { sky: '#FFF1F7' }, shadow: '#7A1240' }, // the site's own light (optional)
// storyDot: '#E8104F', // the colour of the dots on pieces with a story
// base: '../', // for a page in a sub-folder: where the site's models and layouts are from here
onStory: (story, key, x, y) => card.open(story, x, y), // with const card = createStoryCard()
onPick: (part) => {}, // a click on 'center' | 'left' | 'right'
});
scene.setHome('other-home'); // swap homes; also flags, override, setOrbit, setLighting, snapshot... for tools
scene.dispose(); // stop it for good and free the GPU (single-page apps, tests)
templates/compact (an office in a box) and templates/tower (a four-floor building) are complete, short sites
to copy: node bin/popfold.mjs init <folder> [--template tower] starts a new site from one.
Popfold Studio on a site
Add a studio.html page that loads a script calling mountStudio() from popfold/studio with the site's homes
and beats (see templates/compact/src/studio.ts), list it in the Vite build inputs, and add
layoutSaver({ home: 'src/home.json' }) from popfold/vite to the Vite plugins so Save layout can write a moved
piece back into the home file (and public/layouts/ for what the file cannot hold) on the local dev server. Unsaved changes are kept per home as a draft in the browser's localStorage and offered back after a
reload.
Without 3D: the simple page
Every Popfold site works without WebGL, without JavaScript and for crawlers and AI agents. The page starts as the simple version and only upgrades to 3D once the scene is running.
- Build time:
popfoldFallback({ siteName, homeFile, sections, jsonLd, siteUrl })frompopfold/vite(for a home kept in code:storiesandstillsHomein place ofhomeFile) writes each story under its section (<div class="pf-stories">), puts a still beside every stage section (public/stills/<home>-<n>.webp, n = keyframe), adds the fallback CSS, JSON-LD,og:imageandcanonical(withsiteUrl), and emitsllms.txt,robots.txtandsitemap.xml(withsiteUrl). - In the browser:
popfold/fallback:shouldStart3D()(WebGL present; not?view=simple, a saved "simple" choice, Save-Data or a very low-memory device),markReady(canvas)afterstartScene(setshtml.has-3d, falls back if the GPU context is lost),markFallback(), andviewToggle()for the "Simple view / 3D view" button. - Stills: in a site's studio (dev server), Capture stills steps through every story stop and saves one WebP per stop. Recapture after changing a home or its camera path.
- From a script: run
popfold buildin a site's folder (each site haspnpm build:static). It captures fresh stills headlessly and then runsvite build.popfold build --keepbuilds with the stills already there, andpopfold stillsonly captures them. Captures are repeatable, and a still that looks the same as before is put back untouched, so git shows only the stills that really changed.popfold stills --checkchanges nothing and fails if any still differs: a visual test.popfold checkreports mistakes (lists that do not line up, stories and layout entries that match no piece, models that did not load),popfold describeprints every home as JSON, andpopfold shotsaves a picture of any view. They all read the home frompopfoldFallback(), so there is nothing extra to configure. It needs a local Chrome or Edge (orPOPFOLD_BROWSER=<path to Chromium>) and the optionalplaywright-corepackage. It uses the GPU when there is one, about 20 s a site; without one it draws in software, which takes minutes. Every page has a debug panel, opened with the Debug button beside Simple view,?debugin the address or Alt+Shift+D: the build's versions and live numbers on how the page is running (debug: falsetakes it away; seedocs/guide.md).popfold optimizemakes the models inpublic/modelssmaller (usually 40 to 65%) without changing how they look or moving anything in them; seedocs/models.md.
?view=simple or ?view=3d in the address forces a mode for testing.
A site with several story pages lists them: popfoldFallback({ siteName, siteUrl, pages: [{ html, stories, sections, stillsHome }, …] }). See "More than one story page" in docs/guide.md.
A home: HomeRecipe
The templates keep a home in a JSON file and make the recipe from it: const { recipe, beats } = homeFromFile(json, { kinds }) (see docs/create-a-site.md). The same recipe written out in code:
const myHome: HomeRecipe = {
id: 'my-home', name: 'My home', blurb: '…', swatch: ['#…', '#…', '#…', '#…'],
look: { base, lid, heart, leftSlab, rightSlab, centerFloor: () => tex.checker(…), lidPaper, leftFloor, leftWall, rightFloor, rightWall },
pieces: [ // what is in the home: floor pieces at [x, z], wall pieces at [x, height]
{ id: 'sofa', room: 'center', kind: 'sofa', at: [0, -1.3], story: { title: '…', text: '…', tags: ['…'] } },
{ id: 'reading-lamp', room: 'left', kind: 'lamp', size: 1.2, at: [1.5, -1.3] }, // a model file
{ id: 'print', room: 'right', wall: true, kind: 'print', at: [1.4, 1.5] },
],
kinds: { // how to build each kind that is not a model file
sofa: () => P.sofa(),
print: () => P.pictureFrame(0.6, 0.6, tex.blobArt(…), '#fff'),
},
props: ['lamp'], propDir: 'models/props', // model files: <propDir>/<name>.glb, longest side = 1, front +Z
emblem: { title: 'my', subtitle: 'home' },
// rooms: { center: 'living', left: 'closet', right: 'dream' }, // your own room names in keys
fold: 'compact', // or 'book'
};
A piece's key is <room>/<id> (<room>-wall/<id> on a wall). Other fields of a piece: turn, lift, out,
delay, lamp and opts (see PieceSpec in types.ts). For what a list cannot say, a recipe can also have
furnish(ctx), which places pieces in code after the listed ones.
In furnish(ctx): rooms are 4 units wide; side-room walls are 2.2 tall. Floor pieces sit at y0 (centre) or fy (side rooms); wall
pieces go on left.wall / right.wall at z ≈ 0.14; the open lid is the centre room's back wall (add with
rotation.x = PI/2, y = -0.04, z = height). pop(list, obj, delay) makes a piece spring in with its room.
ctx.setLamp({ group, bulb }) names the lamp whose glow the story controls. Built-in pieces are in P (they tag
themselves for layouts), colours in C, canvas textures in tex.
Layouts and stories
Every popped piece gets a key. piece(obj, 'reading-lamp') gives a piece its own id and the key <room>/<id>,
which stays put when pieces are added around it; without an id the key is <room>/<prop> (#2… for repeats, in
the order the code adds them). In a diorama's model, a custom property id on a piece does the same. A compact's rooms are center, left and
right unless the recipe names them (rooms), with -wall for wall pieces; a diorama's are its zones; a tower's
are its floor ids. A home file's places (or, for a home made in code, public/layouts/<home id>.json) moves,
turns, resizes or hides pieces by key (layout.ts); Popfold Studio writes them. A listed piece's story puts a dot on it and opens a story card; recipe.stories does the same
by key for pieces placed in code.
Files
| File | |
|---|---|
engine.ts | startScene(): renderer, lights, story playback, folds, guide figure, picking, studio hooks |
compact.ts | the shell and three rooms; places recipe.pieces, calls recipe.furnish(); keys pieces for layouts |
types.ts | HomeRecipe, Look, FurnishContext, PropStory |
keyframes.ts | story fields, beat(), a beat as data (beatsOf()), keyframe(), sample() |
layout.ts, hotspots.ts, story-card.ts | layouts, story dots, the story card |
diorama.ts | the room shell: a modelled room whose walls unfold (from tools/blender/room_to_glb.py) |
studio/ | Popfold Studio (mountStudio), its props inspector and styles |
vite-plugin.ts | layoutSaver(), the dev-server endpoints the studio saves through (the home file, layouts, stills) |
props.ts, textures.ts, effects.ts, avatar.ts | built-in pieces, canvas textures, sparkles, the built-in guide figure |
Making it look like your site
Nothing in Popfold carries a brand. A site sets its own:
| What | How |
|---|---|
| Light and the ground shadow | startScene({ lighting }) |
| Story dots | startScene({ storyDot: '#…' }) |
| The story card | 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 |
| A compact's step badges | look.badges (three [background, number] pairs) and look.badgeRing |
| The compact's case | look.shell: 'round' (default), 'crisp', 'code' (with look.corner, 0 sharp to 1 soft) or { url } for your own model |
| A heart on a compact's lid | emblem: { heart: true } adds it (off by default) |
| The studio's panel | mountStudio({ theme: { accent: '#…', ink: '#…', paper: '#…' } }) |
Pass lighting, storyDot and base to mountStudio() as well, so the studio and its stills match the site.
Releases
A site holds Popfold as a git submodule pinned to a release tag, and moves to a newer one with
pnpm exec popfold update [tag]. pnpm release <version> cuts a release here. Both are described in
docs/releasing.md; CHANGELOG.md says what each release changed.
License
MIT (see LICENSE).