@solidrt/2d 0.0.56 → 0.0.57

package/AGENTS.md

@@ -17,8 +17,16 @@ moved subtrees in Rust, and picking walks the core BVH.
   `addGroup`/`setGroup`/`setSpriteParent`/`setSpriteTransition`/
   `setGroupTransition` - plain objects, no signals, usable without
   components), the records layer (records.ts: `createRecordLayer` - the
-  raw escape hatch, below), and the component face (components.tsx:
-  `SpriteLayer`/`Sprite`/`Group`/`Camera2d` over context).
+  raw escape hatch, below), and the component face (components/:
+  `SpriteLayer`/`Sprite`/`Group`/`View2d`/`Camera2d` over context).
+- A layer holds sprites and renders NOTHING by itself: it shows through
+  its VIEWS (`layer.createView({ width, height, camera?, oversample?,
+  clearColor?, label? })`, `<View2d>`, or the `<SpriteLayer>`'s own leaf,
+  which is one), each a draw target with a camera, a size and pointer
+  dispatch of its own - a Unity scene renders only through Cameras, a
+  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.
 - 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
@@ -37,9 +45,34 @@ moved subtrees in Rust, and picking walks the core BVH.
 - Picking is the core index: `pick` raycasts [x, y, -1] along +z (exact
   rotated-rect via the node's local box) and returns ALL hits topmost
   first (highest slot) - the all-hits shape of @solidrt/3d's pick, so
-  `pick(x, y)[0]` is the topmost; `pickRect` is the BVH overlap query
-  (exact for rotated sprites, the marquee), unordered. Both filter to the
-  layer's own nodes - the arena is shared with e.g. a 3d scene.
+  `pick(x, y)[0]` is the topmost; `pickRect` is `overlap` over an
+  unrotated rect, sprites only (exact for rotated sprites, the marquee),
+  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.
+- Spatial queries (`checks/collision-check.tsx` pins the contract): the
+  3d scene's trio one dimension down, Godot's PhysicsDirectSpaceState2D
+  and CharacterBody2D in their names. `layer.raycast(x, y, dx, dy,
+  opts?)` is every shown sprite the ray strikes, nearest first, with
+  distance, edge point and edge normal; `layer.overlap(volume, opts?)`
+  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
+  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).
+  A `Volume` is a `Circle` `{ x, y, radius }`, a `Capsule` `{ ax, ay,
+  bx, by, radius }` or a `Rect` `{ x, y, width, height, rotation? }`;
+  `QueryOptions.sprites` is an include-list. Results name sprites, never
+  node ids, and every query runs the pending batch first, like pick.
+  The trap behind the design: a sprite is a COLUMN in the index
+  (`SPRITE_DEPTH` half-depth along z), not a flat quad. Against a flat
+  triangle the core's contact for a circle whose center lies over the
+  sprite is the plane normal (z) with depth = radius; against a column
+  every volume at z = 0 meets only side faces, so contacts, sweeps and
+  the mover stay in the plane with no 2d narrowphase of their own.
 - Groups (`addGroup`/`<Group>`) are plain arena nodes (x, y, rotation,
   UNIFORM scale - a group is a frame, never a sprite size; sprite w/h
   lives in the sprite node's scale, which is why sprites cannot parent
@@ -83,68 +116,139 @@ moved subtrees in Rust, and picking walks the core BVH.
 - Layer space is pixels, top-left origin, y-down - the render tree's frame.
   The pipeline's clip space is y-down too (core gpu.ts pixel contract), so
   the vertex stage carries NO flip anywhere. Do not add one.
-- The camera (`setCamera`/the `camera` prop) is ONE `CameraUpdate` type
-  across both layers: offset, zoom, and rotation about a pivot (camera.ts
-  documents the semantics and the heading-upward convention,
-  `rotation = -h - pi/2`). On the sprite layer it is a shared-params
-  write (`uCamera` + `uCameraRot`, the rotation in-shader), one call
-  however many sprites exist; `projectCamera`/`unprojectCamera` export
-  the world <-> screen mapping as pure functions, and pointer dispatch
-  undoes the camera with the latter, so events arrive in world (layer)
-  pixels. Picking itself works in world space and never sees the camera.
-  `layer.camera()` reads the camera back (every field present - the
-  `CameraState` snapshot, @solidrt/3d's scene.camera()) and
-  `layer.project(x, y)` / `layer.unproject(x, y)` are the two pure
+- The camera (`view.setCamera`/the `camera` prop) is ONE `CameraUpdate`
+  type across both layer kinds' views: offset, zoom, and rotation about a
+  pivot (camera.ts documents the semantics and the heading-upward
+  convention, `rotation = -h - pi/2`). It is a shared-params write on
+  the view's target (`uCamera` + `uCameraRot`, the rotation in-shader),
+  one call however many sprites exist; `projectCamera`/`unprojectCamera`
+  export the world <-> screen mapping as pure functions, and pointer
+  dispatch undoes the view's camera with the latter, so events arrive in
+  world (layer) pixels. Picking itself works in world space and never
+  sees a camera. `view.camera()` reads the camera back (every field
+  present - the `CameraState` snapshot, @solidrt/3d's scene.camera())
+  and `view.project(x, y)` / `view.unproject(x, y)` are the two pure
   functions over it.
-- Camera control: `createCamera2d(layer | layers, { viewport: () =>
+- Camera control: `createCamera2d(view | views, { viewport: () =>
   ({ width, height }), world?: { width, height }, min/maxZoom?, pivot?,
-  deadZone?: { width, height }, zoomSpeed?, followSpeed?, inertia?,
-  x?, y?, zoom?, rotation? })` - Godot's Camera2D and Three's
-  MapControls in one control over the shared CameraUpdate: drag to pan
-  with inertia on release, wheel and pinch zoom about the pointer, eased
-  `glideTo`/`fit`, `follow(x, y)` through a dead zone with damping,
-  rotation about the pivot, and world bounds that CONTAIN the view (an
-  axis whose view is wider than the world centers; limits ignore
-  rotation, Godot's rule). The pose is "world point 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 the layers' `setCamera` (a sprite layer, a
-  record layer, both at once, or a signal setter feeding `<TileLayer
-  camera>`). Input runs on core's `createTransform` recognizer like the
-  3d orbit camera (arena arbitration, slop swallowed, one delta per
-  FRAME - a synthetic drag under a frozen clock pans nothing until frames
-  step). Two ways in: `cam.attach(layer)` listens at the layer's root, so
-  the camera sees exactly the presses the sprites let through (a sprite
-  that stops its down keeps the camera out of that drag; a wheel
-  anywhere zooms) and pushes the pose synchronously on input; the raw
-  `cam.handlers` spread onto a leaf without a dispatch (a tile world on
-  its own). Call `cam.update(dt)` from a frame loop (it pushes one
-  setCamera per driven layer when the pose changed and reports that),
-  gated on the reactive `cam.active()` (true while a glide, fling, fit
-  or follow needs frames, false at rest), read `cam.camera()` for
+  deadZone?: { width, height }, panSpeed?, zoomSpeed?, rollSpeed?,
+  followSpeed?, inertia?, x?, y?, zoom?, rotation? })` - Godot's Camera2D
+  and Three's MapControls in one control over the shared CameraUpdate:
+  pan with inertia on release, zoom about a point, eased `glideTo`/`fit`,
+  `follow(x, y)` through a dead zone with damping, roll about the pivot,
+  and world bounds that CONTAIN the view (an axis whose view is wider
+  than the world centers - so at the fit zoom a pan is a no-op, there is
+  nothing to pan; limits ignore rotation, Godot's rule). The pose is
+  "world point 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>`).
+  Input, the rule (ARCHITECTURE.md): the control consumes a device-free
+  abstraction and never handles events itself. Its `axes` (core's
+  createAxes contract) are `pan` (vec2: a delta is finger travel in
+  viewport heights, applied as content travel - the world follows the
+  finger; a rate slides at one viewport height per second), `zoom` (axis,
+  octaves, positive in: a delta bracketed by a gesture - a pinch - applies
+  at once about its focal point, an unbracketed one - a wheel notch -
+  retargets an eased glide, which is how the control tells a finger from
+  an impulse; notches compound on the pending target) and `roll` (axis,
+  turns); a pan gesture's begin stops any glide (a finger landing on a
+  gliding view holds it) and its end flings with the drag's velocity. The
+  verbs, each pushing the pose at once: `panBy(dx, dy)` screen pixels,
+  `zoomAt(sx, sy, factor, { glide? })`, `rollBy(angle)`, `set(pose)`,
+  `glideTo`, `fit`, `follow`/`unfollow`, `interrupt`, `release`. An input
+  map (core AGENTS.md) drives the axes by name and the APP binds devices
+  to it: the view's pointer feed (`createPointerFeed()`, handed to
+  `<SpriteLayer pointer>` / `<View2d pointer>`, or bridged with
+  `feedPointer(view, feed)` for an imperative view - fed from the view's
+  ROOT, so a sprite that claims its press keeps the camera out of that
+  drag and a wheel anywhere zooms), a pad, the keyboard. Nothing binds
+  by default; `camera2dBindings({ pointer, gamepad?, keyboard? })` is the
+  standard set (drag and two fingers pan, pinch and wheel zoom, twist
+  rolls; the left stick and the arrows scroll the VIEW - bound through
+  invert(), since keys and sticks move the camera where a drag moves the
+  content - the triggers zoom, the right stick's x rolls) and
+  `camera2dActions` the declarations:
+
+  ```tsx
+  let pointer = createPointerFeed()
+  feedPointer(view, pointer)
+  let input = createInputMap(camera2dActions)
+  input.bind(camera2dBindings({ pointer, gamepad: gamepad() }))
+  input.drive(cam.axes)
+  ```
+
+  Call `cam.update(dt)` from a frame loop (it advances glides, follow,
+  inertia and the axis rates, pushes one setCamera per driven view when
+  the pose changed and reports that), gated on the reactive
+  `cam.active()` (true while a glide, fling, fit, follow or pan gesture
+  needs frames, or a rate drives; false at rest), read `cam.camera()` for
   projectCamera. The camera has NO tap of its own: taps are the
   dispatch's (`onTap` on the root with `e.sprite` null is "tap on empty
-  space"). `<Camera2d>` inside `<SpriteLayer>` is all of that wired
-  through context, the 3d `<OrbitCamera>` shape: options read at mount,
-  `viewport` defaulting to the layer's size, frames only while
-  `active()`. Anchors and deltas arrive in the leaf's own frame (core's
-  recognizers measure in the node's frames), so a leaf under a
-  designSize fit pans and zooms correctly. The motion is
-  camera-motion.ts, pure; checks/camera2d-check.ts pins the clamp,
-  anchoring, glides, follow and inertia headless, examples/camera.tsx
-  (function face, attach) and examples/pick.tsx (`<Camera2d>`) are the
-  live guards. Not yet, all additive: two-finger twist rotation,
-  rotation glides, a contain origin other than center, live option
-  props on `<Camera2d>` (the motion reads them once; remount for new
-  bounds).
+  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 `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
+  correctly. camera2d.ts imports `@solidrt/core/input` only, so
+  checks/camera2d-check.ts pins the clamp, anchoring, glides, follow,
+  inertia and the axes headless; examples/camera.tsx (function face) and
+  examples/pick.tsx (`<Camera2d>`) are the live guards. The shared
+  vocabulary with @solidrt/3d, one kind and unit per word: `pan` vec2,
+  `zoom` axis (octaves), `roll` axis (turns) here; `rotate`, `look`,
+  `move`, `rise` there. The pose options are initial values; every other
+  option (world, zoom range, pivot, dead zone, the speeds, inertia) is
+  read where it applies, never snapshotted, so `<Camera2d>` props are
+  live - forwarded as getters, a bounds or pivot change re-clamping and
+  pushing the pose at once through `set({})` - and a function-face
+  caller mutates the options object it passed (the `<OrbitCamera>` rule,
+  pinned in the check's live-options case). Not yet, all additive:
+  rotation glides, a contain origin other than center.
 - Layer tint (`setTint(rgba)`/the `tint` option and prop, both layer
   kinds): one `uTint` shared-params write multiplied over every sprite's
   own tint - day/night, a dimmed parallax plane, a fade-in. Cheap to
   animate (no record touches), unlike TileLayer's, which re-renders
   resident chunks. The same contract as TileLayer.setTint, so one signal
   drives a whole scene across layer kinds.
+- Views (`layer.createView({ width, height, camera?, oversample?,
+  clearColor?, label? })`, both layer kinds): the ONLY output a layer
+  has - the window-filling main view, a minimap, a radar strip, a zoomed
+  inset, two split-screen panes - @solidrt/3d's scene.createView one
+  dimension down, as Unity renders a scene only through Cameras and
+  Godot a World2D only through Viewports. Each view is one draw target
+  holding one entry over the layer's pipeline and instance buffers
+  (views.ts): no sprite is mirrored, no record is written twice, and key
+  order (`orderBy`) comes along, since the core gathers the buffers
+  themselves at publish - ONE live entry declares the order (the first
+  view's; when that view is disposed the next live view re-adds its
+  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);
+  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
+  as the root of the walk: a sprite under a minimap gets its ordinary
+  handlers, `view.listen` is the last stop (a tap there with `e.x`/`e.y`
+  in world pixels is "glide the main camera here"), and
+  a camera bound to a feed `feedPointer(view, feed)` bridges drives any
+  view. `<View2d>` is the
+  component form; the `<SpriteLayer>`'s built-in leaf is a view too, and
+  `<SpriteLayer output={false}>` has none, showing only through its
+  `<View2d>` children (examples/split-screen.tsx). examples/views.tsx is
+  the live guard. Not yet, all additive: tile-layer views, a `layers`
+  bitmask (a markers-only minimap), `into` tiling, per-view tint, and a
+  viewport over SEVERAL layers under one camera (their scene-level
+  camera) - okf/backlog/2d-layer-views-additive.md.
 - Retargeted motion is NATIVE: `setSpriteTransition(sprite, { position:
   { duration: 700, bounce: 0.3 }, ... })` (or the `transition` prop) makes
   setSprite writes TARGETS the core animates toward - position/scale
@@ -217,6 +321,29 @@ empty chunks cost nothing). Tiles are data, not
 children: there is no `<Tile>` component on purpose - write cells through
 `ref` with `setTile`.
 
+Bulk writes: `setTiles(col, row, cols, rows, cells)` writes a rect at
+once - `cells` row-major, `cols * rows` long, either frames (null clears)
+or, with a `frames` table given at creation (`createTileLayer(..., {
+frames })`, the `<TileLayer frames>` prop: a tileset, `grid()`'s array,
+up to 65534 entries), indices into it (-1 clears; a Uint16Array holds -1
+as 0xffff, the same bits) - Unity's SetTilesBlock, Phaser's putTilesAt
+over the map's tileset. One locate and one dirty mark per chunk the rect
+touches, the per-cell loop inside the layer, the same flush; a chunk the
+rect only clears never allocates, so a whole-world write of a sparse
+world allocates exactly the chunks the per-cell seed would. A generated
+or worker-built world is a Uint16Array of indices, transferable, never an
+array of frame objects; a fill is `new Uint16Array(n).fill(i)`. `tint`
+in the options applies to every cell set. Every entry is validated before
+the first write, so a bad one changes nothing; the table is copied at
+creation. The rect form is the shape for worker transfer and chunk
+re-fill, not a large speedup: the per-cell floor is the record write
+itself, so a 16k-cell solid rect re-writes in ~14 ms against ~25 ms as a
+setTile loop and a sparse rect is at parity with the loop, while a first
+seed is dominated by chunk allocation at 1-2 ms per chunk
+(probes/2d-tiles-bulk-bench.tsx). probes/2d-tiles-bulk-probe.tsx holds
+the three seeds (setTile, index rect, frame rect) to the same cells,
+chunks and bakes.
+
 Tinting, two levels: `setTile(col, row, frame, { tint })` writes the
 cell's record tint (same `[r, g, b, a]` 0..1 semantics as a sprite's
 tint; absent keys keep their values, a cell set from empty starts at
@@ -232,37 +359,50 @@ on approach, evict) - okf/backlog/2d-baked-layers.md.
 
 | Component | Props |
 |---|---|
-| `SpriteLayer` | width?, height? (layer pixels - both, or neither = FILL: the leaf lays out at 100% of its sized parent and the layer follows its box, so layer pixels are the leaf's own coordinates; mount-fixed, `output` requires explicit sizes, matching `<Scene>` in @solidrt/3d), atlas (TextureId), capacity?, clearColor?, camera?, tint? ([r,g,b,a] 0..1, over the whole layer), oversample?, maxOversample?, orderBy?, label?, ref?, output?, events?, onPointer{Down,Move,Up}?, onWheel?, onTap? (the root of the walk: `event.sprite` is the hit sprite or null over empty space) |
+| `SpriteLayer` | atlas (TextureId), capacity?, tint? ([r,g,b,a] 0..1, over the whole layer in every view), orderBy?, 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? |
 | `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?, deadZone?, zoomSpeed?, followSpeed?, inertia?, x?, y?, zoom?, rotation?), viewport? (`() => { width, height }`, default: the layer's size), ref? - a `<SpriteLayer>` child driving its camera from the layer's root; read at mount |
-| `TileLayer` | cols, rows, tileW, tileH, atlas (TextureId), 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? |
+| `Camera2d` | createCamera2d's options minus `viewport` (world?, min/maxZoom?, pivot?, deadZone?, panSpeed?, zoomSpeed?, rollSpeed?, followSpeed?, 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>` |
+| `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? |
 
-`SpriteLayer` owns the layer and renders the built-in `<texture>` leaf
-carrying the layer's pointer handlers (opt out with `events={false}`; compose
-yourself with `output`, then spread `useSpriteLayer().layer.handlers` onto
-your leaf). `useSpriteLayer()` returns `{ layer, parent }` - the same shape
-as `useScene()` in `@solidrt/3d` - where `parent` is the enclosing
-`<Group>`'s handle (null at the layer root), so imperative
-`addSprite(layer, { parent })` mounts where the JSX sits. `Sprite` renders
+`SpriteLayer` owns the layer and its own view, rendered as the built-in
+`<texture>` leaf carrying the view's pointer handlers (opt out with
+`events={false}`; compose yourself with `output`, then spread
+`useSpriteLayer().viewport.handlers` onto your leaf; `output={false}` for
+no own view at all). `useSpriteLayer()` returns `{ layer, parent,
+viewport, pointer }` - the same shape as `useScene()` in `@solidrt/3d` -
+where `parent` is the enclosing `<Group>`'s handle (null at the layer
+root), so imperative `addSprite(layer, { parent })` mounts where the JSX
+sits, `viewport` is the nearest view (the `<SpriteLayer>`'s own, or
+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
+`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`
+that is known up front. `Sprite` renders
 nothing - it allocates a record through context and syncs props into it.
 `GroupContext` is `createContext<SpriteGroup | null>(null)` on purpose: an
 optional parent needs a non-undefined default, since Solid 2 throws on a
 resolved `undefined` even when one was passed as the default.
 
 Pointer events (dispatch.ts, both layer kinds): the DOM event model one
-tree deeper, with the LAYER as the root of the walk. Exact rotated-rect
+tree deeper, with the VIEW as the root of the walk. Exact rotated-rect
 containment, topmost sprite first; down/move/up/wheel dispatch on the hit
-sprite, bubble through its enclosing groups and END AT THE LAYER's
-listeners (`layer.listen({...})`, the `<SpriteLayer onPointer*/onWheel/
-onTap>` props) - over empty space the walk is the layer alone, with
-`event.sprite` null. `event.sprite` stays the hit, `currentTarget` the
-handle whose handler runs (the layer at the end), `stopPropagation()`
-stops the walk, and a stopped DOWN claims the whole press: that pointer's
-move, up and tap never reach the layer either (the chain still bubbles).
+sprite, bubble through its enclosing groups and END AT THE VIEW's
+listeners (`view.listen({...})`, the `<SpriteLayer>`/`<View2d>`
+`onPointer*/onWheel/onTap` props) - over empty space the walk is the view
+alone, with `event.sprite` null. `event.sprite` stays the hit,
+`currentTarget` the handle whose handler runs (the view at the end),
+`stopPropagation()` stops the walk, and a stopped DOWN claims the whole
+press: that pointer's move, up and tap never reach the view either (the
+chain still bubbles).
 That one rule is how a sprite drags itself under a `<Camera2d>` without
 the view panning: stop the down, own the captured moves. Capture is per
-pointerId to the press target, the layer included (a drag from empty
+pointerId to the press target, the view included (a drag from empty
 space keeps delivering to the root as it crosses sprites; a drag from a
 sprite keeps naming it with live coordinates). Enter/leave fire on the
 sprite alone - a group never receives them - while the root sees every
@@ -290,7 +430,12 @@ hover, wheel and tap rules headless.
   live app-long. Dispose atlases yourself (or let the reactive owner do it -
   createAtlas registers with the owning scope like every core texture).
 - `capacity` is a reservation, not a limit, on both layer kinds; reserve
-  realistically to skip the growth copies. On the records layer, do not
+  realistically to skip the growth copies. The pool idiom that fits a
+  game: reserve `capacity`, add every sprite at mount with `visible:
+  false`, then show/hide - a hidden sprite keeps its slot, so draw order
+  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`
@@ -307,10 +452,18 @@ hover, wheel and tap rules headless.
   mid-flight pose (what is on screen). Clearing the transition (null) keeps the
   mid-flight pose on the node while the mirror still holds the old
   target: the next setSprite write snaps to whatever it says.
-- Node layer picking reads the index as of the last core flush; `pick`/
-  `pickRect` run the layer's pending batch first, so write-then-pick in
-  one tick is coherent. Producers moving nodes between flushes are one
-  frame stale to picking, like every query.
+- Node layer picking reads the index as of the last core flush; every
+  query runs the layer's pending batch first, so write-then-query in one
+  tick is coherent. Producers moving nodes between flushes are one frame
+  stale to picking, like every query.
+- The queries are per-body answers - a hit test, a marquee, a blast
+  radius, one mover call per character - not a collision broadphase. A
+  bullets-vs-crowd test at frame rate is hundreds of core queries per
+  frame, and it is simulation logic anyway, which lives in plain
+  TypeScript with no layer in sight (core's "keep the simulation out of
+  the renderer"): the app's own arrays, a uniform grid over them,
+  runnable headless. Tile-layer collision (tiles are baked records, not
+  nodes) is a solid-cell grid query of its own, not the sprite index.
 - Records layer: record order is draw order: `removeSprite` shifts every
   later sprite down one slot (copyWithin + index fixup, O(later
   sprites)). Its flush publishes the WHOLE live prefix, not a dirty
@@ -340,14 +493,24 @@ hover, wheel and tap rules headless.
   slot recycles. Do not read style truth from the buffer; getSprite reads
   the JS mirror.
 - `createImage` is the wrong loader for pixel-art atlases: it never forwards
-  sampler options, so it is always `filter: "linear"`. `createAtlas` decodes
-  bytes and passes `filter: "nearest"` through - use it, or `decodeImage` +
-  `createTexture` directly.
+  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.
+- 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).
 - Tint multiplies the sampled texel (`texture * tint`) and the pipeline
   blends with `blend: "alpha"` in record order, the premultiplied composite.
   The atlas is premultiplied because `decodeImage` premultiplies by default;
   an atlas uploaded from straight-alpha pixels (`decodeImage(bytes, { alpha:
-  "straight" })` + `createTexture`) draws color under transparent texels
+  "straight" })` into `createAtlas`) draws color under transparent texels
   as opaque - the classic "keyed-out backdrop becomes a wash" symptom.
 - Every rotation must agree on direction (clockwise, y-down):
   `pointInSprite` in pick.ts with the vertex stage's `iRot`, and

package/README.md

@@ -7,12 +7,12 @@ texture element.
 *Status: experimental. Expect API churn.*
 
 ```tsx
-import { render } from "@solidrt/core"
+import { decodeImage, render } from "@solidrt/core"
 import { createAtlas, grid, Sprite, SpriteLayer } from "@solidrt/2d"
 import sheet from "./sheet.png" with { type: "binary" }
 
-let atlas = createAtlas(sheet, { filter: "nearest" })
-let frames = grid(4, 4, { width: atlas.width, height: atlas.height })
+let atlas = createAtlas(decodeImage(sheet), { filter: "nearest" })
+let frames = grid(atlas, 4, 4)
 
 render(() => (
   <window>

package/examples/README.md

@@ -12,27 +12,52 @@ copy one and adapt it.
   one texture may be) baked into lazily-allocated chunks, flown over by a
   ship-style camera (fixed screen pivot, the world panning and ROTATING
   under it via the `<TileLayer>` camera prop - transform writes, never a
-  re-bake), and a timer editing tiles to show that a `setTile` batch
-  re-bakes only the chunks it touches.
+  re-bake), seeded by ONE `setTiles` rect write over a Uint16Array of
+  frame indices (the layer's `frames` table; -1 where the world is
+  empty, and those chunks never allocate), and a timer editing tiles to
+  show that a `setTile` batch re-bakes only the chunks it touches.
 - `anim.tsx` - frame animation with `createAnimation`: three sprites share
   one looping clip (one clock, stepped by wall time independent of display
   rate) and a one-shot clip holds its last frame and fires `onEnd`.
   Self-asserting - watch the logs for ANIM-OK.
 - `camera.tsx` - the 2d camera (`createCamera2d`) over a world larger than
-  the window, attached at the layer's root (`cam.attach(layer)`): drag
-  empty space to pan with inertia, wheel/pinch to zoom about the pointer,
-  tap empty space to glide there (the layer's `onTap` with `e.sprite`
-  null), tap a sprite to select it, drag a sprite to move it (the sprite
-  stops its down, so the camera never pans under it), F to follow a
-  roaming sprite through a dead zone, R to spin the view, Space to fit the
-  world. The LAYER's `handlers` spread onto its leaf; `update(dt)` from
-  `onFrame` is the only per-frame call. Debug commands `camera`, `mode`,
-  `selected` and `first` drive it headless.
+  the window, driving the layer's one view from an input map the app
+  binds (`camera2dBindings` over the view's pointer feed, bridged from
+  the view's root with `feedPointer`, and any pad): drag empty space to
+  pan with inertia, wheel/pinch to zoom about the pointer, tap empty
+  space to glide there (the view's `onTap` with `e.sprite` null), tap a
+  sprite to select it, drag a sprite to move it (the sprite stops its
+  down, so the camera never pans under it), F to follow a roaming sprite
+  through a dead zone, R to spin the view, Space to fit the world. The
+  VIEW's `handlers` spread onto its leaf; `update(dt)` from `onFrame` is
+  the only per-frame call. Debug commands `camera`, `mode`, `selected`
+  and `first` drive it headless.
 - `pick.tsx` - the event model through the component face: exact
   rotated-rect hit testing topmost-first, `onTap` (the dispatch's own
   click, no slop bookkeeping), a claimed press dragging a sprite under a
   `<Camera2d>` that pans empty space and zooms on wheel, the layer's own
   `onTap` seeing misses with `e.sprite` null (and `tapCount` for double
   taps), and removal through a signal so `<For>` unmounts the `<Sprite>`
-  and the layer recycles the slot. The `state` debug command reads the
-  camera and sprite positions back.
+  and the layer recycles the slot. A corner `<View2d>` inset shows the
+  same sprites again under a `<Camera2d>` of its own (drag or wheel on
+  the inset moves only the inset's camera; a sprite tapped or dragged
+  there responds as in the main view). The `state` debug command reads
+  both cameras and the sprite positions back.
+- `views.tsx` - layer views (`layer.createView`, the only way a layer
+  shows): the world rendered twice from ONE set of sprites - the
+  window-filling main view under a `createCamera2d` and a corner minimap
+  showing the whole world at the fit zoom, a stroked rect outlining the
+  main view rect through `map.project`. A tap on the minimap glides the main camera there (the
+  view's root listener, `e.x`/`e.y` in world pixels), and a tap on a
+  sprite in the minimap selects it as in the main view (the same sprite
+  handlers, the walk ending at the view). Debug commands `state`,
+  `camera`, `selected` and `first` drive it headless.
+- `split-screen.tsx` - one `<SpriteLayer output={false}>` (sprites, no
+  leaf of its own) shown through two `<View2d>` panes filling the window
+  side by side, each with a `<Camera2d>` of its own following one of two
+  roaming sprites through a dead zone, so the two poses differ every
+  frame; wheel zooms a pane alone while its follow keeps tracking, a tap
+  on a sprite in either pane tints it in both (one sprite, two views).
+  Each pane's map binds `gamepad.next()`: the first pad to press any
+  button drives pane 0, the next pane 1. The `cameras` debug command
+  reads both poses back.

package/examples/anim.tsx

@@ -7,7 +7,7 @@
 // The atlas is the core logo sliced 2x2 by grid(): a 4-frame "clip". Real
 // art would slice a sheet the same way and pass a consecutive slice of the
 // frames array per animation.
-import { render } from "@solidrt/core"
+import { decodeImage, render } from "@solidrt/core"
 import { addSprite, createAnimation, createAtlas, createSpriteLayer, getSprite, grid } from "@solidrt/2d"
 import type { Frame, SpriteHandle } from "@solidrt/2d"
 import logoBytes from "./logo.png" with { type: "binary" }
@@ -21,12 +21,10 @@ const LOOP_FPS = 2
 const SHOT_FPS = 5
 
 function App() {
-  let atlas = createAtlas(logoBytes, { label: "logo-atlas" })
-  let frames = grid(2, 2, { width: atlas.width, height: atlas.height })
-  let layer = createSpriteLayer(W, H, atlas.texture, {
-    clearColor: [0.05, 0.05, 0.09, 1],
-    label: "anim",
-  })
+  let atlas = createAtlas(decodeImage(logoBytes), { label: "logo-atlas" })
+  let frames = grid(atlas, 2, 2)
+  let layer = createSpriteLayer(atlas.texture, { label: "anim" })
+  let view = layer.createView({ width: W, height: H, clearColor: [0.05, 0.05, 0.09, 1] })
 
   // Three sprites share the looping clip - one clock steps all of them.
   let looping = createAnimation(frames, LOOP_FPS)
@@ -78,7 +76,7 @@ function App() {
 
   return (
     <window alignItems="center" justifyContent="center">
-      <texture src={layer.texture} width={W} height={H} />
+      <texture src={view.texture} width={W} height={H} />
     </window>
   )
 }

package/examples/camera-probe.tsx

@@ -16,7 +16,7 @@
 // 3. Pointer dispatch round-trips: a pointer at the projected screen
 //    point hits the sprite and reports its world coordinates.
 // 4. Tile chunks bake with the pinned identity camera rotation.
-import { onFrame, render } from "@solidrt/core"
+import { decodeImage, onFrame, render } from "@solidrt/core"
 import { readTexture } from "@solidrt/core/gpu"
 import {
   addSprite,
@@ -53,12 +53,14 @@ function rng(seed: number): () => number {
 }
 
 function App() {
-  let atlas = createAtlas(logoBytes, { label: "logo-atlas" })
-  let frames = grid(2, 2, { width: atlas.width, height: atlas.height })
-  let nodes = createSpriteLayer(W, H, atlas.texture, { label: "cam-nodes" })
-  let records = createRecordLayer(W, H, atlas.texture, { label: "cam-records" })
-  nodes.setCamera(CAM)
-  records.setCamera(CAM)
+  let atlas = createAtlas(decodeImage(logoBytes), { label: "logo-atlas" })
+  let frames = grid(atlas, 2, 2)
+  let nodes = createSpriteLayer(atlas.texture, { label: "cam-nodes" })
+  let records = createRecordLayer(atlas.texture, { label: "cam-records" })
+  let nodeView = nodes.createView({ width: W, height: H, label: "cam-nodes" })
+  let recordView = records.createView({ width: W, height: H, label: "cam-records" })
+  nodeView.setCamera(CAM)
+  recordView.setCamera(CAM)
 
   // The same deterministic population on both layers, kept inside world
   // 20..100 so its reach (~145 with rotation) stays clear of both sample
@@ -103,8 +105,8 @@ function App() {
   }
 
   let shaderCheck = () => {
-    let img = readTexture(nodes.texture)
-    let n = nodes.oversample
+    let img = readTexture(nodeView.texture)
+    let n = nodeView.oversample
     let [sx, sy] = projectCamera(CAM, 320, 320)
     check(sx > 8 && sx < W - 8 && sy > 8 && sy < H - 8, `projected probe on screen (${sx.toFixed(1)}, ${sy.toFixed(1)})`)
     check(alphaAt(img, sx, sy, n) > 0, "probe center opaque at its PROJECTED pixel")
@@ -118,8 +120,8 @@ function App() {
   }
 
   let pixelParity = () => {
-    let a = readTexture(nodes.texture)
-    let b = readTexture(records.texture)
+    let a = readTexture(nodeView.texture)
+    let b = readTexture(recordView.texture)
     if (a.width !== b.width || a.height !== b.height) {
       check(false, `sizes differ: ${a.width}x${a.height} vs ${b.width}x${b.height}`)
       return
@@ -146,7 +148,7 @@ function App() {
     let [sx, sy] = projectCamera(CAM, 320, 320)
     // Synthesize the element event the built-in leaf would deliver (layout
     // null: localX/localY are layer pixels already).
-    nodes.handlers.onPointerDown({
+    nodeView.handlers.onPointerDown({
       localX: sx,
       localY: sy,
       pointerId: 1,
@@ -191,8 +193,8 @@ function App() {
 
   return (
     <window flexDirection="row" alignItems="center" justifyContent="center" gap={8}>
-      <texture src={nodes.texture} width={W} height={H} />
-      <texture src={records.texture} width={W} height={H} />
+      <texture src={nodeView.texture} width={W} height={H} />
+      <texture src={recordView.texture} width={W} height={H} />
     </window>
   )
 }