# Bookshelf Cascade — `bookshelf-cascade@1.0.0`

Rows of cloth-bound books lean against one another in a slow domino wave along a bookcase. Loops perfectly.

A bookcase with shelves of cloth-bound books of every thickness and height, gold bands on their spines, and a slow wave of leaning running through them like a row of dominoes: one book tips against the next, which tips against the next, a ripple that runs along each shelf (the shelves running in opposite directions) before every book settles upright again. Choose the number of shelves and books, the cloth colours (library, pastel, mono or jewel), how far the books lean, the seed, the backdrop and whether the camera drifts.

- Kind: object; status: published; digest sha256:c18cabe836c65086116c3ffe9e602cf3733660bddc7690380bd375adda7fc8c6
- Role: Object (3D, three.js): a calm, satisfying domino-style object for reading, learning and knowledge content.
- Implementation: three; entry `src/bookshelf-cascade.js`
- Files: https://aipixelwizard.com/registry/bookshelf-cascade/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/bookshelf-cascade.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/bookshelf-cascade/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/bookshelf-cascade/1.0.0/index.html (open over http; it imports sibling packages by relative path)
- Dependencies (exact): `three@0.185.1` (source) — Renderer, geometry and shader materials.; `chrome-material@1.1.0` (demo) — Studio environment light, backdrop and contact shadow.; `apw-runtime@1.0.0` (demo) — Demo harness.

## Exports
- `createBookshelf({ shelves?, books?, palette?, lean?, seed? }) => { group, setProgress(progress), dispose() }` — The case and its books (one instanced mesh) as a group, 12 wide, standing on y = 0; add it with an environment map and a shadow-casting light.
- `PALETTES: { library, pastel, mono, jewel }` — Book cloth colours.

## Parameters
- `shelves` (integer 2–4, default 3) — Shelves
- `books` (integer 8–24, default 16) — Books per shelf
- `palette` (select one of library | pastel | mono | jewel, default "library") — Cloth
- `lean` (number 0.4–1.6, default 1) — Lean
- `seed` (integer 1–999, default 4) — Seed
- `background` (color, default "#2a1f18") — Backdrop
- `orbit` (boolean, default true) — Camera drift

## Composition
- Inputs: Time within the loop; the shelves, books, cloth colours, lean, seed, backdrop and camera drift.
- Outputs: A full frame rendered in 3D with soft shadows and a studio environment.
- Coordinates: The case is 12 wide, each shelf 3.4 tall, standing on y = 0 with its back at z = -0.8; books tilt in the xy plane about their bottom corners.
- Lighting: A warm key light with a shadow map and the studio environment.
- Timing: setProgress(progress) sets every book; frames render in any order.
- Works with: chrome-material, orbit-camera, kinetic-title, number-reveal
- Each book is a scaled box in one instanced mesh, coloured per instance and given gold bands by a shared spine map; its lean is a smoothstep window (up to 0.5 rad times the lean setting) that passes along its shelf in the shelf's direction.

## Output and loop
- 1080×1080, 30 fps, 16 s, procedural
- Seamless loop: yes — A smooth window of lean passes along each shelf once per loop; every book's tilt is a function of its position and the loop's phase only, so the last frame meets the first.
- Verified 2026-10-06 in Chrome 154.0.8037.97 headless on Linux 7.0.0-38-generic (x64), Node 22.14.0 (WebGL 2 via SwiftShader (software)); deterministic: yes; loop check: Frame 0 vs end state (progress 1): mean |Δ| 0.0000, max |Δ| 0 of 255.

## Use it
New project: Create a WebGLRenderer with shadows and a studio environment (see chrome-material), add createBookshelf().group and call shelves.setProgress(progress) each frame.

Existing project: Copy src/bookshelf-cascade.js; add shelves.group to your scene with an environment map and a shadow-casting light.

Reuse ideas:
- Library or reading-app title: Library, three shelves.
- Cheerful education loop: Pastel, cheerful.
- Chain-reaction metaphor: Black and white.

## Limitations
- The books lean in a prescribed wave without collision: a leaning book may pass through its neighbour a little.
- Books are plain boxes with a shared spine pattern, with no readable titles.

## License
MIT. Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License. See LICENSE in this folder.

Provenance: Adapted from the owner's threejs-sketches/objects-scenes/bookshelf-cascade (MIT) and rebuilt for AI Pixel Wizard in October 2026 as an original object: seeded books on an instanced shelf, a closed-form domino lean wave in opposite directions per shelf and an exact loop.