Skip to main content

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 }) from popfold/vite (for a home kept in code: stories and stillsHome in place of homeFile) 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:image and canonical (with siteUrl), and emits llms.txt, robots.txt and sitemap.xml (with siteUrl).
  • 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) after startScene (sets html.has-3d, falls back if the GPU context is lost), markFallback(), and viewToggle() 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 build in a site's folder (each site has pnpm build:static). It captures fresh stills headlessly and then runs vite build. popfold build --keep builds with the stills already there, and popfold stills only 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 --check changes nothing and fails if any still differs: a visual test. popfold check reports mistakes (lists that do not line up, stories and layout entries that match no piece, models that did not load), popfold describe prints every home as JSON, and popfold shot saves a picture of any view. They all read the home from popfoldFallback(), so there is nothing extra to configure. It needs a local Chrome or Edge (or POPFOLD_BROWSER=<path to Chromium>) and the optional playwright-core package. 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, ?debug in the address or Alt+Shift+D: the build's versions and live numbers on how the page is running (debug: false takes it away; see docs/guide.md). popfold optimize makes the models in public/models smaller (usually 40 to 65%) without changing how they look or moving anything in them; see docs/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.tsstartScene(): renderer, lights, story playback, folds, guide figure, picking, studio hooks
compact.tsthe shell and three rooms; places recipe.pieces, calls recipe.furnish(); keys pieces for layouts
types.tsHomeRecipe, Look, FurnishContext, PropStory
keyframes.tsstory fields, beat(), a beat as data (beatsOf()), keyframe(), sample()
layout.ts, hotspots.ts, story-card.tslayouts, story dots, the story card
diorama.tsthe 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.tslayoutSaver(), the dev-server endpoints the studio saves through (the home file, layouts, stills)
props.ts, textures.ts, effects.ts, avatar.tsbuilt-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:

WhatHow
Light and the ground shadowstartScene({ lighting })
Story dotsstartScene({ storyDot: '#…' })
The story cardCSS 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 badgeslook.badges (three [background, number] pairs) and look.badgeRing
The compact's caselook.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 lidemblem: { heart: true } adds it (off by default)
The studio's panelmountStudio({ 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).