# Popfold: a web page that unfolds Page: https://popfold.ca/ > Popfold is an alpha three.js engine that turns a long web page into a small 3D world that opens as you scroll, with clickable stories, a studio page and a version of the page without 3D. ## A web page that unfolds. Popfold · alpha Popfold turns a long page into a small 3D world that opens as you scroll. Each section is one beat of a story: a box opens, rooms slide out, pieces spring in, the camera moves on. Open the box Read the docs Built on three.js. This page is made with it. Everything is alpha and can still change. ## One section, one beat. The story Your page stays an ordinary HTML page. Each section is a stop in the story, and a keyframe says how far the box is open and where the camera stands at that stop. The page tells the engine one thing, many times a second: which section are we at? The engine blends the keyframes on either side and draws the result. Click the dots in the rooms for the story behind each piece. - **The page stays a page**: All the copy lives in one ordinary HTML file. The engine never reads it. The page only reports, many times a second, which section is in the middle of the screen. [index.html, getStage()] - **One section, one stop**: Each section of the page is a stop in the story. The story is one list of beats, and each beat carries the id of its section. A check command names a beat or a section that has lost its partner. [Sections, beat()] - **Keyframes, blended**: A keyframe says how far each room is open and where the camera stands. Between two sections the scene holds still for the first and last fifth and eases through the middle, so every section rests while it is centred. [beat(), sample()] ## Things spring in. Any of them can talk. Pieces A piece comes from a small built-in set, from your own code, or from a model file. Give a piece a story and it gets a dot; a click opens a card. Everything in this box is built in code. Built-in pieces Your own code .glb models - **Three ways to get a piece**: Use one of the built-in pieces, build your own from boxes and cylinders, or load a .glb model. A model that fails to load falls back to a code-built piece, so the page still works. [Built-in, Code-built, .glb] - **Everything here is code**: This box uses no model files. Every piece is a few lines of three.js: rounded boxes, cylinders and textures drawn on a canvas. [three.js, Canvas textures] - **Every piece has a key**: A piece is named by its room and its builder, such as "pieces/workbench". Layouts and stories use that key. A piece can be given an id of its own, so its key stays the same whatever is added around it. Pieces without one are numbered in the order the code adds them, and a check command warns when a story hangs on such a number. [Keys, Layouts] ## A workbench on every site. Studio Each Popfold site has a studio page that runs the same engine. Scrub the story, fold the box by hand, move a piece and save where it stands, set a beat's camera and what it opens, switch to evening light, capture a still of every stop. Open this page's studio Saving works only on your own machine. Here you can look and play. - **The same engine, driven by hand**: The studio page runs the scene from a panel instead of the scroll position: scrub the story, open the folds, orbit the camera, move a piece and save where it stands. [mountStudio(), Layouts] - **A still of every stop**: The build opens the studio in a headless browser and captures one picture per stop. Captures are repeatable, so a still that did not change is left untouched and a changed one shows up in git. [popfold stills, Visual test] - **The page without 3D**: The build writes every story under its section, puts a still beside each one, and adds llms.txt, robots.txt and structured data. The 3D scene starts only if the browser can run it. [popfoldFallback(), llms.txt] ## The same page, no 3D needed. Without 3D The HTML that ships is already complete: the copy, a still of every stop, and every story written out. The 3D scene starts only if the browser can run it. Old browsers, search engines and AI agents read the same story. Show this page without 3D Read llms.txt ## Three ways to fold. Shells The compact is this box: a lid and two drawers, or pages that turn like a pop-up book. The diorama is one modelled room whose walls swing up. The tower is a stack of floors with an elevator and glowing pipes, for long stories and diagrams. Compact Pop-up book Tower The buttons fold this box again, or swap it for a small tower. The diorama needs a modelled room, so it is not shown here yet. ## Seven layers, all in the open. How it is built The page and its sections The story : one beat per section The engine : light, camera, the frame loop, clicks The shells : compact, diorama, tower The studio : the workbench page The build : stills and the page without 3D The model tools : from a picture to a piece Ride the tower Read the guide ## Start from the template. Start One command, popfold init , starts a new site as a copy of a template: an office in a box or a small tower, six sections, no model files. Its story, pieces and cards sit in one JSON file. What alpha means here: Popfold runs only as TypeScript source inside a Vite site, there is no package to install, anything beyond the built-in pieces is still code, and nothing is kept backwards compatible before 1.0. Create a site All the docs Docs: ./docs/ (the guide, building a site, making models, the API). --- # How Popfold is built: seven layers Page: https://popfold.ca/architecture/ > The architecture of Popfold, an alpha three.js engine for scroll-driven 3D pages, told as a tower: the page, the story, the engine, the shells, the studio, the build and the model tools. ## Seven layers, top to bottom. Architecture · alpha Popfold is a few thousand lines of TypeScript that a Vite site imports. This tower is its map: one floor per layer, from the page a visitor reads down to the tools that make the models. The pipe beside the lift is the one number the page sends: which section we are at. Every floor reads it. The other pipes show what feeds what. Ride down ## The page Layer 1 of 7 A Popfold site is an ordinary HTML page. Every beat of the story is a section, and the copy is all there before any script runs. The page does one job for the 3D: it reports which section is in the middle of the screen. index.html src/main.ts Click the dots on each floor for the details. - **All the copy, in one HTML file**: Each section with the class "stage" is one stop of the story. The canvas is fixed behind the page. The engine never reads the page, so the words stay ordinary HTML that anything can read. [index.html, Sections] - **One number leaves the page**: The site works out which section is in the middle of the screen and reports it as a number: 0 is the first section, 2.5 is halfway between the third and the fourth. That number is all the engine gets. [getStage(), Scroll] ## The story Layer 2 of 7 One beat per section names the section and holds a keyframe: what the home and the camera look like at that stop. The scroll position picks two neighbours and blends them, resting on each stop while its section is centred. src/beats.ts beat() sample() - **One beat per section**: A keyframe says how far each room or floor is open, how bright the lamp is, which side of the screen the home sits on, and where the camera stands and looks. A beat pairs a keyframe with the id of its section and a short name. Beats can be written in code, as here, or kept in the home file. [beat(), Camera] - **Blended, with a rest on every stop**: Between two sections the story holds still for the first and last fifth and eases through the middle. The engine then eases the scene towards that target, so a fast scroll never snaps. [sample(), Easing] ## The engine Layer 3 of 7 One call, startScene() , sets up three.js: the renderer, the lights, the frame loop, the camera and the clicks. It builds a home the first time it is asked for and keeps it, so a page can switch between homes. startScene() setHome() three.js - **startScene()**: One call sets up the renderer, the lights and the frame loop, builds the home and plays the story. It draws less often at rest, but never stops while the home floats. Drawing nothing when nothing moves is on the roadmap. Add ?debug to the address to see what build this is and how many frames it has drawn. [three.js, Frame loop] - **Camera and clicks**: The camera follows the keyframes, pulls back on narrow screens and slides the home beside the text on wide ones. A click is traced into the scene: on a room, a floor or a piece that has a story. [Camera, Picking] ## The shells Layer 4 of 7 A shell is the kind of container a home is. There are three: the compact, a box with three rooms; the diorama, one modelled room; and the tower, a stack of floors. Pieces stand in them, each with a key that layouts and stories use. Compact Diorama Tower - **The compact**: A clamshell box with three rooms. The lid lifts to become a back wall and two drawers slide out, or the side rooms turn open like the pages of a pop-up book. It needs no modelling. [Three rooms, Book fold] - **The diorama**: One room modelled in Blender and exported as a single file. It starts flat like an unfolded box, its walls swing up, and three zones fill in on their own beats. [Blender, One .glb] - **The tower**: Stacked floors for a long story or a diagram, which is what you are looking at. Each floor slides out, lights up and fills with pieces; an elevator follows, and pipes show what feeds what. [Floors, Flow pipes] ## The studio Layer 5 of 7 A workbench page on every site, running the same engine from a panel. It is where you frame each stop, move pieces by eye and save where they stand, and where the stills are taken. studio.html mountStudio() - **The same engine, with a panel**: Every site has a studio page. It drives the scene by hand instead of by scrolling: pick a home, scrub the story, open the folds, orbit the camera, switch the light. The address bar holds the view, so a link reopens it. [mountStudio(), studio.html] - **Move a piece, save where it stands**: Pick a piece, then move, turn, resize or hide it. A piece listed in the home file is saved back into that file, and with a home file the studio also adds and removes pieces, writes their stories and sets what each beat does. A piece placed in code, as on this page, is saved to a small layout file by its key. Saving works on the local dev server only. [Layouts, Piece keys] ## The build Layer 6 of 7 One command captures a still of every stop and runs the Vite build. A plugin writes the stories and stills into the HTML, so what ships is a complete page without 3D, with 3D as an upgrade. The output is a static folder. popfold build popfold stills llms.txt - **A still of every stop**: The build opens the studio in a headless browser and captures one picture per stop. The same scene gives the same picture every time, so comparing stills works as a visual test. [popfold stills, --check] - **The page without 3D**: A Vite plugin writes every story under its section, puts a still beside each one and adds structured data, llms.txt, robots.txt and a sitemap. In the browser, 3D starts only if WebGL works and the visitor has not asked for less. [popfoldFallback(), llms.txt] ## The model tools Layer 7 of 7 Pieces can be built in code, as everything on this page is. For the rest there are Blender scripts that convert and tidy models, and a pipeline that makes them from a prompt with local AI models. They are working scripts, not a product yet. tools/blender tools/forge .glb - **From a prompt to a model**: A set of scripts runs local AI models and Blender: a prompt becomes a picture, the picture a cut-out, the cut-out a dense mesh, and Blender turns that into a small textured model with a review sheet. They are working scripts, not a polished tool. [ComfyUI, Blender] - **One convention for every piece**: Every model file follows the same rule: its front faces +Z, its origin is the centre of its base and its longest side is 1. Blender scripts bring downloads, free furniture libraries and whole rooms into that shape. [.glb, gen()] ## What feeds what Overview The stage number, read by every layer One frame: page, story, engine, shells Models become pieces in the shells Layouts and stills go from the studio to the build The build writes the page without 3D back into the page ## Read the long version. Next The guide explains each layer with the real file names. What is still rough is written down too: there is no package to install, the three shells are wired into the engine, and the visual test does not run by itself yet. How Popfold works The roadmap Back to the start Landing page: ../ . Docs: ../docs/ .