quirq_ai

---

What this repository is

• A single procedural glass ribbon stays mounted behind the page.
• Each content section registers itself as a beat.
• Scroll position becomes a fractional beat such as 1.42.
• A choreography track blends all 14 pose, optics, and lighting channels.
• The same renderer can turn React components, plain objects, or a branching JSON tree into a staged page.

The visual argument is carried by the glass itself: cost drains toward monochrome; verified delivery restores the full spectrum.

Contents

• Experience tour
• Technology
• Quick start
• Architecture
• Repository map
• Three ways to author a page
• Turn JSON into a page
• Journey JSON reference
• Story beat reference
• Scene and glass customization
• Brand, content, and UI customization
• Runtime, performance, and accessibility
• Validation and golden testing
• Production notes

Experience tour

Route	Purpose	Primary source
/	The main five-beat story: hero, ecosystem, tokens, quirqs, ledger, invite	app/page.tsx, components/beats
/what-is-quirq	A focused explainer using the shared stage	app/what-is-quirq
/how-it-works	The journey JSON authoring manual, rendered by the system it explains	app/how-it-works/story.ts
/beats	Fractional traversal and the beats-array contract	app/beats
/scenes	The 14 scene channels, camera-by-relativity, and pose presets	app/scenes/story.ts
/dynamic	A complete example of a page whose middle is plain data	app/dynamic/story.ts
/editor	A live authoring surface for copy, layout, poses, optics, ordering, and JSON export	app/editor/editor.tsx
/journey	A branching page generated from .quirq/journeys/*.json	app/journey
/golden	The zero-delta visual choreography harness	app/golden, lib/golden.ts
/registry	How beat sections announce themselves at runtime	app/registry, lib/beat-registry.ts
/tree	Cascaded, branchable choreography authoring	app/tree, components/stage/choreo-tree.ts
/research	Research index generated from typed content	lib/research.ts
/research/[slug]	Statically generated research articles	app/research/[slug]/page.tsx
/quirq-whitepaper.pdf	Static PDF whitepaper	public/quirq-whitepaper.pdf
/llm.txt	The whitepaper as one machine-readable text file	public/llm.txt

Technology

• Next.js 16.2.11 with App Router and Turbopack
• React 19.2.4
• Tailwind CSS 4
• react-three-fiber 9, drei 10, and three 0.185
• Motion 12 for content entrance choreography
• Lenis 1.3 for smooth scroll
• TypeScript with the @/* root alias

The Three.js scene is client-only and lazily imported. The page shell, copy, and layout can paint before the roughly 1 MB 3D dependency graph arrives.

Quick start

Requirements

• Node.js 20.9 or newer
• pnpm
• A browser with WebGL for the live stage; a still-image fallback is included

Install and run

pnpm install
pnpm dev

Open http://localhost:3000.

Production build

pnpm build
pnpm start

No application environment variables are required. The build does need network access the first time next/font fetches Inter, Poppins, and JetBrains Mono.

Architecture

From scroll to glass

flowchart LR
    A["Story content"] --> B["StoryBeat or custom beat component"]
    B --> C["Beat section registers id, index, and element"]
    C --> D["ScrollRuntime measures section centres"]
    D --> E["stage.beat becomes a fractional index"]
    E --> F["sampleKeyframes blends adjacent poses"]
    F --> G["GlassForm damps 14 live channels"]
    G --> H["One persistent ribbon is re-staged"]

    D --> I["stage.progress"]
    I --> J["CSS --scroll"]
    J --> K["Spectrum progress rule"]

The hot path deliberately avoids React state. ScrollRuntime writes fast-changing values into the module-level stage store; useFrame reads them inside the separate react-three-fiber reconciler root.

From a .quirq JSON file to a page

flowchart TD
    A[".quirq/journeys/my-story.json"] --> B["GET /api/journeys/my-story"]
    B --> C["validateDefinition"]
    C -->|valid| D["resolveDefinition"]
    C -->|invalid| X["Refuse the file with a readable error"]
    D --> E["Named pose + tweaks becomes a full keyframe"]
    D --> F["Beat object stays plain render data"]
    E --> G["Visited node path becomes overrideLeaves track"]
    F --> H["StoryBeat renders each visited node"]
    G --> I["Glass follows the chosen branch"]
    H --> I
    I --> J["/journey?j=my-story"]

The three layers

Layer	Owns	Important files
Content	Headlines, rows, tiles, calls to action, choices, research	components/beats/*, app/*/story.ts, .quirq/journeys/*.json, lib/research.ts
Choreography	Beat registration, scroll mapping, pose resolution, interpolation	lib/beat-registry.ts, components/scroll-runtime.tsx, components/stage/choreo-tree.ts, components/stage/choreography.ts
Rendering	DOM story components, glass mesh, material, lights, overlays	components/story/*, components/ui/*, components/stage/*, app/globals.css

Repository map

.
├── .quirq/
│   └── journeys/                 JSON-authored branching pages
├── app/
│   ├── api/journeys/             list, read, dev-only write, and recording APIs
│   ├── editor/                   live page and scene editor
│   ├── journey/                  JSON model, resolver, and branching runtime
│   ├── research/                 research index and generated article routes
│   ├── dynamic/                  canonical data-driven page example
│   ├── scenes/                   scene customization guide
│   ├── golden/ registry/ tree/   architecture feature pages
│   ├── layout.tsx                fonts, metadata, motion provider, no-JS fallback
│   ├── page.tsx                  composed home page
│   └── globals.css               design tokens and global visual language
├── components/
│   ├── beats/                    hand-composed home sections
│   ├── story/                    BeatData type and generic StoryBeat renderer
│   ├── stage/                    canvas, mesh, shader, track, and choreography
│   ├── ui/                       primitives, navigation, footer, agent handoff
│   ├── scroll-runtime.tsx        DOM measurement → fractional beat mapping
│   └── stage-page.tsx            shared stage shell
├── lib/
│   ├── beat-registry.ts          runtime beat registration
│   ├── stage-store.ts            allocation-free frame state
│   ├── golden.ts                 dev capture harness
│   ├── lighting.ts               coupled brightness presets
│   ├── research.ts               typed research content
│   └── spectrum.ts               the seven brand colors
├── public/
│   ├── assets/                   favicon, social art, fallback, README banner
│   ├── llm.txt                   machine-readable whitepaper
│   └── quirq-whitepaper.pdf
├── docs/
│   ├── animation.md              deeper animation-system walkthrough
│   └── goldens/                  captured choreography baselines
├── next.config.ts
└── package.json

Three ways to author a page

Choose the lowest level that gives you the control you need.

1. Compose custom React beats

Use this when a section needs bespoke markup or interaction. The home page follows this pattern:

import { StagePage } from "@/components/stage-page";
import { Hero } from "@/components/beats/hero";
import { Delivery } from "@/components/beats/delivery";

export default function Page() {
  return (
    <StagePage>
      <Hero />
      <Delivery />
    </StagePage>
  );
}

Every staged section must render the shared Beat primitive or call registerBeat directly. A raw section that never registers is invisible to the choreography.

2. Render plain BeatData

Use this for linear pages whose layout fits the generic renderer:

import { StagePage } from "@/components/stage-page";
import { StoryBeat } from "@/components/story/story-beat";
import type { BeatData } from "@/components/story/types";

const STORY: BeatData[] = [
  {
    index: 0,
    id: "intro",
    layout: "center",
    title: ["Your first line,", "made of light."],
    glass: 1,
    lede: "A page can be an array of plain objects.",
  },
  {
    index: 1,
    id: "proof",
    layout: "left",
    marker: "01 · the proof",
    title: ["State in,", "state out."],
    rows: [
      { title: "Capture before.", note: "Record the world before work starts." },
      { title: "Verify after.", note: "Score the actual changed state." },
    ],
  },
];

export default function Page() {
  return (
    <StagePage>
      {STORY.map((beat) => (
        <StoryBeat key={beat.id} data={beat} />
      ))}
    </StagePage>
  );
}

Pages that use the repository’s default choreography should have no more than its five resolved leaves. Fewer beats are fine. The editor and journey runtime can exceed five because they provide their own track through overrideLeaves.

3. Generate a branching page from JSON

Use a .quirq journey when content should branch based on visitor choices, or when the page should be transferable as one data object without adding a route component.

The rest of this README focuses on this path.

Turn JSON into a page

Fastest path: use the live editor

1. Run pnpm dev.
2. Open http://localhost:3000/editor on a desktop-sized viewport.
3. Add, remove, or reorder beats.
4. Edit marker, title, lede, alignment, and glass title line.
5. Pick a pose preset or tune any of the 14 channels.
6. Set a kebab-case slug such as product-tour.
7. Choose Copy journey JSON to copy the complete document.
8. Choose Create page in development to write .quirq/journeys/product-tour.json.
9. Open /journey?j=product-tour.

The editor exports a valid linear journey: one node per beat and one forward choice per node. Open the generated JSON afterward to add forks, richer content blocks, or different prompts.

Create page is intentionally development-only. In production, the .quirq folder is read-only.

Hand-authored path

Create .quirq/journeys/launch-story.json:

{
  "slug": "launch-story",
  "name": "Launch story",
  "rules": {
    "start": "intro",
    "maxDepth": 2,
    "allowRewind": true,
    "allowReplay": true
  },
  "nodes": {
    "intro": {
      "short": "start",
      "pose": {
        "base": "centre"
      },
      "beat": {
        "layout": "center",
        "title": ["A page from", "one JSON file."],
        "glass": 1,
        "lede": "The copy, the branch, and the glass pose all travel together."
      },
      "prompt": "Where should we go next?",
      "choices": [
        {
          "label": "Show me the proof",
          "to": "proof"
        }
      ]
    },
    "proof": {
      "short": "the proof",
      "pose": {
        "base": "flooded",
        "tweaks": {
          "spin": 0.2,
          "burst": 0.78
        }
      },
      "beat": {
        "layout": "right",
        "marker": "01 · verified",
        "title": ["State changed,", "value proved."],
        "glass": 1,
        "rows": [
          {
            "title": "The page renders from data.",