Inside 3drossa

The thing it replaces

Building a scroll-driven 3D page today means hand-authoring numbers: a table of waypoints, a lerp() per camera framing, and a browser refresh between every guess. The numbers are invisible — you cannot see a waypoint, you can only see where the object ended up — so tuning is a loop of edit, reload, squint.

3drossa is that work extracted. The whole experience — the path, the camera, the moments the page stops — is one plain-data document, and a visual editor runs inside your own page and writes it back to disk. You drag the path over your real headline, at its real size, at the depth it really sits.

The words, first

Everything below assumes these. They are not jargon for its own sake — each one names a decision that could have gone another way.

p

Page progress, 0 at the top and 1 at the bottom. Every table in the document is bound to it.

sx

Sideways position as a fraction of the visible half-width at that depth. Not a world coordinate. 0 is centre, 1 is the edge of frame.

t

A station's own clock, 0 on arrival and 1 on leaving. Independent of p.

station

A section that pins the viewport for a written run of scroll while copy arrives on beats.

travel

Everything between stations. The pin releases and the subject moves along the spline.

handoff

A path row that derives its position from a station rather than stating one.

beat

A moment inside a station when a line of copy arrives or leaves, in that station's clock.

shot

Where the page camera is, what it aims at and its field of view, for one value of p.

svh

Small viewport height. Station lengths are written in these, not pixels.

Waypoints live in screen space

The visible width of a perspective scene shrinks as you approach the lens. So a world-x that comfortably clears your text column at one depth is off-screen at another — and “stay out of the copy” is the entire job of a waypoint.

With the demo's lens (z 5.9, fov 38°, aspect 1.6), the visible half-width is 3.80 world units at z = -1 and only 2.42 at z = +1.5. The same sx = 0.62 therefore means two different world positions — which is exactly right, because it means the same thing on screen.

This is also the one thing a generic spline editor cannot do. Three.js's own editor, zz85's, the Cientos one — they all edit raw XYZ, which throws away the property that makes the table work. So the editor drags in world space and stores screen space, converting on every pointer move.

// src/editor/JourneyEditor.js — world in, screen space out
const screenPatch = (position) => ({
  sx: Number(journey.toScreenX(position.x, position.z).toFixed(3)),
  y:  Number(position.y.toFixed(3)),
  z:  Number(position.z.toFixed(3)),
});

Depth is typed, never dragged. A 2D gesture has no third axis to give, and z is the one that decides whether the subject passes in front of the copy or behind it — too important to guess at.

Waypoints are bound to measured progress

Each row declares the page progress it belongs to. The subject is at that waypoint when the reader is at that point in the page — guaranteed, not approximately.

The obvious alternative is to space waypoints evenly along the spline and hope they line up with the sections. They don't. Sections are wildly different heights, so an evenly spaced spline drifts off the content it was written for, and a beat written for one section plays over another.

// src/core/journey.js — shared by the subject's path and the camera's
function tableToU(table, p) {
  const last = table.length - 1;
  if (p <= table[0].p) return 0;
  if (p >= table[last].p) return 1;

  let i = 0;
  while (i < last - 1 && p > table[i + 1].p) i++;

  const a = table[i], b = table[i + 1];
  return (i + (p - a.p) / (b.p - a.p)) / last;
}

The subject moves faster between distant waypoints, which is correct: it is covering more ground in the same amount of scroll.

Stations and travel, and derived handoffs

A station pins the viewport for a written run of scroll: the page stops, the camera takes up a framing, and copy arrives on beats inside the held frame. Between stations the pin releases and the subject travels. That alternation is what makes a page read as a place rather than a stack of sections.

At a station boundary the spline's only job is to hand off. The obvious implementation states the position twice — once in the station, once in the path — and the two drift apart every single time a station is retuned. The drift reads as the subject teleporting, and it is miserable to diagnose because both numbers look plausible.

// A path row either states a position, or asks a station for one.
{ "p": 0.121,  "station": "launch", "at": 0 }   // derived — cannot drift
{ "p": 0.450,  "sx": -0.72, "y": -0.15, "z": -1.8 }  // authored

The editor shows derived rows in teal, read-only, with their resolved values visible. You can see the spline and the station agreeing at the boundary, which is exactly the thing that used to silently stop being true.

Five layers, one rule

These are layers, not steps — each depends only on the ones above it. The rule that shapes everything: core is pure.

Why core is pure

Not a layering nicety. It is what makes an experience checkable: a whole journey can be swept in node and asserted against, with no browser, no GPU and no screenshots.

import { Journey, makeSample } from "3drossa";

const journey = new Journey(doc);
const out = makeSample();

for (let p = 0; p <= 1; p += 0.001) {
  journey.sample(p, out);   // subject, camera, beats, station, stationT
}

Every motion bug this engine was extracted from was originally found by instrumenting a running page, because there was no other way to look at it. Now a continuity violation — the path jumping, a station handoff not meeting exactly — fails in CI in 150ms.

Damping and blending are deliberately not in core. sample() reports where the path is and where the station wants the subject; easing between them across time is runtime state, and belongs to the renderer. Keeping it out is what keeps sample() a pure function of p.

Everything is keyframes

The finding that made this an engine rather than a spline library: every station framing in the original hand-built site was already two endpoints and an easing, wearing a function costume.

// what it was
out.position.set(lerp(1.1, -0.3, ease), lerp(-0.35, 0.9, ease), lerp(2.9, 6.6, ease));

// what it is
"camera": [
  { "t": 0, "position": [ 1.1, -0.35, 2.9], "target": [0.9, -0.5,  0], "fov": 34, "ease": "smoothstep" },
  { "t": 1, "position": [-0.3,  0.9,  6.6], "target": [0.1,  0.35, 0], "fov": 40 }
]

No logic a keyframe pair could not hold. So travel waypoints and station framings collapse into one format, and one tool edits both — where previously stations could only be changed by hand-writing lerp() calls, which is the worse of the two authoring problems.

Channels are discovered, not declared

A keyframe may carry channels the engine has never heard of — a fog density, a light colour — and they interpolate and round-trip untouched. ease sets a segment's easing; <channel>Ease overrides one channel.

// src/core/track.js
const RESERVED = new Set(["t", "at", "ease", "id", "p", "station"]);

export function channelsOf(key) {
  return Object.keys(key).filter(
    (k) => !RESERVED.has(k) && !k.endsWith("Ease") && (isNum(key[k]) || isVec(key[k]))
  );
}

Per-channel easing is not gold-plating. The original site eased position on smoothstep but scale on raw t; without it the conversion would not have been lossless, and lossless was the whole proof.

Serialization is byte-stable

Stable key order, fixed precision. parse → serialize → parse is identical, so a save that changes nothing produces no diff. A tool that dirties a file just by opening it is a tool people stop using.

This reaches further than it looks. The starter document the scaffold writes goes through the same serializer, so a new project's very first Save also produces no diff — and the packaging check asserts exactly that, because hand-stringifying the starter was the obvious shortcut and it silently broke the guarantee.

Scroll never touches React state

One mutable object is the bridge. GSAP, Lenis or the built-in loop writes to it; useFrame reads it. The scroll pipeline costs zero reconciliations, which is why sixty-times-a-second editing is free.

All negative, on purpose. In React Three Fiber a positive priority takes over the render loop and makes you call gl.render() yourself; negative priorities only order the callbacks, so automatic rendering still happens after all of them. The blue steps are the editor's, and they are negative for a second reason — see the preview, below.

The measured pin beats the document

A station has two positions. The pin is measured from the live DOM — offsetTop, offsetHeight — and is authoritative at runtime. The handoffs are the two path rows that say where the spline meets it, and those are authored.

The document still owns the space around a station — lead and trail, in viewport heights, applied as margin. Because offsetTop already accounts for margin, moving a station needs no arithmetic anywhere else: the pin, the editor readout and every handoff follow for free. And the gap between two stations is the travel section, so its length is a choreography decision, not a layout one.

The rule that bites

stage keeps its identity across a rebuild. That is deliberate — it is what makes editing free — but it means anything reading the document during render has no way to notice a change. Two components were quietly broken by exactly this before it was named and given one hook.

// src/react/useDocument.js
export default function useDocument(stage) {
  const subscribe = useCallback(
    (listener) => (stage?.subscribe ? stage.subscribe(listener) : () => {}), [stage]
  );
  const snapshot = useCallback(() => (stage?.getVersion ? stage.getVersion() : 0), [stage]);

  useSyncExternalStore(subscribe, snapshot, snapshot);
  return stage?.journey.doc ?? null;
}

Getting a canvas on top of a page

The overlay has to sit above the host's content without hiding it — and that turned out to be the single most expensive problem in the project, because two of its failure modes look identical to bugs elsewhere.

First: canvas.parentElement is R3F's own wrapper, not your positioning container. Raising it achieves nothing, because it still sits inside the host's container — which is typically fixed inset-0 -z-10, deliberately behind the page. So the whole ancestor chain is lifted to <body>, and any static ancestor gets position: relative first, since z-index does nothing without one.

Second: the page content is then lifted above the canvas with pointer-events: none, so it stays legible while clicks fall through to the handles. And its backgrounds are knocked out for the duration — because lifting opaque sections over the 3D just gives you a normal-looking website with an editor panel beside it and no path visible anywhere, which is worse than either choice alone.

Dragging without a gizmo

drei's TransformControls was tried first and never received a single pointer event, while R3F's own click events on the same meshes worked fine. Selection worked; dragging silently did not — which reads as “it moves when I click but I cannot hold it”.

Rather than keep guessing why a third-party control was deaf, dragging became a plane raycast on the event path that was already demonstrably working: a plane through the point, facing the camera, with pointermove on the window — because a fast drag routinely leaves the canvas, and a listener that stops at its edge drops the gesture halfway.

A working journey, built in the same render

stage.rebuild() runs in an effect, which is a frame too late. Add a station and the working document immediately contains a row handing off to it while stage.journey has never heard of it — resolving that row throws, and the editor unmounts mid-edit.

const lastGood = useRef(null);
const working = useMemo(() => {
  try { lastGood.current = new Journey(doc); } catch {}
  return lastGood.current ?? stage.journey;   // you may type "2" on the way to "0.25"
}, [doc, stage]);

Flying, not orbiting

The editor used OrbitControls, and OrbitControls was the wrong tool in a specific way. It is a viewer control: it circles a pivot, and the pivot only moves when you pan. Authoring a flight path means getting inside the volume the path moves through — under it, alongside it, level with the lens at the moment of a station — and with an orbit-only control the only way there is pan, re-orbit, pan again. You spend the session steering the camera rather than the path.

So the state is not “a pivot and an angle”. It is a position, a heading and a distance to the pivot, which makes all four gestures the same two numbers seen differently.

Three decisions that are not arbitrary

Yaw and pitch are stored, not derived. Reading them back out of the camera's basis every frame re-rounds them, and the error accumulates into a slow roll — the kind of bug you notice an hour in, when everything you have placed is slightly askew. Pitch is clamped just shy of the pole so the heading can never flip over the top.

Q and E are world up and down, not the camera's. Camera-relative up is what a flight sim does and it is wrong here: while you are pitched down to look at the path, “up” would carry you backwards as well, so the one gesture you reach for to get above the scene also loses your framing.

Speed scales with how far back you are. The same keystroke should cross the same fraction of what you can see, whether you are inches from a waypoint or looking at the whole page. The same reasoning sets the pan rate from the visible height at the pivot's depth: a fixed units-per-pixel rate is imperceptible at one end of the range and a catapult at the other.

A left press is only a candidate

The handles are the point of the editor and they are picked with the left button, so navigation has to lose that press whenever something in the scene wants it. The mechanism is useDragPlane setting controls.enabled = false — and it cannot be relied on to have run yet.

Two listeners on one element run in registration order, and R3F's goes on at <Canvas> mount while the controls' goes on when the editor opens — so the controls hear the press before the hit-test that would have silenced them. Starting the orbit there let exactly one pointermove through: the waypoint moved correctly and the whole view rotated about two degrees underneath it.

None of this needs a browser to check, which is the point of writing the control rather than importing one. Thirteen node tests cover the gestures: that an orbit holds its radius and its pivot, that a look holds the eye, that the horizon never rolls after forty frames of vertical drag, that Q does not drift sideways from a pitched-down camera, and that a press claimed by a handle never turns the view at all.

Seeing the camera you are editing

This was the worst problem the editor had, and it is not a bug in any single piece of code. The moment you take the camera to inspect the path, the thing you are authoring — the shot — becomes invisible, because the shot is defined by a lens you are no longer looking through.

So you fly out to see the path, cannot judge the framing, fly back to judge the framing, cannot see the path. Every adjustment cost two trips, and the trips are where the session goes.

One solver, two readers

Both pieces need to know where the page camera is, and the first version of both worked it out themselves. That is the mistake this codebase keeps naming: the gizmo drifted from the real camera the moment anything about the director changed, and it was wrong in exactly the cases that matter — at a station, and in the camera-path mode the gizmo exists to help author.

So the branch table moved out of <Stage> into one function. <Stage> damps the answer onto the real camera; the editor reads the same answer undamped, because a gizmo should show where the shot is composed, not where a lerp has got to.

// src/react/director.js — pure in everything but `out`
export function solveCamera(stage, sample, held, out, overrides = {}) {
  // locked · orbit · path · follow · beats, then the station blend
  out.position.lerpVectors(followPos, sample.camera.position, k);
  out.target.lerpVectors(followTarget, sample.camera.target, k);
  out.fov = MathUtils.lerp(baseFov, sample.camera.fov, sample.station ? k : 0);
  return out;
}

Rendering the inset without taking the loop

The obvious implementation of a picture-in-picture takes over the render loop: a positive useFrame priority, two gl.render calls, a scissored viewport for the corner. It works, and it makes the editor responsible for the host's main pass as well — so any host with postprocessing silently loses its effects the moment the editor opens.

Drawing into a texture touches nothing. At a negative priority the automatic pass still happens afterwards, exactly as it did before.

const previous = gl.getRenderTarget();
gl.setRenderTarget(target);
gl.render(scene, pageCamera);     // the host's scene, its lights, its fog
gl.setRenderTarget(previous);     // and the normal pass follows

The quad showing that texture is then written in front of the editor's camera each frame rather than parented to it — the host owns the camera object and may not even have it in the scene graph, so a child of it is sometimes rendered and sometimes not.

Splitting the editor out of the picture

Rendered naively that view is useless: it contains the handles, the spline, the keep-out volumes and the camera gizmo — a picture of the editor rather than a picture of the page. Culling by layer is the only way to separate them without a second scene, and a second scene is worse, because the host's lights, fog and background all live in its one.

// src/editor/layers.js
export const EDITOR_LAYER = 19;   // not 1 — hosts use low layers

// assigned, not enabled: an editor object has no business being
// visible to the page camera at all
if (object.layers.mask !== EDITOR_MASK) object.layers.mask = EDITOR_MASK;

Claimed every frame, because the editor's subtree changes constantly — a waypoint added, a station's keyframes appearing when it is selected — and there is no single mount hook that covers all of it. It costs one integer compare per object on the frames where nothing changed, which is all of them.

That layer also made every handle unpickable, for a reason worth its own case file below.

Making a path legible

The first version of the scene view was accurate and unusable, in four ways that are each obvious once named and none of which are about correctness.

Two details that took a second attempt

Arrowheads are spaced by arc length, not by parameter. getPoints is evenly spaced in the curve's parameter, which on a centripetal Catmull-Rom is emphatically not evenly spaced in distance. Arrows bunched up wherever waypoints were close together and vanished across the long travel sections — exactly backwards, because the long sections are the ones where you cannot otherwise tell which way the subject is going.

Labels are sprites, not <Html>. The editor goes to considerable trouble to lift the canvas's whole ancestor chain above the host's page and then lift the host's copy back above that; an HTML label lands in R3F's own wrapper somewhere inside that stack, so it is either buried under the copy it annotates or painted over the panel. A sprite is in the scene, which is where a label on a point in the scene belongs.

X-ray is on by default — handles draw through geometry — because a waypoint tucked behind the subject's own model is a waypoint you cannot select, and “the handle is missing” is indistinguishable from “this row has no handle” until you have flown around to check.

Writing source files from a browser

Two handlers, deliberately separate: one takes JSON and validates it with the engine's own parser, the other takes opaque bytes it cannot inspect. Those deserve different rules, and folding them together is how the strict one ends up with the loose one's checks.

Nothing from a request is ever spliced into a file. The document is parsed, validated, and re-serialized from the validated result, so the worst a malformed request can do is fail. A route that takes strings from a client and writes them into a source file is a remote code execution hole, whoever it was meant for.

For dropped models the rules are: an allowlist of extensions, the filename reduced to a safe basename, the joined path re-checked against the asset directory, an 80 MB cap, and a flat refusal in production.

The rules live in one place, not three

All of that used to live inside the Next route handler, which made “can I use 3drossa?” mean “are you on Next?” for anyone who wanted the editor to write to disk — and writing to disk is the entire product. It is now plain functions taking and returning plain data, with thin adapters on top.

// vite.config.js
import { rossaVite } from "3drossa/server";
export default { plugins: [react(), rossaVite({ file: "src/journey.json" })] };

// or anything that speaks connect middleware
app.use(rossaMiddleware({ file: "src/journey.json" }));

// or Next's App Router — about forty lines of adapter over the same functions
export const POST = createSaveRoute({ file: "app/journey.json" }).POST;

And when there is nowhere to write

The page most likely to have someone trying a model on it is a static one — a Pages deploy, a preview build, the playground this project ships. The editor used to refuse the drop there with “no save route”, which is honest, and also means the most interesting thing the tool does was unavailable in the only place most people will ever meet it.

An object URL is the obvious fallback and was rejected for a good reason: it dies with the tab, so the document you saved refers to a model that no longer exists. The reason holds; it is an argument against object URLs, not against local models. The bytes go into IndexedDB and the document records a rossa-local: URL.

There is a file picker beside the drop zone too, because drag-and-drop is the nicer gesture and not a reliable one: it does not exist on a touch device, it is awkward from inside an archive manager, and when a drop silently fails there is nothing to try again.

Putting it on your own site

There is a gap between npm install 3drossa and a page you can actually edit, and it is not a conceptual gap. The library is four imports and a JSON document, and every one of them has to be in a particular place relative to your framework.

None of that is hard; all of it is fiddly; and getting any one of them wrong produces a symptom that does not name the cause — a 404 on save, a model that vanishes on reload, a development tool in a production bundle. So the answer should be a command, not a checklist.

npm install 3drossa three @react-three/fiber @react-three/drei
npx 3drossa init

+ app/journey.json              the experience. commit it.
+ app/api/rossa/route.js        lets the editor write that file back
+ app/api/rossa/model/route.js  lets a dropped model land in your repo
+ app/page.jsx                  a starter page, editor already gated
+ public/models/                where a dropped .glb goes

It reads the directory rather than package.json to decide what you are on — a monorepo root lists every framework anyone uses, and the question is not “is Next installed somewhere” but “where do routes go in this directory”. It never overwrites: existing files are reported and left alone, so running it again when you add a second page is safe.

What actually ships

The editor is a development tool and should not reach your visitors. Three things, all of which the scaffold sets up:

1. The editor is dynamically imported and gated on NODE_ENV, which keeps it out of the bundle rather than merely out of the render.
2. The save routes refuse in production by construction. The demo goes further and names them route.dev.js, listing .dev.js in pageExtensions only in development — so they are not routes at all in a production build, which is harder to get wrong than a script that moves source around.
3. journey.json and public/models/ are committed. They are the experience. Everything the page does at runtime is in those two places, and that is what makes it reproducible: clone the repository and you have the whole thing.

The packaging check runs all of this from outside: it packs the tarball, installs it into a throwaway project, imports every entry point, runs the CLI, and asserts the starter it wrote is a document the engine accepts and round-trips byte-for-byte. A tarball where bin/ was left out of files is a tarball whose README is wrong on line one.

The bugs worth studying

Grouped by what kind of mistake they were, because the class is the transferable part. Each of these took real time, and most of them produced a symptom that pointed somewhere else entirely.

// the handlers go through a ref; the construction does not depend on them
const shortcuts = useRef({ onFrameSelection, onFrameAll });
shortcuts.current = { onFrameSelection, onFrameAll };

useEffect(() => { …build the controls… }, [camera, gl, set, get]);

event.preventDefault();
setOver(false);
if (event.defaultPrevented) return;   // always true. the rest is dead.

What is checked, and where

The suite is split along the purity line, and the split is the whole strategy: anything that is a property of the data is asserted in node, and only what is a property of the interaction needs a browser.

The browser half presses real buttons

Nothing in it reaches into React state. Every step is a click or a keystroke a developer would make — which is the only way ordering bugs appear at all: a document referencing a station the live journey has not heard of, a rename leaving path rows pointing at the old id.

W (forward)                      ok
Q is world up                    ok
Q does not drift                 ok
W typed in a field is text       ok
left drag orbits (radius held)   ok
right drag looks (eye held)      ok
wheel does not scroll the page   ok
the horizon never rolled         ok
the controls survive an edit     ok
pressing a handle selects it     ok
dragging a handle moves it       ok
dragging a handle does not orbit ok
the page camera has a frustum    ok
editor gizmos are off the page layer  ok
a dropped model reaches the document  ok
fixture                          untouched
all checks passed

That fixture line is not decoration. The editor can write source files, so the harness diffs the demo's journey.json before and after every run — after a selector once hit Save and rewrote the fixture, leaving the next run starting from a document nobody had authored.

Assertions are made on the scene, not the document, wherever both are possible. Writing subject.rotation and reading it back would pass just as happily if useSubject ignored the field — and ignoring it is precisely the bug worth catching. Where the production build hides the development handles, the harness measures something the page cannot fake instead: a wrapped fetch, the DOM, the stored draft.

Adding something new

The shape of almost every feature here is the same, and following it is the fastest way to add another:

1. Put it in the document with a default that changes nothing, in src/core/document.js. Validate it there too — a document the engine would reject must never reach the disk.
2. Sample it in core, as a pure function of p. Write into the reused sample object; allocate nothing.
3. Consume it in the renderer, where damping and blending live. Props are overrides; the document is the source.
4. Expose it in the panel, in the section it belongs to, with a one-line explanation of what it does in the reader's terms.
5. Assert it — in node if it is a property of the data, in the browser if it is a property of the interaction.

Known gaps

• Lights, ground and environment are still the host's JSX, not document data — so a dropped model is lit by whatever the page happened to set up. This is the largest remaining gap.
• Route variants (one path shaped differently per user choice) are a code hook, not data.
• Station camera framings are editable as numbers but have no drag handles; the subject keyframes and the camera path do.
• While a station is held, heading still follows the travel spline rather than the station's own motion.
• The preview inset renders the scene a second time each frame. It is small, and it is a development tool, but it is not free.
• Mobile is untested, and the navigation assumes a keyboard and three mouse buttons.
• A locally stored model lives in one browser, so a teammate who clones the repository sees the fallback subject until it is saved properly.

The through-line

Read back, nearly every decision here is the same decision. When two things must agree, do not maintain both — make one ask the other. Path handoffs ask stations. The editor's scrub bar asks the page. The camera gizmo and the real lens ask one solver. useSubject asks the sample. The measured pin beats the written one.

And nearly every bug was the same bug: a second copy of something, quietly drifting. A duplicated position. A state that outlived its schema. An estimator converging from a wrong start. A chunk served from a cache after the file behind it had changed.

The newer ones add a second family, which is worth naming on its own: a check that cannot see what it is checking. A raycaster filtered onto the wrong layer. A guard reading a flag it had just set. A harness counting resource entries that a blob URL never produces. Each one was quiet, and each one was reassuring while it was wrong.

The engine is small. What took the time was finding out, one failure at a time, which things were allowed to be true in two places — and the answer was none of them.

Abdullah Bilal

Software Engineer & Founder

web

abdullahbilal.nxera.io

email

aabdullahbillall@gmail.com

phone

+92 317 5081727

github

github.com/abdullahbilal-y

demo

abdullahbilal-y.github.io/3drossa