Function debugDrawStreams

Packs buffer's live segments into the position + colour streams a per-segment-coloured GL.LINES draw wants — the function that finally makes §84/§113's debug overlay drawable in one call (R-35).

Why this returns arrays and not a BufferGeometry (decision, R-35)

The §3.1 dependency matrix gives @fourjs/diagnostics exactly three edges — core, math, scene — and geometry is not among them; the matrix is frozen, so this package cannot import BufferGeometry and must not pretend to. What it can do is emit the two arrays in the exact shape BufferGeometry accepts verbatim, which is the same duck-typed-contract move ParticleDrawable and ReplayTarget make. The assembly is two lines in the application, which owns both packages:

// once
const streams = debugDrawStreams(buffer);
const geometry = new BufferGeometry({ ...streams, mode: "lines" });
const node = new Renderable(geometry, new UnlitMaterial({ vertexColors: true }));

// per frame
buffer.clear();
collectContactPoints(world.queuedEvents, buffer);
debugDrawStreams(buffer, streams);        // pack (no alloc at a stable count)
applyDebugDrawStreams(streams, geometry); // re-point or markDirty
Copy

The { ...streams, mode: "lines" } spread works because DebugDrawStreams's first two fields are named exactly as BufferGeometryOptions' positions and colors; the extra count fields are ignored by the constructor. That naming is deliberate and load-bearing.

Reuse (§7b out-parameter discipline)

Pass the record back as out and the arrays are rewritten in place whenever the segment count is unchanged — the steady state of an overlay whose provider set is fixed, where this allocates nothing at all. When the count moves, the two arrays are replaced (they must be: BufferGeometry rejects a slack tail) and DebugDrawStreams.resized says so.

Growing-and-never-shrinking, DebugDrawBuffer's own policy, is deliberately not copied here: an oversized array is exactly what the geometry refuses, and re-pointing a geometry costs a full §85 validation scan of both streams anyway, which dwarfs the allocation it would save.

An empty buffer yields two zero-length arrays — a legal, empty "lines" geometry that draws nothing, so an overlay with nothing to say needs no special case.