@solidrt/2d 0.0.66 → 0.0.68

package/AGENTS.md

@@ -1,7 +1,8 @@
 # @solidrt/2d - agent notes
 
-An instanced sprite layer above `@solidrt/core/gpu`: one atlas texture, N
-quads in ONE draw call, composited into the app as an ordinary `<texture>`
+An instanced sprite layer above `@solidrt/core/gpu`: a layer's atlases
+bound together, N quads from any of them in ONE draw call, composited into
+the app as an ordinary `<texture>`
 leaf. The live layer backs every sprite with a SPATIAL ARENA node (never a
 rendertree element - `d-texture` sprites are the right tool up to the low
 thousands; measured ~0.65us paint and ~15KB memory per NODE, and every
@@ -15,6 +16,7 @@ Contents:
 - [The model](#the-model)
   - [Three faces](#three-faces)
   - [A layer renders through its views](#a-layer-renders-through-its-views)
+  - [Atlases and frames](#atlases-and-frames)
   - [Pose and style slots](#pose-and-style-slots)
   - [Fixed instance slots](#fixed-instance-slots)
   - [Growth](#growth)
@@ -23,7 +25,7 @@ Contents:
   - [Groups](#groups)
   - [Visibility](#visibility)
   - [Flips](#flips)
-  - [Mutations batch to a microtask](#mutations-batch-to-a-microtask)
+  - [Mutations batch to the frame](#mutations-batch-to-the-frame)
   - [The records layer](#the-records-layer)
   - [Layer space](#layer-space)
   - [The camera](#the-camera)
@@ -33,6 +35,7 @@ Contents:
   - [Retargeted motion](#retargeted-motion)
   - [Frame-rate motion](#frame-rate-motion)
   - [Frame animation](#frame-animation)
+  - [Text runs](#text-runs)
   - [Pure pieces](#pure-pieces)
 - [The baked tile layer (tiles.ts)](#the-baked-tile-layer-tilests)
   - [Chunks](#chunks)
@@ -48,6 +51,7 @@ Contents:
   - [Slots, capacity and order](#slots-capacity-and-order)
   - [Nodes, transitions and queries](#nodes-transitions-and-queries)
   - [Cameras and rotation](#cameras-and-rotation)
+  - [Text runs](#text-runs-1)
   - [Tile layer](#tile-layer)
 
 ## The model
@@ -73,15 +77,49 @@ Godot World2D only through Viewports, and there is no privileged first
 one. The window view, the minimap, two split-screen panes are the same
 `ViewHandle`. Details under Views below.
 
+### Atlases and frames
+
+A layer draws from the ATLASES it declares at creation
+(`createSpriteLayer([a, b], ...)`, `<SpriteLayer atlases={[a, b]}>`, the
+record and tile layers alike): `createAtlas` records, or
+`{ texture, width, height }` literals for a render target or a camera
+frame, up to `limits.maxTextureUnits` of them (16 on every GLES 3.0
+device), of any sizes and sampler states. They bind together as ONE
+draw per view - the multi-texture batch of PixiJS and Phaser, where
+Unity and Godot break the batch on every texture change - so sprites
+from several sheets interleave freely in draw order, key order
+included, and a tile world bakes from several tilesets in one pass. A
+`Frame` carries its texture (`{ texture, u0, v0, u1, v1 }`, stamped by
+`grid`/`namedFrames`/`fullFrame`; PixiJS's Texture, Phaser's Frame,
+Unity's Sprite and Godot's AtlasTexture pair the texture with the rect
+the same way), the record stores that texture's index in the layer's
+list (`layer.atlases`, what a raw record writer stores), and the
+fragment stage is GENERATED per layer with one sampler per atlas, the
+flat per-instance index picking it: derivatives are taken from the
+unclamped uv before the branch and the tap is `textureGrad`, so mip
+selection is the quad's own and well defined inside the branch. A frame
+whose texture the layer did not declare THROWS at the write (the
+wrong-sheet bug, caught instead of drawn); the frame left out of
+`addSprite` is the whole FIRST atlas. An atlas declared `sdf: { range }`
+(a sprite font's msdf atlas, or any distance field you upload) is
+decoded in its branch instead of sampled as colour: the median of rgb is
+the edge, anti-aliased over one screen pixel at whatever zoom, the true
+field in alpha grows a per-sprite outline (text runs set it; a colour
+atlas ignores the field). Fixed at creation like the list itself.
+
 ### Pose and style slots
 
-Node layer ownership split, two instance-buffer slots on one pipeline:
-slot 0 is the POSE buffer `[x, y, angle, sx, sy]` written ONLY by the
-core (each sprite node's Pose2D record sink; one coalesced buffer write
-per flush however many nodes moved), slot 1 the STYLE buffer
-`[u0, v0, u1, v1, tint rgba, renderOrder]`, JS-owned, published through the
-zero-copy write lease. NEVER write the pose buffer from JS - the core's
-staging mirror owns it and will overwrite.
+Node layer ownership split, two instance-buffer slots on one pipeline
+(the layer's, blended with its `blend` option, "alpha" unless it says
+"add", "multiply" or "none" at creation - two blend modes are two
+layers): slot 0 is the POSE buffer `[x, y, angle, sx, sy]` written ONLY
+by the core (each sprite node's Pose2D record sink; one coalesced buffer
+write per flush however many nodes moved), slot 1 the STYLE buffer
+`[u0, v0, u1, v1, tint rgba, renderOrder, minScreenPx, maxScreenPx,
+atlas, outline rgb, outlineWidth]` (16 floats), JS-owned, published
+through the zero-copy write lease. NEVER
+write the pose buffer from JS - the core's staging mirror owns it and
+will overwrite.
 
 ### Fixed instance slots
 
@@ -108,6 +146,30 @@ unordered. Every query passes the core a filter with the layer's root
 node (sprites and groups without a parent hang off it), so the arena
 being shared with e.g. a 3d scene costs nothing in JS.
 
+The screen-size clamp bends this one way. A sprite with `minScreenPx`
+and/or `maxScreenPx` draws its smaller axis within those VIEW pixels
+(scaled uniformly, in the vertex stage over the core-written pose, so
+after group scale and mid-transition; core's `screenSizeScale`, the
+same function @solidrt/3d's sprite material uses), which differs from
+its index column once the zoom carries it past a bound - larger under
+a floor, smaller under a ceiling; equal bounds hold a constant screen
+size. So `pick(x, y, zoom)` takes the camera zoom the clamps are
+measured at (default 1): while no sprite on the layer is clamped it is
+the raycast above; once one is, the candidates are the columns
+containing the point (the ray) plus, when a floor is on, those within
+the widest floor's reach of it (`floorReach` in pick.ts over the
+clamped sprites, recomputed on the next pick after one leaves or
+shrinks; the box overlap is a SURFACE contact in the core, so a box
+inside a big column finds nothing, which is why the ray stays in the
+union), and each is tested exactly against its drawn rect from the
+node's world matrix (`screenSizeScale` + `pointInSprite`). The pointer
+walk and `view.pick(x, y)` pass the view camera's zoom; a bare
+`layer.pick(x, y)` is the unzoomed world. `pickRect`, overlap, sweep and
+the mover stay world-space body queries and never see a clamp. The
+record layer's JS walk applies the same scale per record. The pair is
+validated against the STORED bounds before any write (a ceiling set
+alone may not drop below the floor already there).
+
 ### Spatial queries
 
 Spatial queries (`tests/collision.test.tsx` pins the contract): the
@@ -119,7 +181,8 @@ every sprite a volume touches with its deepest contact `{ sprite,
 point, normal, depth }`, unordered; `layer.sweep(volume, dx, dy,
 opts?)` every sprite the moving volume first touches `{ sprite, time,
 point, normal }`, earliest first; `layer.moveAndSlide(volume, dx, dy,
-opts?)` the character mover over them, one core call per body per
+opts?)` (and the free `moveAndSlide(layer, ...)` spelling of it, as
+@solidrt/3d's) the character mover over them, one core call per body per
 frame (the depenetration, slide and floor-snap loop runs in the spatial
 core, the same one @solidrt/3d's mover uses), returning `{ motion,
 floor, wall, ceiling, hits }` with `up` defaulting to [0, -1] (y-down).
@@ -170,19 +233,41 @@ flip). The flags live on the Sprite and re-apply to every later frame
 write; `getSprite` returns the frame un-mirrored plus the flags. Raw
 `records` writers swap u0/u1 themselves.
 
-### Mutations batch to a microtask
+### Mutations batch to the frame
 
-Mutations batch to a microtask: style lease publish + count setDraw +
-`spatial.flush()`. No mutation, no publish, no frame: a static layer
-costs zero, the same demand-gate story as the rest of the platform.
+Mutations batch: style lease publish + count setDraw + `spatial.flush()`
+go out once, in the publish pass of core's `onBeforeRender` ahead of the
+frame's paint, so a write made anywhere in the frame's JS (onFrame, an
+effect, an onLayout handler) is in that frame's picture, never the next;
+a write made outside a frame (an event handler, a timer) publishes at
+the microtask. No mutation, no publish, no frame: a static layer costs
+zero, the same demand-gate story as the rest of the platform.
 
 ### The records layer
 
-The records layer (`createRecordLayer`) keeps the old model whole: 13
+The records layer (`createRecordLayer`) keeps the old model whole: 20
 JS-owned floats per sprite `[cx, cy, w, h, u0, v0, u1, v1, rot, tint
-rgba]` (`FLOATS_PER_SPRITE`), draw order = insertion order (or key
-order with `orderBy` - see below), remove
-shifts, `layer.records` + `touch()` raw writes, JS pick walk. It is the
+rgba, minScreenPx, maxScreenPx, atlas, outline rgb, outlineWidth]`
+(`INSTANCE_FLOATS`; `atlas` is the frame's texture as its index in
+`layer.atlases`; the outline is read by a distance-field atlas only), draw order =
+insertion order (or key order with `orderBy` - see below), remove
+shifts, raw writes, JS pick walk. The raw path speaks @solidrt/3d's
+record-mesh verbs, one dimension down: `records(layer)` is the mirror
+(read it at use time - growth replaces it), `updateRecords(layer, {
+first?, count? })` publishes a RANGE of it at the flush (the whole
+mirror by default; ten moved records of ten thousand cost ten - one
+`writeBuffer` at the range's byte offset, clipped to the live sprites;
+under `orderBy` the drawn prefix whole through the lease instead, since
+the core gathers it into key order during the copy), and
+`setRecordCount(layer, n)` dials the drawn prefix - the first n live
+sprites draw and pick, the rest stay live but undrawn and unpicked,
+and the dial stays in force as sprites come and go (write ahead, dial
+after; `layer.count` is the live total regardless). The sprite verbs
+mark their own record, so a `setSprite` here publishes one record, not
+the prefix. The POPULATION verbs differ by kind and stay so: a record
+mesh's records are opaque data (`setRecords` copies in and grows), a
+record layer's are sprites (`addSprite`/`destroySprite`), so the copy-in
+here is `records(layer).set(src)` then `updateRecords(layer)`. It is the
 escape hatch for motion only JS can compute at scale (measured 30k
 sprites: 12.9ms raw records vs 30.8ms via setSprite; both figures are
 the WRITE path only - whatever computes the motion is excluded and is
@@ -190,7 +275,9 @@ usually the dominant cost, e.g. a 24k-particle sim measured ~25ms with
 a near-free publish) - the axis is
 WHERE MOTION IS COMPUTED, not retained-vs-dynamic. The sprite functions
 (addSprite/setSprite/getSprite/destroySprite) work on both layer kinds;
-record sprites have `node: null` and no groups.
+record sprites have `node: null` and no groups. `tests/records.test.tsx`
+pins the range, the dial, growth and the ordered publish on painted
+frames.
 
 ### Layer space
 
@@ -224,8 +311,8 @@ range, the contain clamp) apply to pose plus lanes and move the pose,
 and the PUSH writes the final camera. `pose()` is the pose alone;
 `camera()` the final camera as the layers received it.
 
-Camera control: `createCamera2d(view | views, { viewport: () =>
-({ width, height }), world?: { width, height, damping? }, min/maxZoom?,
+Camera control: `createCamera2d(view | views, { world?: { width,
+height, damping? }, min/maxZoom?,
 pivot?, follow?: { damping?, deadZone?, hardLimits?, lookahead? },
 offset?, panSpeed?, zoomSpeed?, rollSpeed?, damping?, inertia?, x?, y?,
 zoom?, rotation? })` - Godot's Camera2D and Three's MapControls in one
@@ -241,9 +328,13 @@ at the pivot", the pivot a viewport fraction defaulting to the center,
 so `camera().x/y` is the view center and glideTo/follow land there
 (without a `world`, the default pose puts world 0,0 at the pivot: a
 fill layer that wants world = screen at rest takes `pivot: { x: 0, y:
-0 }`). The first argument is anything with a view's `setCamera` (a view
-of a sprite layer, of a record layer, several at once - one camera over
-a scene's layers - or a signal setter feeding `<TileLayer camera>`).
+0 }`). The pivot is the point the control zooms and rolls about - the
+3d orbit control's target, which that control holds at the view centre
+and re-seats in world space (`setPivot`); this one places it on screen.
+The first argument is anything with a view's `setCamera` and `size()`
+(a view of a sprite layer, of a record layer, several at once - one
+camera over a scene's layers, the FIRST one's size the viewport - or a
+`{ setCamera, size }` pair over a signal feeding `<TileLayer camera>`).
 
 **Follow.** `follow(x, y)` chases a world point through the framing in
 `follow` (core's camera-control, shared with the 3d orbit camera):
@@ -277,7 +368,7 @@ view - a wide camera and a close one, each with its own control - and
 `activate(name, { blend? })` makes the highest-priority enabled shot
 live, blending the view from the current output over `blend` seconds
 (default 0.5; 0 cuts; x/y/rotation/pivot linear, the zoom in log
-space, `mixCamera2d`); `deactivate` falls back by priority. A live
+space, `mixCamera`); `deactivate` falls back by priority. A live
 shot's pushes reach the view at once; a blend needs `update(dt)` while
 `active()`, the controls' rule. `live()` and `camera()` read the state.
 A switch mid-blend starts from the output of that moment, so a quick
@@ -309,7 +400,8 @@ gesture measured (viewport heights per second from the pointer feed;
 the control has no estimator of its own). The
 verbs, each pushing the pose at once: `panBy(dx, dy)` screen pixels,
 `zoomAt(sx, sy, factor, { glide? })`, `rollBy(angle)`, `set(pose)`,
-`glideTo(x, y, zoom?, rotation?)` (eased, a rotation glide included),
+`glideTo({ x?, y?, zoom?, rotation? })` (eased, the fields given, a
+rotation glide included - the 3d controls' glideTo(pose)),
 `fit`, `follow`/`unfollow`, `shake`, `interrupt`, `release([vx, vy])`
 (screen pixels per second of content travel). An input
 map (core AGENTS.md) drives the axes by name and the APP binds devices
@@ -345,7 +437,7 @@ root with `e.sprite` null is "tap on empty space"). `<Camera2d
 input={input}>` inside `<SpriteLayer>` is all of that wired through
 context, the 3d `<OrbitCamera>` shape: options read at mount, driving
 the nearest view (the `<SpriteLayer>`'s own or the enclosing
-`<View2d>`), `viewport` defaulting to that view's size, the map's
+`<View2d>`), that view's `size()` the viewport, the map's
 `pan`/`zoom`/`roll` actions (or the names in `actions`) driving the
 axes, frames only while `active()`. A view's feed normalizes a drag by
 the leaf's own box, so a leaf under a designSize fit pans and zooms
@@ -392,9 +484,10 @@ entry ordered), every other entry reads them sorted. Growth, the
 instance count and the layer tint fan out to every view; the camera
 and the viewport are the view's own params, so a view costs no
 per-frame JS beyond its camera writes. The `ViewHandle` is the
-viewport contract (texture, width/height/setSize,
-oversample/setOversample, setCamera/camera/project/unproject,
-listen/handlers/handlersFor, dispose - views also die with the layer);
+viewport contract (texture, size/setSize,
+oversample/setOversample, setCamera/camera/project/unproject, pick (the
+layer's, through this camera), listen/handlers/handlersFor, dispose -
+views also die with the layer);
 the sprites stay the layer's (`addSprite`, `pick`, `setTint`,
 `createView`, `dispose`). Pointer events on a view leaf run the
 dispatch with the VIEW's camera undone over the layer's pick, the view
@@ -484,12 +577,46 @@ attach via `ref` and leave the `frame` prop off - the clip owns that
 field (the prop effect passes absent props as undefined, which setSprite
 keeps, so other props stay reactive).
 
+### Text runs
+
+Text IN the layer's world - a label under a sprite, a name on a map, a
+damage number - is a text run: a group of glyph sprites drawn from a
+SPRITE FONT's atlas (`createSpriteFont`, `addText`/`setText`/
+`destroyText`, `<Text2d>`; `examples/text.tsx`). The font is the
+runtime's own glyph engine (`flux:font`): it shapes the text (kerning is
+the engine's, carets are one pass), makes glyph cells on a worker thread
+and packs them into one atlas texture that grows as glyphs arrive. The
+atlas is one more entry in the layer's list - `createSpriteLayer([art,
+font.atlas])` - so labels draw in the one draw with the sprites they
+belong to and pan, zoom, sort (`orderBy`), pick and transition as
+sprites; a run's pose is its group's (`run.group`), where glyph pointer
+events bubble. Two cell kinds: "msdf" (the default: one atlas sharp at
+every zoom, the fragment stage decoding `Atlas.sdf`; the per-run
+`outline` draws only here) and "mask" (coverage at the face's exact size,
+for 1:1 drawing). Text
+as elements is still the right tool up to hundreds of labels: `d-text`
+under a `<view>` carrying the camera transform (what `<TileLayer>` does
+for its chunks) costs no JS per label on a camera move and is rasterized
+at the real scale; runs are for thousands, for in-layer draw order, and
+for a zoom animation that would re-rasterize every label per frame.
+
+Layout is `layoutText` (text-layout.ts, pure): `\n` breaks, `maxWidth`
+wraps with core's greedy rule, `align` per line, `anchor`
+(start/middle/end, as d-text) and `anchorY` (top/middle/baseline/bottom)
+place the run's point, `letterSpacing` and `lineHeight` as named. The
+run reports `width`, `height`, `ascent` and `lines`. A run's `fontSize`
+defaults to the face's; glyphs scale their cells by `fontSize /
+font.size`.
+
 ### Pure pieces
 
-frames.ts, pick.ts, camera.ts, camera-motion.ts, dispatch.ts,
-oversample-math.ts and tiles-math.ts (the tile grid's chunk and slot
-math, tests/tiles.test.ts) are pure (no GPU imports) BY DESIGN so they
-can be checked headless; keep them that way.
+frames.ts, extrude.ts (the mip-gutter repack, tests/extrude.test.ts),
+pack.ts (the shelf packer, tests/pack.test.ts), pick.ts, camera.ts,
+camera-motion.ts, dispatch.ts, oversample-math.ts, tiles-math.ts (the
+tile grid's chunk and slot math, tests/tiles.test.ts) and text-layout.ts
+(glyph placement over prepared units, tests/text-layout.test.ts) are pure
+(no GPU imports) BY DESIGN so they can be checked headless; keep them
+that way.
 
 ## The baked tile layer (tiles.ts)
 
@@ -497,17 +624,19 @@ can be checked headless; keep them that way.
 
 Static 2D bulk as a few quads: on tiled GPUs the budget is primitive count
 (core agents/performance.md), so a 100x100 tile world must not be 10,000
-quads per frame. `createTileLayer(cols, rows, tileW, tileH, atlas)` bakes
-the world into CHUNKED `render: "manual"` targets (default ~512px of tiles
-per chunk, `chunkTiles` to tune), each chunk a small copy of the sprite
-pipeline (shaders.ts) with FIXED record slots - an empty tile is a
+quads per frame. `createTileLayer(cols, rows, tileW, tileH, atlases)`
+bakes the world into CHUNKED `render: "manual"` targets (default ~512px
+of tiles per chunk, `chunkTiles` to tune), each chunk a manual target
+over the layer's ONE sprite pipeline (shaders.ts, compiled once per
+layer for its atlases) with FIXED record slots - an empty tile is a
 zero-size quad, instance count is constant per chunk. Records hold WORLD
 pixel coordinates; each chunk target's `uCamera` is its pixel origin, so
 the shared vertex stage does the chunk-local mapping. Chunks allocate on
 the first `setTile` that reaches them - an empty chunk costs nothing, a
 sparse world is bounded by its content, and world size is bounded by
-memory, not `maxTextureSize`. `setTile` batches to a microtask whose flush
-publishes and re-bakes ONLY dirty chunks. After that the layer is static
+memory, not `maxTextureSize`. `setTile` batches to the frame's publish
+pass (the microtask, outside a frame), whose flush publishes and re-bakes
+ONLY dirty chunks. After that the layer is static
 textures: zero per-frame cost however many tiles exist.
 
 ### Scrolling and the camera
@@ -567,16 +696,17 @@ on approach, evict) - okf/backlog/2d-baked-layers.md.
 
 | Component | Props |
 |---|---|
-| `SpriteLayer` | atlas (TextureId), capacity?, tint? ([r,g,b,a] 0..1, over the whole layer in every view), orderBy?, stagger? (ms, the layer root's enter/exit spacing), label?, ref?(layer) - the layer; plus its OWN VIEW, unless `output={false}`: width?, height? (view pixels - both, or neither = FILL: the leaf lays out at 100% of its sized parent and the view follows its box, so view pixels are the leaf's own coordinates; mount-fixed, a function `output` requires explicit sizes, matching `<Scene>` in @solidrt/3d), clearColor?, camera?, oversample?, maxOversample?, viewRef?(view), output? (a function composes the leaf from the texture id; `false` = no own view, the layer shows only through `<View2d>` children and the view props throw), events?, pointer? (a createPointerFeed fed from the view's root, what a map over this view binds; `useSpriteLayer().pointer` inside), onPointer{Down,Move,Up}?, onWheel?, onTap? (the view's root: `event.sprite` is the hit sprite or null over empty space) |
-| `Sprite` | x, y (center; local to the enclosing `<Group>`), w, h, frame?, rotation? (radians, clockwise), tint? ([r,g,b,a] 0..1), visible?, transition?, onPointer{Down,Move,Up,Enter,Leave}?, onWheel?, onTap?, ref? |
+| `SpriteLayer` | atlases (Atlas[], the sheets bound as one draw; mount-fixed) or layer (an existing createSpriteLayer handle to adopt: the component shows and populates it, keeps only the view and the leaf as its own and leaves the layer's lifetime to its maker, so `<Sprite>`/`<Text2d>` sit over an imperative layer; the creation props atlases/capacity/blend/orderBy then throw), capacity?, blend? (core gpu BlendMode, "alpha" default, "add" for glows; mount-fixed), tint? ([r,g,b,a] 0..1, over the whole layer in every view), orderBy?, stagger? (ms, the layer root's enter/exit spacing), label?, ref?(layer) - the layer; plus its OWN VIEW, unless `output={false}`: width?, height? (view pixels - both, or neither = FILL: the leaf lays out at 100% of its sized parent and the view follows its box, so view pixels are the leaf's own coordinates; mount-fixed, a function `output` requires explicit sizes, matching `<Scene>` in @solidrt/3d), clearColor?, camera?, oversample?, maxOversample?, viewRef?(view), output? (a function composes the leaf from the texture id; `false` = no own view, the layer shows only through `<View2d>` children and the view props throw), events?, pointer? (a createPointerFeed fed from the view's root, what a map over this view binds; `useSpriteLayer().pointer` inside), onPointer{Down,Move,Up}?, onWheel?, onTap? (the view's root: `event.sprite` is the hit sprite or null over empty space) |
+| `Sprite` | x, y (center; local to the enclosing `<Group>`), w, h, frame?, rotation? (radians, clockwise), tint? ([r,g,b,a] 0..1), minScreenPx?, maxScreenPx? (the screen-size clamp on the smaller axis, view pixels; 0 = off; equal = constant size), visible?, transition?, onPointer{Down,Move,Up,Enter,Leave}?, onWheel?, onTap?, ref? |
 | `Group` | x?, y?, rotation?, scale? (uniform, scales the subtree), visible? (the whole subtree), transition?, onPointer{Down,Move,Up}?, onWheel?, onTap? (bubbled from hit child sprites), ref? |
-| `Camera2d` | createCamera2d's options minus `viewport` (world?, min/maxZoom?, pivot?, follow?, offset?, panSpeed?, zoomSpeed?, rollSpeed?, damping?, inertia?, x?, y?, zoom?, rotation?), viewport? (`() => { width, height }`, default: the driven viewport's size), input? (the input map driving its `pan`/`zoom`/`roll` axes; live), actions? (action names per axis when the map's differ), ref? - a `<SpriteLayer>` child driving the nearest view's camera (the `<SpriteLayer>`'s own, or inside a `<View2d>` that view) from the map, nothing else; read at mount; throws under `output={false}` outside a `<View2d>` |
+| `Camera2d` | createCamera2d's options (world?, min/maxZoom?, pivot?, follow?, offset?, panSpeed?, zoomSpeed?, rollSpeed?, damping?, inertia?, x?, y?, zoom?, rotation?), input? (the input map driving its `pan`/`zoom`/`roll` axes; live), actions? (action names per axis when the map's differ), ref? - a `<SpriteLayer>` child driving the nearest view's camera (the `<SpriteLayer>`'s own, or inside a `<View2d>` that view; its `size()` the viewport) from the map, nothing else; read at mount; throws under `output={false}` outside a `<View2d>` |
 | `View2d` | a `<SpriteLayer>` child: one more view of the layer from a camera of its own (layer.createView as a component): width, height (view pixels, live; fixed-size only for now), camera? (partial CameraUpdate on the view's camera, live; the same state a `<Camera2d>` child writes), oversample?, maxOversample? (the auto-pick, as SpriteLayer's), clearColor?, label? (createView's, fixed), ref?(view), output?(texture) (else a built-in `<texture>` leaf at the view size carrying the view's handlers), events?, pointer? (this view's feed, fed from its root), onPointer{Down,Move,Up}?, onWheel?, onTap? (the view's root: `event.sprite` null over empty space); a `<Camera2d>` child drives the VIEW from its map (inside, `useSpriteLayer()` reports the view as `viewport` and the feed as `pointer`); `<Sprite>`/`<Group>` children mount to the layer as outside |
-| `TileLayer` | cols, rows, tileW, tileH, atlas (TextureId), frames? (the tileset `setTiles` indices name), chunkClearColor?, filter?, chunkTiles?, tint? ([r,g,b,a] 0..1, over the whole layer), oversample?, maxOversample?, camera? (TileCamera: x, y, zoom, rotation, pivotX, pivotY), label?, ref? |
+| `TileLayer` | cols, rows, tileW, tileH, atlases (Atlas[], the tilesets bound as one bake; mount-fixed), frames? (the tileset `setTiles` indices name), chunkClearColor?, blend? (the bake's blend mode, "alpha" default; mount-fixed), filter?, chunkTiles?, tint? ([r,g,b,a] 0..1, over the whole layer), oversample?, maxOversample?, camera? (TileCamera: x, y, zoom, rotation, pivotX, pivotY), label?, ref? |
 
 ### SpriteLayer and useSpriteLayer
 
-`SpriteLayer` owns the layer and its own view, rendered as the built-in
+`SpriteLayer` owns the layer (or adopts an existing one through `layer`,
+owning only what follows) and its own view, rendered as the built-in
 `<texture>` leaf carrying the view's pointer handlers (opt out with
 `events={false}`, which throws at mount together with a `pointer` feed -
 the feed would listen at a root no event reaches; the same on `<View2d>`;
@@ -591,7 +721,7 @@ inside a `<View2d>` that view), what a `<Camera2d>` drives, and
 `pointer` that view's feed (the owner's `pointer` prop, null without
 one); read under `output={false}` outside a `<View2d>` `viewport` throws. A FILL-mode
 view is 1x1 until the first layout: `ref` fires at mount, before it, so
-`viewport.width`/`height` read 1 there. Sprites added and positioned from
+`viewport.size()` reads 1x1 there. Sprites added and positioned from
 `ref` (the pool, the opening scene) are fine - the first layout resizes
 the view before the first paint - but anything that needs the real size
 (centering on the view) waits for `onLayout`, or works in a `designSize`
@@ -645,23 +775,45 @@ hover, wheel and tap rules headless.
 
 ### Atlases and sampling
 
-- The atlas is NOT owned by the layer: layers come and go, atlases usually
-  live app-long. Dispose atlases yourself (or let the reactive owner do it -
-  createAtlas registers with the owning scope like every core texture).
+- The atlases are NOT owned by the layer: layers come and go, atlases
+  usually live app-long. Dispose atlases yourself (or let the reactive
+  owner do it - createAtlas registers with the owning scope like every
+  core texture).
 - `createImage` is the wrong loader for pixel-art atlases: it never forwards
   sampler options, so it is always `filter: "linear"`. `createAtlas` takes
   decoded pixels (`createAtlas(decodeImage(bytes), { filter: "nearest" })`,
   or pixels built in code) and passes the full sampler through (`filter`,
-  `wrap`, `mipmap`, `anisotropy`); the record it returns is what `grid` and
-  `namedFrames` slice.
+  `wrap`, `mipmap`, `anisotropy`); the record it returns is what `grid`,
+  `namedFrames` and `fullFrame` slice, and what a layer's `atlases` list
+  holds.
+- A frame from a sheet the layer did not declare THROWS at the write
+  (addSprite, setSprite, setTile, setTiles, a tile layer's `frames`
+  table), naming the layer's atlases: a sprite never silently draws from
+  the wrong sheet. The same frames serve every layer that declares their
+  atlas (a scene layer and its additive glow layer over the same art).
+  Raw record writers store the texture's index in `layer.atlases`.
+- The sampler cap: a layer binds at most `limits.maxTextureUnits` atlases
+  (16 on every GLES 3.0 device, the whole pass's budget - a layer's
+  targets bind nothing else). Past it, pack sheets together; runtime
+  images need the packer (okf/backlog/2d-atlas-runtime-packing.md).
 - Frames that share an edge do not bleed: the fragment stage clamps every
   sample into its frame, so a sprite at a fractional position (a scrolling
   backdrop, an easing camera) never paints a line of the neighbouring cell,
-  and an edge-to-edge sheet needs no gutter and no shaved rect table. The
-  one case left is a `mipmap` atlas, whose mip texels average across cell
-  edges before sampling: pass `inset` to `grid`/`namedFrames` (2^k texels
-  keeps mip level k clean, losing that border) or pack a gutter as
-  `spacing`, until extrusion lands (okf/backlog/2d-atlas-extrude.md).
+  and an edge-to-edge sheet needs no gutter and no shaved rect table. A
+  `mipmap` atlas is different: its mip texels average across cell edges
+  BEFORE sampling, and no UV-side trick undoes that. Extrude the sheet
+  before `createAtlas` - `extrudeGrid(image, cols, rows, gutter)` for a
+  uniform sheet, `extrudeRects(image, rects, gutter)` for a hand-packed
+  one: every cell is copied into a gutter of its own replicated edge
+  pixels, the result slices with the returned `options`/`rects`, and mip
+  levels 0 through log2(gutter) sample clean (TexturePacker's "Extrude",
+  Unity's "Extrude Edges"). The rules: `gutter` a power of two and every
+  cell size a multiple of it, so cell edges land on mip texel edges (the
+  calls throw otherwise, naming the fix); the sheet grows by 2 x gutter
+  per cell per axis; deeper levels mix again, so size the gutter to the
+  smallest scale the sheet is drawn at (gutter 4 covers down to a
+  quarter). Load-time CPU work, a few milliseconds for a 1024-square
+  sheet.
 - The colour contract: tint multiplies the atlas texel as stored -
   premultiplied sRGB, no decode - and the layer tint multiplies over
   that, so a tint of `[0.5, 0.5, 0.5, 1]` halves the ENCODED value (about
@@ -671,7 +823,11 @@ hover, wheel and tap rules headless.
   shading: the same tint triple is a different brightness in the two
   packages, so a palette shared across them needs its own conversion.
 - Tint multiplies the sampled texel (`texture * tint`) and the pipeline
-  blends with `blend: "alpha"` in record order, the premultiplied composite.
+  blends with the layer's `blend` in record order - "alpha" by default,
+  the premultiplied composite; "add" accumulates (glows, sparks, light
+  cones: two half-alpha whites make opaque white), "multiply" darkens,
+  "none" overwrites. Pipeline state, so it is per layer and fixed at
+  creation; an additive effect layer draws over the scene layer.
   The atlas is premultiplied because `decodeImage` premultiplies by default;
   an atlas uploaded from straight-alpha pixels (`decodeImage(bytes, { alpha:
   "straight" })` into `createAtlas`) draws color under transparent texels
@@ -716,23 +872,24 @@ hover, wheel and tap rules headless.
   stays stable and a spawn is one setSprite, never an add. Keep a free
   list of hidden handles; scanning the pool for one is the cost that
   shows up first at a few hundred entities. On the records layer, do not
-  cache `layer.records` across addSprite - growth replaces the array and
-  a hoisted reference becomes a dead copy whose writes publish nothing.
-  `layer.withRecords(fn)` is the hoist-proof read; a bare `layer.records`
-  at use time is equally live.
+  cache `records(layer)` across addSprite - growth replaces the array and
+  a hoisted reference becomes a dead copy whose writes publish nothing;
+  read it at use time (the top of the frame's step is the place).
 - Records layer: record order is draw order: `destroySprite` shifts every
   later sprite down one slot (copyWithin + index fixup, O(later
-  sprites)). Its flush publishes the WHOLE live prefix, not a dirty
-  range: one moved sprite re-publishes count x 52 bytes - a single
-  memcpy, microseconds at 10k; the node layer's style publish is the same
-  whole-prefix shape. Dirty ranges were deliberately not built until a
-  measurement asks.
+  sprites)) and marks the shifted records dirty. The flush publishes the
+  DIRTY record range (one buffer write at its byte offset, clipped to
+  the live sprites), or under `orderBy` the drawn prefix whole through
+  the lease - so a moved sprite costs its 80 bytes on a plain layer and
+  count x 80 bytes on an ordered one. The node layer's style publish is
+  still the whole-prefix shape (a boolean dirty flag over the high-water
+  mark), the one place a range is not yet tracked.
 - `orderBy` on BOTH layers: the core gathers publishes into key order
   (gpu `instanceOrder`, radix sort + one extra memcpy, no per-record JS),
   so a y-sorted crowd costs the same flush as an unsorted one. Records
   and slots stay stably addressed; ties keep slot order; `pick()` still
   resolves overlap by slot/record order. Records layer keys: "y" or a raw
-  `{ field, descending? }` offset into the 13-float record. Node layer
+  `{ field, descending? }` offset into the 16-float record. Node layer
   keys: `"y"` - WORLD y from the core-written pose buffer, so sprites
   moved by native transitions (or any core producer) re-sort with zero JS
   per frame - or `"renderOrder"` - the app-owned per-sprite `renderOrder`
@@ -743,7 +900,7 @@ hover, wheel and tap rules headless.
   pose AND style under ONE permutation and republishes the sibling buffer
   itself when the key buffer re-orders (the multi-buffer stage of
   okf/backlog/gpu-instance-order.md). `renderOrder` on a record-layer
-  sprite throws - its 13-float record has no key field.
+  sprite throws - its 16-float record has no key field.
 - The node layer's STYLE slots are not compacted: a removed sprite leaves
   its style floats in place (invisible - the pose is zeroed) until the
   slot recycles. Do not read style truth from the buffer; getSprite reads
@@ -804,6 +961,26 @@ hover, wheel and tap rules headless.
   away with the transform-on-the-leaf camera only because its composited
   view is the WORLD, not a viewport of it.
 
+### Text runs
+
+- A run draws nothing for a glyph whose cell is not in the atlas yet:
+  the sprite is there, hidden, at its place, and the font re-frames the
+  run when the cell lands a frame or two later (`font.ready()` awaits
+  that; `settle` does in a test). Printable ASCII is made at font
+  creation so a run of it never waits; `chars: false` skips that.
+- The atlas grows by doubling and EVERY cell moves when it does:
+  `font.atlas.width`/`height` change in place and every run over the
+  font is re-framed. Never cache a glyph's frame outside the font.
+- A sprite font over "msdf" cells (the default) is sharp at every zoom;
+  one over "mask" cells is exact at the face's size, resamples under zoom
+  like any texture, and silently ignores `outline`.
+- A run is node-layer only (it is a group); `addText` on a layer that
+  does not declare `font.atlas` throws. Dispose runs before the font
+  (`font.dispose`, or the owner's cleanup).
+- The style record is 16 floats and the raw record 20: a raw record
+  writer (`records(layer)`) that assumed 16 is off by the outline field
+  per sprite.
+
 ### Tile layer
 
 - `<TileLayer>`'s world view is WORLD sized (cols * tileW) and takes that

package/README.md

@@ -1,8 +1,8 @@
 # @solidrt/2d
 
-An instanced sprite layer for SolidRT: one atlas, one GPU buffer, thousands
-of sprites in a single draw call, composited into your app as an ordinary
-texture element.
+An instanced sprite layer for SolidRT: your atlases bound together, one GPU
+buffer, thousands of sprites in a single draw call, composited into your
+app as an ordinary texture element.
 
 *Status: experimental. Expect API churn.*
 
@@ -16,7 +16,7 @@ let frames = grid(atlas, 4, 4)
 
 render(() => (
   <window>
-    <SpriteLayer width={720} height={480} atlas={atlas.texture}>
+    <SpriteLayer width={720} height={480} atlases={[atlas]}>
       <Sprite x={100} y={120} w={32} h={32} frame={frames[0]} />
       <Sprite x={200} y={160} w={32} h={32} frame={frames[5]} rotation={0.4} />
     </SpriteLayer>
@@ -24,28 +24,43 @@ render(() => (
 ))
 ```
 
+A frame knows the sheet it is cut from, so a layer declaring several
+atlases draws sprites from any of them in the same draw (the multi-texture
+batch), and a mipmapped sheet goes through `extrudeGrid`/`extrudeRects`
+first so its mip chain does not bleed across cells.
+
 The rendertree already handles 2D well: a `d-texture` with atlas sub-rects is
 a sprite, with native transitions, gesture-arena pointer events, and
 per-element inspectability, and it carries populations into the low
-thousands. This package is for what lies beyond that: dense, per-frame
-animated populations - entities, particles, bullets - where per-sprite
-property writes through the JS boundary are the bottleneck. Sprite records
-live in one `Float32Array` and publish to the GPU through SolidRT's zero-copy
-buffer write lease; moving ten thousand sprites is ten thousand float stores
-and one bulk publish, not twenty thousand FFI calls.
+thousands. This package is for what lies beyond that: dense, animated
+populations - entities, particles, bullets - drawn as one instanced draw
+per view. Every sprite is a node of the spatial core, so native
+transitions, groups, picking and the collision queries reach it with no
+per-frame JS: a sprite write is a target the core animates toward, and
+the core writes the pose buffer itself. For motion only JS can compute at
+scale (a flock, a particle sim), the records layer is the escape hatch:
+sixteen JS-owned floats per sprite in one `Float32Array`, published by
+dirty range with the same `records`/`updateRecords`/`setRecordCount`
+verbs as `@solidrt/3d`'s record mesh - ten thousand float stores and one
+buffer write, not twenty thousand FFI calls.
 
 Two layers, like `@solidrt/3d`: an imperative core
 (`createSpriteLayer` / `addSprite` / `setSprite` - per-frame motion calls
 these from `onFrame`) and the component face (`SpriteLayer` / `Sprite`) for
 structure and slow state. A static layer publishes nothing and costs nothing;
-the paint-order story is the painter's algorithm (insertion order); pointer
-events hit-test exact rotated rects, topmost first, with pointer capture.
-
-v1 scope: atlas creation and slicing (`createAtlas`, `grid`, `namedFrames`),
-the sprite layer with camera pan/zoom, sprite pointer events, and the
-component face. Staged next: baked/tilemap layers (static worlds as one
-quad), z-ordering, frame animation helpers, and the retro presets (pixel
-canvas, palette and scanline passes) - see `okf/backlog/`.
+draw order is slot order unless the layer names a key (`orderBy`: world y
+for a perspective crowd, or a per-sprite `renderOrder`); pointer events
+hit-test exact rotated rects, topmost first, with pointer capture.
+
+In the package: atlas creation, slicing and extrusion (`createAtlas`,
+`grid`, `namedFrames`, `fullFrame`, `extrudeGrid`, `extrudeRects`), the
+sprite layer with its views and cameras, sprite pointer events, the baked
+tile layer, frame animation, key ordering, world-space text (a sprite
+font over the runtime's glyph engine is one more atlas, a run of text a
+group of glyph sprites: `createSpriteFont`, `addText`, `<Text2d>`), and
+the component face. Staged
+next: streaming tile worlds and the retro presets (pixel canvas, palette
+and scanline passes) - see `okf/backlog/`.
 
 The full model and the sharp edges are in [AGENTS.md](AGENTS.md); runnable
 patterns in [examples/](examples/).