@solidrt/2d 0.0.55 → 0.0.57

package/src/components/tile-layer.tsx

@@ -0,0 +1,160 @@
+import { createEffect, createSignal, displayScale, For, getBoundingBoxViewport, onLayout, untrack } from "@solidrt/core"
+import type { TextureId, VoidComponent } from "@solidrt/core"
+import type { FilterMode } from "@solidrt/core/gpu"
+import type { CameraUpdate } from "../camera.ts"
+import type { Frame } from "../frames.ts"
+import { tileWorldScale } from "../oversample-math.ts"
+import { createTileLayer } from "../tiles.ts"
+import type { TileChunk, TileLayer as TileLayerHandle } from "../tiles.ts"
+import { applyOversample } from "./auto-oversample.ts"
+
+/**
+ * The tile layer's camera - the same CameraUpdate vocabulary as the sprite
+ * layer (see camera.ts for the pivot/rotation semantics and the
+ * heading-upward convention), so one signal drives a whole rotating scene
+ * across both layers. Here the camera is a transform on the composited
+ * world view, never a re-bake; projectCamera/unprojectCamera are the same
+ * mapping as plain functions.
+ */
+export type TileCamera = CameraUpdate
+
+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
+  /** The frames table `setTiles`' index cells name (a tileset, `grid()`'s
+   * array); see TileLayerOptions. Fixed at creation. */
+  frames?: Frame[]
+  /** Per-chunk clear color (the name says the scope: never-written regions
+   * have no chunk and render nothing, so a full-bleed ground color belongs
+   * on the container behind the layer). */
+  chunkClearColor?: [number, number, number, number]
+  /** Sampler filter for the baked chunk textures at composite time; default
+   * "linear" (hard pixels belong to the atlas sampler, see TileLayerOptions). */
+  filter?: FilterMode
+  /**
+   * Target texels per world pixel in the baked chunks. Absent, the component
+   * picks it every layout from the world view's on-screen size (display
+   * scale, camera zoom, any designSize fit), so tiles resample properly at
+   * any scale.
+   */
+  oversample?: number
+  /**
+   * Cap on the auto-picked oversample (integer >= 1): tiles stay adaptive
+   * up to it, never above. A tile world's texture memory is resident chunks
+   * x n squared, so this is the lever that bounds it on high-scale displays
+   * without giving up adaptivity. Ignored when `oversample` is set.
+   */
+  maxOversample?: number
+  /** Chunk edge in tiles (default ~512px worth); see TileLayerOptions. */
+  chunkTiles?: number
+  /**
+   * Layer tint, [r, g, b, a] in 0..1, multiplied over every cell's own
+   * tint (day/night, a dimmed parallax plane). A change re-renders every
+   * resident chunk GPU-side (no record uploads) - drive it from slow
+   * state, not per frame.
+   */
+  tint?: [number, number, number, 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. A layout
+ * component: the world view is laid out, so it cannot sit inside a d-*
+ * subtree. Tiles
+ * are data, not children: write them through `ref` with `setTile` and
+ * `setTiles` - 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, {
+      chunkClearColor: props.chunkClearColor,
+      filter: props.filter,
+      chunkTiles: props.chunkTiles,
+      tint: props.tint,
+      frames: props.frames,
+      label: props.label,
+    }),
+  )
+  untrack(() => props.ref)?.(layer)
+  createEffect(
+    () => props.oversample,
+    n => {
+      if (n !== undefined) layer.setOversample(n)
+    },
+  )
+  createEffect(
+    () => props.tint,
+    tint => {
+      if (tint !== undefined) layer.setTint(tint)
+    },
+  )
+  // Auto oversample: the world view's window box, in device pixels, per
+  // world pixel. Rotation is not a resolution factor - texels per world
+  // pixel do not change as the camera turns - but the measured box is the
+  // AABB of the ROTATED view, which swells by up to sqrt(2) and under an
+  // animated rotation would sweep the scale across an integer boundary,
+  // re-baking every resident chunk on each flip. So the swell is divided
+  // back out for the known camera rotation, leaving displayScale, the
+  // ancestor fit and the camera zoom. The divide-out's basis is the view's
+  // laid-out box, which flexShrink 0 below pins to layer.width x
+  // layer.height: a flex container would otherwise compress the box (the
+  // chunks are detached and draw at world coordinates either way) and the
+  // measurement would mix layout compression into the scale. pick runs
+  // untracked (onLayout handler / effect apply), so its prop reads are
+  // wrapped explicitly.
+  let world: { id: number } | undefined
+  let pick = () =>
+    untrack(() => {
+      if (!world || props.oversample !== undefined) return
+      let box = getBoundingBoxViewport(world)
+      if (!box) return
+      let r = props.camera?.rotation ?? 0
+      let scale = displayScale() * tileWorldScale(box.width, box.height, layer.width, layer.height, r)
+      applyOversample(layer, scale, layer.chunkW, layer.chunkH, props.maxOversample)
+    })
+  onLayout(pick)
+  createEffect(() => [displayScale(), props.maxOversample], pick)
+  // 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) -
+  // projectCamera (camera.ts) spelled with element transforms as origin at
+  // the camera point, rotate + scale there, then translate the camera point
+  // onto the pivot. checks/camera-check.ts holds the two spellings together.
+  let camX = () => props.camera?.x ?? 0
+  let camY = () => props.camera?.y ?? 0
+  return (
+    <view
+      ref={(n: { id: number }) => (world = n)}
+      width={layer.width}
+      height={layer.height}
+      flexShrink={0}
+      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/components/view2d.tsx

@@ -0,0 +1,151 @@
+import { createEffect, displayScale, getBoundingBoxViewport, onCleanup, onLayout, untrack, useContext } from "@solidrt/core"
+import type { Element, ParentComponent, PointerFeed, TextureId } from "@solidrt/core"
+import type { CameraUpdate } from "../camera.ts"
+import { feedPointer } from "../views.ts"
+import type { ViewHandle, ViewOptions } from "../views.ts"
+import { LayerContext, PointerContext, ViewportContext } from "./context.ts"
+import type { LayerPointerProps } from "./sprite-layer.tsx"
+import { applyOversample } from "./auto-oversample.ts"
+
+export type View2dProps = LayerPointerProps &
+  Pick<ViewOptions, "clearColor" | "label"> & {
+    /** View pixels, live (view.setSize). Fixed only, for now: a fill mode
+     * like SpriteLayer's is a later, additive step. */
+    width: number
+    height: number
+    /** Partial camera update on the view's own camera (view.setCamera):
+     * absent keys keep their values. Live. A `<Camera2d>` child writes the
+     * same state - use one form, not both. */
+    camera?: CameraUpdate
+    /**
+     * Target texels per view pixel. Absent, the component picks it every
+     * layout from the built-in leaf's on-screen size, as `<SpriteLayer>`
+     * does; with `output` there is no built-in leaf, so set it yourself.
+     */
+    oversample?: number
+    /** Cap on the auto-picked oversample (see SpriteLayerProps). */
+    maxOversample?: number
+    ref?: (view: ViewHandle) => void
+    /**
+     * Compose the leaf yourself: called once (untracked) with view.texture,
+     * and its return renders in place of the built-in `<texture>` leaf.
+     * Sprite pointer events through the view then need its handlers on
+     * your leaf: `<texture src={texture} {...view.handlers} />` (the view
+     * from `ref`).
+     */
+    output?: (texture: TextureId) => Element
+    /** Pointer events (default on): the built-in leaf carries the view's
+     * handlers. `false` detaches them. */
+    events?: boolean
+    /** The pointer feed of this view (createPointerFeed), fed from the
+     * view's root - the events the sprites let through - so a map bound
+     * to it drives the `<Camera2d>` inside this view and no other; inside,
+     * `useSpriteLayer().pointer` is this feed. Fixed at creation. */
+    pointer?: PointerFeed
+  }
+
+/**
+ * A view of the enclosing layer from a camera of its own (layer.createView
+ * as a component): the same sprites, one more target and one entry, so
+ * it costs no per-frame JS. The `<SpriteLayer>`'s own leaf is one of
+ * these too; a `<SpriteLayer output={false}>` shows ONLY through its
+ * `<View2d>` children (split-screen: two side by side). Composites as an
+ * ordinary `<texture>` leaf at the view size, or through `output`. A
+ * `<Camera2d>`
+ * child drives the VIEW's camera from the map it is given, and the view's
+ * `pointer` feed carries the view's gestures to that map: inside,
+ * `useSpriteLayer()` reports the view as `viewport` and the feed as
+ * `pointer`. `<Sprite>` and
+ * `<Group>` children mount to the layer as they would outside - a view
+ * mirrors the layer's sprites, it has none of its own. Sprites under the
+ * view's leaf get their ordinary pointer handlers, with the view's camera
+ * undone; the view's own `onPointer*`/`onTap` are the last stop of that
+ * walk (`event.sprite` null over empty space).
+ */
+export let View2d: ParentComponent<View2dProps> = props => {
+  let layer = useContext(LayerContext)
+  // The initial props seed createView, so `ref` hands out a configured
+  // view and the first frame draws it whole; the effects follow changes
+  // only (`defer`).
+  let view = untrack(() =>
+    layer.createView({
+      width: props.width,
+      height: props.height,
+      camera: props.camera,
+      oversample: props.oversample,
+      clearColor: props.clearColor,
+      label: props.label,
+    }),
+  )
+  createEffect(
+    () => [props.width, props.height] as const,
+    ([w, h]) => view.setSize(w, h),
+    { defer: true },
+  )
+  createEffect(
+    () => props.camera,
+    camera => {
+      if (camera) view.setCamera(camera)
+    },
+    { defer: true },
+  )
+  createEffect(
+    () => props.oversample,
+    n => {
+      if (n !== undefined) view.setOversample(n)
+    },
+    { defer: true },
+  )
+  untrack(() => props.ref)?.(view)
+  onCleanup(() => view.dispose())
+  let pointer = untrack(() => props.pointer) ?? null
+  if (pointer) onCleanup(feedPointer(view, pointer))
+  // The view's own handlers at the root of the walk; the props are read
+  // per event, so a handler prop may change without re-registering.
+  onCleanup(
+    view.listen({
+      onPointerDown: e => props.onPointerDown?.(e),
+      onPointerMove: e => props.onPointerMove?.(e),
+      onPointerUp: e => props.onPointerUp?.(e),
+      onWheel: e => props.onWheel?.(e),
+      onTap: e => props.onTap?.(e),
+    }),
+  )
+  let output = untrack(() => props.output)
+  let events = untrack(() => props.events) !== false
+  let leaf: { id: number } | undefined
+  // Auto oversample from the built-in leaf's window box, in device pixels,
+  // per view pixel: the same pick as SpriteLayer's fixed mode.
+  let pick = () =>
+    untrack(() => {
+      if (!leaf || props.oversample !== undefined) return
+      let box = getBoundingBoxViewport(leaf)
+      if (!box) return
+      let scale = displayScale() * Math.max(box.width / props.width, box.height / props.height)
+      applyOversample(view, scale, props.width, props.height, props.maxOversample)
+    })
+  onLayout(pick)
+  createEffect(() => [displayScale(), props.maxOversample], pick)
+  return (
+    <ViewportContext value={view}>
+      <PointerContext value={pointer}>
+      {output ? (
+        untrack(() => output(view.texture))
+      ) : (
+        <texture
+          ref={(n: { id: number }) => (leaf = n)}
+          src={view.texture}
+          width={props.width}
+          height={props.height}
+          onPointerDown={events ? view.handlers.onPointerDown : undefined}
+          onPointerMove={events ? view.handlers.onPointerMove : undefined}
+          onPointerUp={events ? view.handlers.onPointerUp : undefined}
+          onPointerLeave={events ? view.handlers.onPointerLeave : undefined}
+          onWheel={events ? view.handlers.onWheel : undefined}
+        />
+      )}
+      {props.children}
+      </PointerContext>
+    </ViewportContext>
+  )
+}

package/src/dispatch.ts

@@ -0,0 +1,231 @@
+// Pointer dispatch behind view.handlers, shared by both layer kinds: the
+// element event model one tree deeper, with the VIEW as the root of the
+// walk. Down, move, up and wheel dispatch on the topmost hit sprite,
+// bubble through its enclosing groups and end at the layer's listeners;
+// over empty space the walk is the layer alone (`sprite` null). Claiming
+// is stopPropagation: a handler that stops an event keeps every later
+// target, the layer included, from seeing it, and the DOWN decides the
+// press - a pointer whose down never reached the layer stays claimed by
+// the sprite chain for its move, up and tap too, so a sprite that drags
+// itself stops its down once and a camera attached at the root never
+// pans. Capture is per pointer to the press target, the layer included: a
+// drag from empty space keeps delivering to the layer as it crosses
+// sprites, exactly as a drag from a sprite keeps naming that sprite.
+// Enter/leave pair on the sprite alone. Taps are synthesized here (DOM's
+// click, Unity's IPointerClickHandler): a press that releases on the same
+// target within the slop, the only pointer down for its whole press,
+// counted up for repeats (DOM's detail, Unity's clickCount).
+//
+// Pure BY DESIGN (types and camera.ts, nothing with GPU imports) so
+// checks/dispatch-check.ts drives it headless with a fake pick.
+
+import type { PointerEvent as ElementPointerEvent } from "@solidrt/core"
+import { unprojectCamera } from "./camera.ts"
+import type { CameraUpdate } from "./camera.ts"
+import type { LayerPointerListener, Sprite, SpriteGroup, SpriteHandlers, SpritePointerEvent } from "./layer.ts"
+import type { ViewHandle } from "./views.ts"
+
+// Finger travel from the down point, in window pixels, past which a press
+// is a drag and never a tap. Core's pan and transform recognizers engage
+// at the same 8, so a press is never both a tap and a pan.
+const TAP_SLOP = 8
+// Successive taps closer in time than this, on the same target and within
+// TAP_REPEAT_SLOP of each other, count up (Unity's 0.3 s clickCount
+// window, Android's double-tap timeout).
+const TAP_INTERVAL_MS = 300
+// Window pixels a repeat tap may land from the previous one and still
+// count: a thumb repeats within about this (Hammer.js uses 10, Android
+// 100 dp); 20 tolerates touch without a mouse double-click spanning
+// neighbouring sprites.
+const TAP_REPEAT_SLOP = 20
+
+export type DispatchDeps = {
+  size: () => [number, number]
+  camera: () => CameraUpdate
+  pick: (x: number, y: number) => Sprite[]
+  /** The view: the walk's root and the listeners' currentTarget. */
+  root: ViewHandle
+  /** The root's listeners, in registration order. */
+  listeners: Set<LayerPointerListener>
+  /** The clock for tap repeats (default performance.now; checks inject). */
+  now?: () => number
+}
+
+type HandlerName = "onPointerDown" | "onPointerMove" | "onPointerUp" | "onWheel" | "onTap"
+
+// One runtime event object serves every view (SpritePointerEvent for the
+// sprite chain, LayerPointerEvent at the root, plus the wheel and tap
+// fields); the public types narrow it per handler.
+type InternalEvent = {
+  sprite: Sprite | null
+  currentTarget: Sprite | SpriteGroup | ViewHandle
+  x: number
+  y: number
+  pointerId: number
+  pointerType: string
+  button?: number
+  shiftKey: boolean
+  ctrlKey: boolean
+  altKey: boolean
+  metaKey: boolean
+  native: ElementPointerEvent
+  deltaX?: number
+  deltaY?: number
+  tapCount?: number
+  _stopped: boolean
+  stopPropagation(): void
+}
+
+// A pointer between its down and up: what it pressed (null = the layer),
+// whether the down reached the root, the down point for the slop, and
+// whether it has been the only pointer down for its whole press.
+type Press = {
+  target: Sprite | null
+  claimed: boolean
+  cx: number
+  cy: number
+  moved: boolean
+  alone: boolean
+}
+
+export function spriteDispatch(deps: DispatchDeps): (layout: (() => { width: number; height: number }) | null) => SpriteHandlers {
+  let now = deps.now ?? (() => performance.now())
+  let presses = new Map<number, Press>()
+  let hover = new Map<number, Sprite>()
+  let lastTap: { time: number; cx: number; cy: number; target: Sprite | null; count: number } | null = null
+
+  // Bubble from the sprite through its groups; then, when the press lets
+  // it, the root's listeners (every one of them - the root is the last
+  // stop, there is nothing left to claim). Returns whether the root ran.
+  let walk = (name: HandlerName, event: InternalEvent, toRoot: boolean): boolean => {
+    for (let n: Sprite | SpriteGroup | null = event.sprite; n !== null && !event._stopped; n = n._parent) {
+      // An inert handle (removed mid-press) has no handlers to run.
+      if (n.layer === null) continue
+      let handler = n[name] as ((event: InternalEvent) => void) | undefined
+      if (handler) {
+        event.currentTarget = n
+        handler(event)
+      }
+    }
+    if (event._stopped || !toRoot) return false
+    event.currentTarget = deps.root
+    for (let listener of deps.listeners) {
+      let handler = listener[name] as ((event: InternalEvent) => void) | undefined
+      if (handler) handler(event)
+    }
+    return true
+  }
+
+  return layout => {
+    let toLayer = (e: ElementPointerEvent): [number, number] => {
+      let x = e.localX
+      let y = e.localY
+      let l = layout?.()
+      let [width, height] = deps.size()
+      if (l && l.width > 0 && l.height > 0) {
+        x *= width / l.width
+        y *= height / l.height
+      }
+      // Undo the camera: screen -> world.
+      return unprojectCamera(deps.camera(), x, y)
+    }
+    let makeEvent = (sprite: Sprite | null, x: number, y: number, e: ElementPointerEvent): InternalEvent => {
+      let event: InternalEvent = {
+        sprite,
+        currentTarget: sprite ?? deps.root,
+        x,
+        y,
+        pointerId: e.pointerId,
+        pointerType: e.pointerType,
+        button: e.button,
+        shiftKey: e.shiftKey,
+        ctrlKey: e.ctrlKey,
+        altKey: e.altKey,
+        metaKey: e.metaKey,
+        native: e,
+        _stopped: false,
+        stopPropagation() {
+          event._stopped = true
+        },
+      }
+      return event
+    }
+    let topmost = (x: number, y: number): Sprite | null => deps.pick(x, y)[0] ?? null
+    // Enter/leave go to one sprite directly, outside the walk: the event
+    // in its sprite view.
+    let hoverEvent = (sprite: Sprite, x: number, y: number, e: ElementPointerEvent): SpritePointerEvent =>
+      makeEvent(sprite, x, y, e) as unknown as SpritePointerEvent
+
+    return {
+      onPointerDown(e) {
+        let [x, y] = toLayer(e)
+        let hit = topmost(x, y)
+        // A second pointer landing ends "alone" for every press in flight.
+        for (let p of presses.values()) p.alone = false
+        let press: Press = { target: hit, claimed: false, cx: e.clientX, cy: e.clientY, moved: false, alone: presses.size === 0 }
+        presses.set(e.pointerId, press)
+        press.claimed = !walk("onPointerDown", makeEvent(hit, x, y, e), true)
+      },
+      onPointerMove(e) {
+        let [x, y] = toLayer(e)
+        let press = presses.get(e.pointerId)
+        if (press) {
+          if (!press.moved && Math.hypot(e.clientX - press.cx, e.clientY - press.cy) >= TAP_SLOP) press.moved = true
+          walk("onPointerMove", makeEvent(press.target, x, y, e), !press.claimed)
+          return
+        }
+        let hit = topmost(x, y)
+        let prev = hover.get(e.pointerId) ?? null
+        if (prev !== hit) {
+          if (prev && prev.layer) prev.onPointerLeave?.(hoverEvent(prev, x, y, e))
+          if (hit) hit.onPointerEnter?.(hoverEvent(hit, x, y, e))
+          if (hit) hover.set(e.pointerId, hit)
+          else hover.delete(e.pointerId)
+        }
+        walk("onPointerMove", makeEvent(hit, x, y, e), true)
+      },
+      onPointerUp(e) {
+        let [x, y] = toLayer(e)
+        let press = presses.get(e.pointerId)
+        if (!press) {
+          // A press this layer never saw go down: deliver to what is
+          // under it, as the element model does.
+          walk("onPointerUp", makeEvent(topmost(x, y), x, y, e), true)
+          return
+        }
+        presses.delete(e.pointerId)
+        walk("onPointerUp", makeEvent(press.target, x, y, e), !press.claimed)
+        // The tap rule: no travel past the slop, alone for the whole
+        // press, released over the target it pressed (empty space for the
+        // layer itself).
+        if (press.moved || !press.alone || topmost(x, y) !== press.target) return
+        let time = now()
+        let repeat =
+          lastTap !== null &&
+          time - lastTap.time <= TAP_INTERVAL_MS &&
+          lastTap.target === press.target &&
+          Math.hypot(e.clientX - lastTap.cx, e.clientY - lastTap.cy) <= TAP_REPEAT_SLOP
+        let count = repeat ? lastTap!.count + 1 : 1
+        lastTap = { time, cx: e.clientX, cy: e.clientY, target: press.target, count }
+        let tap = makeEvent(press.target, x, y, e)
+        tap.tapCount = count
+        walk("onTap", tap, !press.claimed)
+      },
+      onWheel(e) {
+        let [x, y] = toLayer(e)
+        let event = makeEvent(topmost(x, y), x, y, e)
+        event.deltaX = e.deltaX
+        event.deltaY = e.deltaY
+        walk("onWheel", event, true)
+      },
+      onPointerLeave(e) {
+        let [x, y] = toLayer(e)
+        let prev = hover.get(e.pointerId)
+        if (prev) {
+          hover.delete(e.pointerId)
+          if (prev.layer) prev.onPointerLeave?.(hoverEvent(prev, x, y, e))
+        }
+      },
+    }
+  }
+}

package/src/frames.ts

@@ -31,10 +31,14 @@ export function writeFrame(
   data[at + 3] = flipY ? v0 : v1
 }
 
+/**
+ * What the slicers need of an atlas: its pixel size, the space every rect
+ * and gap below is measured in. An `Atlas` fits as it is; a texture from
+ * anywhere else (a render target, a camera) passes `{ width, height }`.
+ */
+export type AtlasSize = { width: number; height: 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
@@ -43,6 +47,29 @@ export type GridOptions = {
   /** Pixel offset of the first cell from the top-left corner; default 0. */
   marginX?: number
   marginY?: number
+  /**
+   * Texels shaved off every side of each frame; default 0. Only a
+   * mipmapped atlas needs it: 2^k texels keep mip level k inside the cell
+   * (the layer shaders already clamp level-0 samples into the frame), at
+   * the cost of that border of every sprite. The stopgap until extrusion
+   * (okf/backlog/2d-atlas-extrude.md).
+   */
+  inset?: number
+}
+
+export type NamedFramesOptions = {
+  /** As GridOptions.inset: texels shaved off every side of each rect. */
+  inset?: number
+}
+
+/** A pixel rect to UVs, shrunk by `inset` on every side; `what` names the throw. */
+function frameOf(atlas: AtlasSize, x: number, y: number, w: number, h: number, inset: number, what: string): Frame {
+  if (!(inset >= 0)) throw new Error(`${what}: inset must be non-negative, got ${inset}`)
+  let iw = w - inset * 2
+  let ih = h - inset * 2
+  if (!(iw > 0 && ih > 0)) throw new Error(`${what}: inset ${inset} leaves no frame of a ${w} x ${h} rect`)
+  let { width, height } = atlas
+  return { u0: (x + inset) / width, v0: (y + inset) / height, u1: (x + inset + iw) / width, v1: (y + inset + ih) / height }
 }
 
 /**
@@ -50,17 +77,23 @@ export type GridOptions = {
  * 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.
+ *
+ * Cells that touch do not bleed at mip level 0: the layer shaders clamp
+ * every sample into its frame (shaders.ts). A mip chain is different - its
+ * texels straddle cell edges before sampling - so a mipmapped sheet packs
+ * a gutter (`spacing`) or shaves its frames (`inset`); see namedFrames.
  */
-export function grid(cols: number, rows: number, opts: GridOptions): Frame[] {
+export function grid(atlas: AtlasSize, 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
+  let { width, height } = atlas
   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
+  let { spacing = 0, marginX = 0, marginY = 0, inset = 0 } = opts ?? {}
+  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`)
   }
@@ -69,7 +102,7 @@ export function grid(cols: number, rows: number, opts: GridOptions): Frame[] {
     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 })
+      frames.push(frameOf(atlas, x, y, cellW, cellH, inset, "grid"))
     }
   }
   return frames
@@ -78,21 +111,37 @@ export function grid(cols: number, rows: number, opts: GridOptions): Frame[] {
 /**
  * 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.
+ * hand-packed or tool-exported sheets. The key union comes from the table
+ * you pass: an object literal (or a built table with `satisfies Record<...>`
+ * on the literal) gives a record whose every name is checked; a table
+ * typed `Record<string, ...>` gives back an index signature, so every name
+ * compiles, a typo included, and no `!` is needed on a lookup - the
+ * scaffold's tsconfig does not set noUncheckedIndexedAccess.
+ *
+ * The oldest atlas trap - frames addressed as whole-pixel rects that share
+ * an edge bleed into each other, a sprite drifting by fractions of a pixel
+ * flashing a one-texel line of the cell next door - is handled in the
+ * layer shaders, which clamp every sample into its frame. What they cannot
+ * handle is a mip chain, whose texels average across cell edges before
+ * sampling: a mipmapped sheet passes `inset` (2^k texels keeps level k
+ * clean, losing that border) or packs a gutter, until extrusion lands
+ * (okf/backlog/2d-atlas-extrude.md).
  */
 export function namedFrames<K extends string>(
-  atlasW: number,
-  atlasH: number,
+  atlas: AtlasSize,
   rects: Record<K, [number, number, number, number]>,
+  opts?: NamedFramesOptions,
 ): Record<K, Frame> {
-  if (!(atlasW > 0 && atlasH > 0)) {
-    throw new Error(`namedFrames: atlas size must be positive, got ${atlasW} x ${atlasH}`)
+  let { width, height } = atlas
+  if (!(width > 0 && height > 0)) {
+    throw new Error(`namedFrames: atlas size must be positive, got ${width} x ${height}`)
   }
+  let inset = opts?.inset ?? 0
   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 }
+    out[name] = frameOf(atlas, x, y, w, h, inset, `namedFrames: frame '${name}'`)
   }
   return out
 }