@solidrt/2d 0.0.52

package/examples/sprites.tsx

@@ -0,0 +1,73 @@
+// The sprite layer at its natural scale: hundreds of sprites bouncing at
+// frame rate, driven imperatively. The component face mounts the layer; the
+// motion loop grabs sprite handles via addSprite and rewrites positions with
+// setSprite from onFrame - signals carry structure, per-frame motion goes
+// straight to the layer (the same split as @solidrt/3d). Whatever moves, the
+// tree holds ONE texture leaf; each setSprite writes the sprite's arena
+// node, and the core flush publishes every moved pose as one coalesced
+// instance-buffer write per frame.
+//
+// The atlas is a real image (core's logo) sliced 2x2 by grid(): four frames,
+// each sprite drawing one quarter. An atlas from raw pixel bytes would use
+// createTexture directly; this path (createAtlas) decodes PNG bytes imported
+// with { type: "binary" }.
+import { onFrame, render } from "@solidrt/core"
+import { addSprite, createAtlas, createSpriteLayer, grid, setSprite } from "@solidrt/2d"
+import logoBytes from "./logo.png" with { type: "binary" }
+
+const COUNT = 500
+const W = 720
+const H = 720
+const SPRITE = 48
+
+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, {
+    capacity: COUNT,
+    clearColor: [0.05, 0.05, 0.09, 1],
+    label: "bounce",
+  })
+
+  // Simulation state lives in plain arrays; the layer holds the published
+  // snapshot of it.
+  let x = new Float32Array(COUNT)
+  let y = new Float32Array(COUNT)
+  let vx = new Float32Array(COUNT)
+  let vy = new Float32Array(COUNT)
+  let sprites = new Array(COUNT)
+  for (let i = 0; i < COUNT; i++) {
+    x[i] = SPRITE / 2 + Math.random() * (W - SPRITE)
+    y[i] = SPRITE / 2 + Math.random() * (H - SPRITE)
+    vx[i] = (Math.random() * 2 - 1) * 3
+    vy[i] = (Math.random() * 2 - 1) * 3
+    sprites[i] = addSprite(layer, {
+      x: x[i],
+      y: y[i],
+      w: SPRITE,
+      h: SPRITE,
+      frame: frames[i % 4],
+      rotation: Math.random() * Math.PI * 2,
+    })
+  }
+
+  onFrame(tick => {
+    for (let i = 0; i < COUNT; i++) {
+      let nx = x[i]! + vx[i]!
+      let ny = y[i]! + vy[i]!
+      if (nx < SPRITE / 2 || nx > W - SPRITE / 2) vx[i] = -vx[i]!
+      else x[i] = nx
+      if (ny < SPRITE / 2 || ny > H - SPRITE / 2) vy[i] = -vy[i]!
+      else y[i] = ny
+      setSprite(sprites[i]!, { x: x[i]!, y: y[i]!, rotation: tick / 1000 + i })
+    }
+  })
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <texture src={layer.texture} width={W} height={H} />
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/tiles.tsx

@@ -0,0 +1,102 @@
+// The baked tile layer: a world of tiles baked into lazily-allocated chunk
+// textures and composited as a few quads, so scrolling and rotating cost
+// transform writes and an unchanged world costs nothing per frame. The
+// world here is BIGGER than one texture is allowed to be (6144px), which is
+// the chunking at work; sparse regions never allocate a chunk at all.
+//
+// The camera flies a ship-style path: a fixed screen pivot near the bottom
+// of the viewport, the world panning and ROTATING under it so the flight
+// heading always points up - the <TileLayer> camera prop with rotation and
+// pivot (a leaf transform, never a re-bake). A timer edits tiles while it
+// runs: beacon markers along the road's center line blink, and each blink's
+// batch of setTile calls re-bakes only the chunks the beacons land in.
+//
+// The atlas is the core logo sliced 2x2 by grid(); a real game would slice
+// a tileset sheet the same way.
+import { createSignal, onFrame, render } from "@solidrt/core"
+import { createAtlas, grid, TileLayer } from "@solidrt/2d"
+import type { TileCamera, TileLayerHandle } from "@solidrt/2d"
+import logoBytes from "./logo.png" with { type: "binary" }
+
+const COLS = 128
+const ROWS = 128
+const TILE = 48
+const VIEW = 720
+const WORLD = COLS * TILE
+
+function App() {
+  let atlas = createAtlas(logoBytes, { label: "logo-atlas" })
+  let frames = grid(2, 2, { width: atlas.width, height: atlas.height })
+
+  let layer!: TileLayerHandle
+  let seed = (l: TileLayerHandle) => {
+    layer = l
+    // A solid ring "road" around the world center: continuous under the
+    // flight path, empty everywhere else - the empty regions are the point,
+    // their chunks never allocate.
+    let c = COLS / 2
+    for (let row = 0; row < ROWS; row++) {
+      for (let col = 0; col < COLS; col++) {
+        let d = Math.hypot(col - c, row - c)
+        if (d > 40 && d < 52) l.setTile(col, row, frames[(col ^ row) % 4]!)
+      }
+    }
+  }
+
+  // Beacon cells on the road's center line every 7.5 degrees; the interval
+  // below blinks them between a marker frame and the road pattern.
+  let beacons: [number, number][] = []
+  for (let k = 0; k < 48; k++) {
+    let a = (k * Math.PI) / 24
+    beacons.push([Math.round(COLS / 2 + Math.cos(a) * 46), Math.round(ROWS / 2 + Math.sin(a) * 46)])
+  }
+
+  // The ship flies the ring: camera x/y follow the circle, rotation keeps
+  // the heading pointing screen-up, the pivot pins the ship's world point
+  // near the viewport bottom. Per-frame camera motion is one signal write
+  // feeding the transform - never a re-bake.
+  let [camera, setCamera] = createSignal<TileCamera>({})
+  onFrame(tick => {
+    let t = tick / 6000
+    let radius = 46 * TILE
+    setCamera({
+      x: WORLD / 2 + Math.cos(t) * radius,
+      y: WORLD / 2 + Math.sin(t) * radius,
+      // Circle tangent heading, rotated so "forward" renders upward.
+      rotation: -(t + Math.PI / 2),
+      zoom: 0.9,
+      pivotX: VIEW / 2,
+      pivotY: VIEW * 0.78,
+    })
+  })
+
+  // Blink the beacons: each 500 ms batch of setTile calls re-bakes only the
+  // chunks the beacons land in - live edits next to the free scrolling.
+  let lit = false
+  setInterval(() => {
+    lit = !lit
+    for (let [col, row] of beacons) layer.setTile(col, row, lit ? frames[3]! : frames[(col ^ row) % 4]!)
+  }, 500)
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <view width={VIEW} height={VIEW} overflow="clip">
+        {/* Ground color: never-written regions render nothing, so the
+            full-bleed backdrop is the container's, not the layer's. */}
+        <d-rect x={0} y={0} w={VIEW} h={VIEW} color="#0d0d17" />
+        <TileLayer
+          cols={COLS}
+          rows={ROWS}
+          tileW={TILE}
+          tileH={TILE}
+          atlas={atlas.texture}
+          camera={camera()}
+          label="tile-world"
+          ref={seed}
+        />
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@solidrt/2d",
+  "version": "0.0.52",
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/wellawaretech",
+  "author": "Antoine van Wel",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src/",
+    "examples/",
+    "AGENTS.md"
+  ],
+  "peerDependencies": {
+    "@solidjs/signals": "2.0.0-rc.1",
+    "@solidrt/core": "0.0.52"
+  }
+}

package/src/atlas.ts

@@ -0,0 +1,52 @@
+// Atlas creation: encoded image bytes to a GPU texture plus its frame table.
+// Thin by design - the frame math lives in frames.ts (pure, checkable) and
+// the texture is an ordinary core texture. createImage is NOT used here: it
+// never forwards sampler options, and pixel-art atlases want
+// `filter: "nearest"` (render small, display big with hard pixels).
+import { createTexture, decodeImage } from "@solidrt/core"
+import type { TextureId } from "@solidrt/core/gpu"
+import type { Frame } from "./frames.ts"
+import { grid } from "./frames.ts"
+import type { GridOptions } from "./frames.ts"
+
+export type Atlas = {
+  /** The atlas texture, sampled by every sprite in layers created over it. */
+  texture: TextureId
+  width: number
+  height: number
+  /** Frames in cell order when created via the grid option, else empty. */
+  frames: Frame[]
+}
+
+export type AtlasOptions = {
+  /**
+   * Sampling: "nearest" is the pixel-art path (hard pixels at any scale),
+   * "linear" (default) the photographic one. Fixed at creation, like every
+   * core texture.
+   */
+  filter?: "nearest" | "linear"
+  /** Slice a uniform sheet at creation: cols x rows of equal cells. */
+  grid?: { cols: number; rows: number } & Omit<GridOptions, "width" | "height">
+  label?: string
+  /** Skip the owner-scoped auto-free (the core createTexture contract). */
+  autoFree?: boolean
+}
+
+/**
+ * Decode encoded image bytes (PNG, JPEG, ...) into an atlas texture. Bytes
+ * come from `import sheet from "./sheet.png" with { type: "binary" }` or
+ * `await file("assets/sheet.png").bytes()`. Freed with the owning reactive
+ * scope like any core texture (opt out with `{ autoFree: false }`).
+ */
+export function createAtlas(bytes: Uint8Array, opts?: AtlasOptions): Atlas {
+  let decoded = decodeImage(bytes)
+  let texture = createTexture(decoded.data, decoded.width, decoded.height, {
+    filter: opts?.filter ?? "linear",
+    label: opts?.label ?? "atlas",
+    autoFree: opts?.autoFree,
+  })
+  let frames = opts?.grid
+    ? grid(opts.grid.cols, opts.grid.rows, { ...opts.grid, width: decoded.width, height: decoded.height })
+    : []
+  return { texture, width: decoded.width, height: decoded.height, frames }
+}

package/src/components.tsx

@@ -0,0 +1,287 @@
+// The Solid face: PascalCase components over context, syncing the retained
+// layer (layer.ts) - no new intrinsic elements, no renderer changes. Props
+// follow the Solid 2.0 model (reactive values, no destructuring); effects
+// write into the retained records and the runtime's dirty flush renders.
+// Anything moving at frame rate can bypass the declarative layer: grab the
+// sprite with `ref` and call setSprite from onFrame - signals carry
+// structure and slow state, per-frame motion goes straight to the layer.
+// The same split, with the same reasoning, as @solidrt/3d's components.
+import { createContext, createEffect, createSignal, For, onCleanup, untrack, useContext } from "@solidrt/core"
+import type { Element, ParentComponent, TextureId, VoidComponent } from "@solidrt/core"
+import type { FilterMode } from "@solidrt/core/gpu"
+import { addGroup, addSprite, createSpriteLayer, removeGroup, removeSprite, setGroup, setGroupTransition, setSprite, setSpriteTransition } from "./layer.ts"
+import type { NodeTransition } from "flux:spatial"
+import type { CameraUpdate, Sprite as SpriteHandle, SpriteGroup, SpriteLayer as LayerHandle, SpriteOptions, SpritePointerEvent, TransitionEndEvent } from "./layer.ts"
+import { createTileLayer } from "./tiles.ts"
+import type { TileChunk, TileLayer as TileLayerHandle } from "./tiles.ts"
+
+let LayerContext = createContext<LayerHandle>()
+
+/**
+ * The enclosing layer - the imperative escape hatch inside a component
+ * subtree (throws outside a `<SpriteLayer>`).
+ */
+export function useSpriteLayer(): LayerHandle {
+  return useContext(LayerContext)
+}
+
+export type SpritePointerProps = {
+  onPointerDown?: (event: SpritePointerEvent) => void
+  onPointerMove?: (event: SpritePointerEvent) => void
+  onPointerUp?: (event: SpritePointerEvent) => void
+  onPointerEnter?: (event: SpritePointerEvent) => void
+  onPointerLeave?: (event: SpritePointerEvent) => void
+}
+
+export type SpriteLayerProps = {
+  /** Layer pixels. With `output`, the leaf's own width/height are layout, so
+   * render size and display size separate. */
+  width: number
+  height: number
+  /** The atlas texture every sprite samples (create with createAtlas). */
+  atlas: TextureId
+  /** Initial record reservation (grows on demand); default 1024. */
+  capacity?: number
+  clearColor?: [number, number, number, number]
+  /** Pan/zoom over the world; a shared-params write, never per-sprite. */
+  camera?: CameraUpdate
+  label?: string
+  ref?: (layer: LayerHandle) => void
+  /**
+   * Compose the output yourself: called once (untracked) with the layer's
+   * texture id, and its return renders in place of the built-in `<texture>`
+   * leaf. Sprite pointer events then need the layer's handlers on your
+   * leaf: `<texture src={texture} {...useSpriteLayer().handlers} />`.
+   */
+  output?: (texture: TextureId) => Element
+  /**
+   * Sprite pointer events (default on): the built-in leaf carries
+   * layer.handlers. `false` detaches them - the leaf then costs no pointer
+   * routing at all.
+   */
+  events?: boolean
+}
+
+/**
+ * Owns a sprite layer and composites it as an ordinary `<texture>` leaf, so
+ * the output takes layout, transforms, blendMode, and pointer events like
+ * any element - or hand `output` the texture id and compose it yourself.
+ * Children (`<Sprite>`) render nothing themselves - they populate the
+ * retained layer through context.
+ */
+export let SpriteLayer: ParentComponent<SpriteLayerProps> = props => {
+  let layer = untrack(() =>
+    createSpriteLayer(props.width, props.height, props.atlas, {
+      capacity: props.capacity,
+      clearColor: props.clearColor,
+      label: props.label,
+    }),
+  )
+  createEffect(
+    () => [props.width, props.height] as const,
+    ([w, h]) => layer.setSize(w, h),
+  )
+  createEffect(
+    () => props.camera,
+    camera => {
+      if (camera) layer.setCamera(camera)
+    },
+  )
+  untrack(() => props.ref)?.(layer)
+  let output = untrack(() => props.output)
+  let events = untrack(() => props.events) !== false
+  return (
+    <LayerContext value={layer}>
+      {output ? (
+        untrack(() => output(layer.texture))
+      ) : (
+        <texture
+          src={layer.texture}
+          width={props.width}
+          height={props.height}
+          onPointerDown={events ? layer.handlers.onPointerDown : undefined}
+          onPointerMove={events ? layer.handlers.onPointerMove : undefined}
+          onPointerUp={events ? layer.handlers.onPointerUp : undefined}
+          onPointerLeave={events ? layer.handlers.onPointerLeave : undefined}
+        />
+      )}
+      {props.children}
+    </LayerContext>
+  )
+}
+
+let GroupContext = createContext<SpriteGroup | null>(null)
+
+export type GroupProps = {
+  /** Position in the parent frame (layer pixels at the root). */
+  x?: number
+  y?: number
+  /** Rotation, radians, clockwise. */
+  rotation?: number
+  /** Uniform scale on the whole subtree (child sprites scale with it). */
+  scale?: number
+  /** How pose-prop changes animate (see setGroupTransition); the mount
+   * pose always snaps. */
+  transition?: NodeTransition | string | null
+  /** A declared transition settled on one component. */
+  onTransitionEnd?: (event: TransitionEndEvent) => void
+  ref?: (group: SpriteGroup) => void
+}
+
+/**
+ * A transform group: `<Sprite>` (and nested `<Group>`) children mount under
+ * its spatial arena node, so their pose props read in the group's frame and
+ * moving the group moves the subtree in one native recompute - a ship with
+ * turrets is one `<Group>` with the hull and turret sprites inside. Renders
+ * nothing itself.
+ */
+export let Group: ParentComponent<GroupProps> = props => {
+  let layer = useContext(LayerContext)
+  let parent = useContext(GroupContext)
+  let group = untrack(() => addGroup(layer, { parent }))
+  createEffect(
+    () => [props.x, props.y, props.rotation, props.scale] as const,
+    ([x, y, rotation, scale]) => setGroup(group, { x, y, rotation, scale }),
+  )
+  // After the pose effect, so the mount pose snaps before writes animate.
+  createEffect(
+    () => props.transition,
+    transition => setGroupTransition(group, transition ?? null),
+  )
+  createEffect(
+    () => props.onTransitionEnd,
+    end => {
+      group.onTransitionEnd = end
+    },
+  )
+  untrack(() => props.ref)?.(group)
+  onCleanup(() => removeGroup(group))
+  return <GroupContext value={group}>{props.children}</GroupContext>
+}
+
+export type SpriteProps = SpriteOptions &
+  SpritePointerProps & {
+    /** How pose-prop changes animate (see setSpriteTransition); the mount
+     * pose always snaps. */
+    transition?: NodeTransition | string | null
+    /** A declared transition settled on one component. */
+    onTransitionEnd?: (event: TransitionEndEvent) => void
+    ref?: (sprite: SpriteHandle) => void
+  }
+
+/** One sprite: a frame drawn at a position (in the enclosing `<Group>`'s
+ * frame when there is one). */
+export let Sprite: VoidComponent<SpriteProps> = props => {
+  let layer = useContext(LayerContext)
+  let parent = useContext(GroupContext)
+  let sprite = untrack(() => addSprite(layer, parent ? { parent } : undefined))
+  createEffect(
+    () => [props.x, props.y, props.w, props.h, props.frame, props.rotation, props.tint] as const,
+    ([x, y, w, h, frame, rotation, tint]) => setSprite(sprite, { x, y, w, h, frame, rotation, tint }),
+  )
+  // After the pose effect, so the mount pose snaps before writes animate.
+  createEffect(
+    () => props.transition,
+    transition => setSpriteTransition(sprite, transition ?? null),
+  )
+  createEffect(
+    () => [props.onPointerDown, props.onPointerMove, props.onPointerUp, props.onPointerEnter, props.onPointerLeave, props.onTransitionEnd] as const,
+    ([down, move, up, enter, leave, end]) => {
+      sprite.onPointerDown = down
+      sprite.onPointerMove = move
+      sprite.onPointerUp = up
+      sprite.onPointerEnter = enter
+      sprite.onPointerLeave = leave
+      sprite.onTransitionEnd = end
+    },
+  )
+  untrack(() => props.ref)?.(sprite)
+  onCleanup(() => removeSprite(sprite))
+  return null
+}
+
+/**
+ * The tile layer's camera: the world point (`x`, `y`) is shown at the
+ * viewport point (`pivotX`, `pivotY`), the world scaled by `zoom` and
+ * rotated by `rotation` (radians, clockwise) ABOUT that pivot. The pivot
+ * defaults to (0, 0), which makes `{ x, y, zoom }` mean exactly what the
+ * sprite layer's camera means (world at the viewport top-left) - one
+ * signal drives both. The whole thing is a transform on the composited
+ * world, never a re-bake. (The sprite layer's camera cannot rotate yet -
+ * okf/backlog/2d-sprite-camera-rotation.md.)
+ */
+export type TileCamera = CameraUpdate & {
+  rotation?: number
+  pivotX?: number
+  pivotY?: number
+}
+
+export type TileLayerProps = {
+  /** Grid shape and tile pixel size - creation-fixed (recreate to resize). */
+  cols: number
+  rows: number
+  tileW: number
+  tileH: number
+  /** The atlas texture every tile samples (create with createAtlas). */
+  atlas: TextureId
+  /** Per-chunk clear color; never-written regions render nothing, so a
+   * full-bleed ground color belongs on the container behind the layer. */
+  clearColor?: [number, number, number, number]
+  /** Sampler filter for the baked chunk textures; "nearest" for pixel art. */
+  filter?: FilterMode
+  /** Chunk edge in tiles (default ~512px worth); see TileLayerOptions. */
+  chunkTiles?: number
+  /**
+   * Pan/zoom/rotate over the world - a transform on the composited world
+   * view, never a re-bake. The world view is WORLD sized; put the layer
+   * inside a clipping container (`overflow="clip"`) sized to the viewport.
+   */
+  camera?: TileCamera
+  label?: string
+  ref?: (layer: TileLayerHandle) => void
+}
+
+/**
+ * Owns a baked tile layer (createTileLayer) and composites its chunks as
+ * `d-texture` leaves at their world rects inside a `<view>` carrying the
+ * camera transform - a handful of quads however many tiles exist. Tiles
+ * are data, not children: write them through `ref` with `setTile` - there
+ * is no `<Tile>` component on purpose (a component per tile would
+ * re-introduce the per-element cost the bake removes).
+ */
+export let TileLayer: VoidComponent<TileLayerProps> = props => {
+  let layer = untrack(() =>
+    createTileLayer(props.cols, props.rows, props.tileW, props.tileH, props.atlas, {
+      clearColor: props.clearColor,
+      filter: props.filter,
+      chunkTiles: props.chunkTiles,
+      label: props.label,
+    }),
+  )
+  untrack(() => props.ref)?.(layer)
+  // Chunk allocations arrive through the layer's hook; the signal carries a
+  // fresh array so <For> sees the growth.
+  let [chunks, setChunks] = createSignal<TileChunk[]>(layer.chunks.slice())
+  layer.onChunk = () => setChunks(layer.chunks.slice())
+  // World -> screen: p maps to pivot + R(rotation) * zoom * (p - camera),
+  // spelled with element transforms as origin at the camera point, rotate +
+  // scale there, then translate the camera point onto the pivot.
+  let camX = () => props.camera?.x ?? 0
+  let camY = () => props.camera?.y ?? 0
+  return (
+    <view
+      width={layer.width}
+      height={layer.height}
+      originX={camX()}
+      originY={camY()}
+      rotate={props.camera?.rotation ?? 0}
+      scale={props.camera?.zoom ?? 1}
+      x={(props.camera?.pivotX ?? 0) - camX()}
+      y={(props.camera?.pivotY ?? 0) - camY()}
+    >
+      <For each={chunks()}>
+        {chunk => <d-texture src={chunk.texture} x={chunk.x} y={chunk.y} w={chunk.width} h={chunk.height} />}
+      </For>
+    </view>
+  )
+}

package/src/frames.ts

@@ -0,0 +1,78 @@
+// Atlas frame math, pure: names and grid coordinates to normalized UV rects.
+// No GPU or GUI imports, so the checks rig (checks/frames-check.ts) exercises
+// this module headless on the flux binary.
+
+/**
+ * One atlas frame as normalized UVs: the rect [u0, v0] to [u1, v1] with
+ * top-left origin (the texture pixel contract), u right, v down.
+ */
+export type Frame = { u0: number; v0: number; u1: number; v1: number }
+
+export type GridOptions = {
+  /** Pixel size of the atlas the pixel-space options below refer to. */
+  width: number
+  height: number
+  /** Cell size in pixels; defaults to width/cols x height/rows. */
+  cellW?: number
+  cellH?: number
+  /** Pixel gap between cells (not around the edge); default 0. */
+  spacing?: number
+  /** Pixel offset of the first cell from the top-left corner; default 0. */
+  marginX?: number
+  marginY?: number
+}
+
+/**
+ * Slice a uniform sprite sheet into frames, row-major (left to right, then
+ * top to bottom) - the layout every sheet packer and pixel-art tool emits.
+ * Frames are returned in cell order, so `frames[row * cols + col]` addresses
+ * a cell and an animation is a slice of consecutive indices.
+ */
+export function grid(cols: number, rows: number, opts: GridOptions): Frame[] {
+  if (!(cols > 0 && rows > 0 && Number.isInteger(cols) && Number.isInteger(rows))) {
+    throw new Error(`grid: cols and rows must be positive integers, got ${cols} x ${rows}`)
+  }
+  let { width, height, spacing = 0, marginX = 0, marginY = 0 } = opts
+  if (!(width > 0 && height > 0)) {
+    throw new Error(`grid: atlas size must be positive, got ${width} x ${height}`)
+  }
+  let cellW = opts.cellW ?? (width - marginX * 2 - spacing * (cols - 1)) / cols
+  let cellH = opts.cellH ?? (height - marginY * 2 - spacing * (rows - 1)) / rows
+  if (!(cellW > 0 && cellH > 0)) {
+    throw new Error(`grid: derived cell size ${cellW} x ${cellH} is not positive`)
+  }
+  let frames: Frame[] = []
+  for (let row = 0; row < rows; row++) {
+    for (let col = 0; col < cols; col++) {
+      let x = marginX + col * (cellW + spacing)
+      let y = marginY + row * (cellH + spacing)
+      frames.push({ u0: x / width, v0: y / height, u1: (x + cellW) / width, v1: (y + cellH) / height })
+    }
+  }
+  return frames
+}
+
+/**
+ * Name frames from a pixel-rect map: `{ hero: [x, y, w, h], ... }` in atlas
+ * pixels to `{ hero: Frame, ... }`. The named counterpart of `grid` for
+ * hand-packed or tool-exported sheets.
+ */
+export function namedFrames<K extends string>(
+  atlasW: number,
+  atlasH: number,
+  rects: Record<K, [number, number, number, number]>,
+): Record<K, Frame> {
+  if (!(atlasW > 0 && atlasH > 0)) {
+    throw new Error(`namedFrames: atlas size must be positive, got ${atlasW} x ${atlasH}`)
+  }
+  let out = {} as Record<K, Frame>
+  for (let name in rects) {
+    let [x, y, w, h] = rects[name]
+    if (!(w > 0 && h > 0)) throw new Error(`namedFrames: frame '${name}' has non-positive size ${w} x ${h}`)
+    out[name] = { u0: x / atlasW, v0: y / atlasH, u1: (x + w) / atlasW, v1: (y + h) / atlasH }
+  }
+  return out
+}
+
+/** The whole texture as one frame (a plain image used as a sprite). */
+export const FULL_FRAME: Frame = { u0: 0, v0: 0, u1: 1, v1: 1 }

package/src/index.ts

@@ -0,0 +1,29 @@
+// @solidrt/2d - an instanced sprite layer above @solidrt/core/gpu.
+// One atlas, N quads in one draw. The live layer (createSpriteLayer/
+// addSprite) backs every sprite with a SPATIAL ARENA node whose Pose2D
+// record sink writes the pose instance buffer at the core flush, so core
+// producers reach sprites and picking walks the core BVH; style stays a
+// JS-written second instance buffer. The records layer (createRecordLayer)
+// is the raw escape hatch for motion only JS can compute: 13 JS-owned
+// floats per sprite published through the zero-copy write lease. The baked
+// tile layer (createTileLayer/TileLayer) is the static sibling: a tile
+// world rendered once into textures and composited as a few quads,
+// re-baked on change. Two faces throughout: the imperative core (usable
+// without Solid components) and the components (SpriteLayer/Sprite/Group/
+// TileLayer) on top. See AGENTS.md for the model and the traps.
+
+export { addGroup, addSprite, createSpriteLayer, getSprite, removeGroup, removeSprite, setGroup, setGroupTransition, setSprite, setSpriteParent, setSpriteTransition, POSE_FLOATS, STYLE_FLOATS } from "./layer.ts"
+export { createRecordLayer, FLOATS_PER_SPRITE } from "./records.ts"
+export type { RecordLayer as RecordLayerHandle } from "./records.ts"
+export { pointInSprite } from "./pick.ts"
+export type { AddSpriteOptions, CameraUpdate, GroupOptions, Sprite as SpriteHandle, SpriteGroup, SpriteHandlers, SpriteLayer as SpriteLayerHandle, SpriteLayerOptions, SpriteOptions, SpritePointerEvent, TransitionEndEvent } from "./layer.ts"
+export { createTileLayer } from "./tiles.ts"
+export type { TileChunk, TileLayer as TileLayerHandle, TileLayerOptions } from "./tiles.ts"
+
+export type { NodeTransition, NodeTransitionSpec } from "flux:spatial"
+export { grid, namedFrames, FULL_FRAME } from "./frames.ts"
+export type { Frame, GridOptions } from "./frames.ts"
+export { createAtlas } from "./atlas.ts"
+export type { Atlas, AtlasOptions } from "./atlas.ts"
+export { Group, Sprite, SpriteLayer, TileLayer, useSpriteLayer } from "./components.tsx"
+export type { GroupProps, SpriteLayerProps, SpritePointerProps, SpriteProps, TileCamera, TileLayerProps } from "./components.tsx"