@solidrt/2d 0.0.52 → 0.0.54

package/AGENTS.md

@@ -43,6 +43,12 @@ moved subtrees in Rust, and picking walks the core BVH.
   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
   sprites). Child sprite pose fields are local to the group.
+- `flipX`/`flipY` mirror on the UV SIDE: the style/record write swaps
+  u0/u1 (v0/v1), so w/h stay the drawn size, a scale transition never sees
+  a flip, and picking is unchanged (the vertex stage still carries no
+  flip). The flags live on the Sprite and re-apply to every later frame
+  write; `getSprite` returns the frame un-mirrored plus the flags. Raw
+  `records` writers swap u0/u1 themselves.
 - Mutations batch to a microtask: style lease publish + count setDraw +
   `spatial.flush()`. No mutation, no publish, no frame: a static layer
   costs zero, the same demand-gate story as the rest of the platform.
@@ -117,10 +123,10 @@ chunks on approach, evict) - okf/backlog/2d-baked-layers.md.
 
 | Component | Props |
 |---|---|
-| `SpriteLayer` | width, height (layer pixels), atlas (TextureId), capacity?, clearColor?, camera?, label?, ref?, output?, events? |
+| `SpriteLayer` | width, height (layer pixels), atlas (TextureId), capacity?, clearColor?, camera?, oversample?, label?, ref?, output?, events? |
 | `Sprite` | x, y (center; local to the enclosing `<Group>`), w, h, frame?, rotation? (radians, clockwise), tint? ([r,g,b,a] 0..1), transition?, onPointer{Down,Move,Up,Enter,Leave}?, ref? |
 | `Group` | x?, y?, rotation?, scale? (uniform, scales the subtree), transition?, ref? |
-| `TileLayer` | cols, rows, tileW, tileH, atlas (TextureId), clearColor?, filter?, chunkTiles?, camera? (TileCamera: x, y, zoom, rotation, pivotX, pivotY), label?, ref? |
+| `TileLayer` | cols, rows, tileW, tileH, atlas (TextureId), clearColor?, filter?, chunkTiles?, oversample?, 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
@@ -176,12 +182,11 @@ is flat. Event x/y are layer pixels with the camera undone.
   bytes and passes `filter: "nearest"` through - use it, or `decodeImage` +
   `createTexture` directly.
 - Tint multiplies the sampled texel (`texture * tint`) and the pipeline
-  blends with `blend: "alpha"` in record order. The layer's OUTPUT obeys the
-  premultiplied-alpha contract to the extent the atlas does: PNG decode
-  yields straight alpha, and a translucent texel tinted translucent can
-  composite slightly wrong at the edges. Opaque-or-transparent pixel art
-  (the overwhelming case) is exact. A premultiply-on-decode option is the
-  fix if it ever matters; note it, do not silently add it.
+  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
+  as opaque - the classic "keyed-out backdrop becomes a wash" symptom.
 - `pointInSprite` in pick.ts and the vertex stage's rotation must agree on
   direction (clockwise, y-down). The differential check (pick-check.ts)
   guards the math against an oracle but NOT against the shader - if you
@@ -196,14 +201,39 @@ is flat. Event x/y are layer pixels with the camera undone.
 - `<TileLayer>`'s world view is WORLD sized (cols * tileW) and takes that
   much layout space: put it inside a clipping container (`overflow="clip"`)
   sized to the viewport, or camera panning shows the world hanging out of
-  the box.
+  the box. Both layers render LAID-OUT elements (`<TileLayer>` a `<view>`,
+  `<SpriteLayer>` a `<texture>` leaf) and take no position props, so to
+  overlay sprites on tiles wrap each in a `<view position="absolute">`
+  inside that container - as plain flex siblings they stack side by side
+  instead.
+  Both are LAYOUT components: neither can live inside a d-* subtree (the
+  insert throws); for a detached parent, `<SpriteLayer output>` hands out
+  the texture id for a `<d-texture>` of your own.
 - `clearColor` is PER CHUNK: never-written regions have no chunk and render
   nothing, so a full-bleed ground color belongs on the container behind the
   layer (a `d-rect` under it), not on clearColor.
-- Tile layer zoom/rotation scale the BAKED chunk textures at composite time
-  (the sprite layer's zoom re-samples the atlas in-shader), so the tile
-  layer's `filter` option is what pixel art must set to "nearest" - on top
-  of the atlas's own nearest from createAtlas; they are different samplers.
+- Two samplers, two jobs. The ATLAS sampler (createAtlas `filter`) decides
+  whether texels are hard blocks ("nearest", pixel art) or smooth
+  ("linear"). The LAYER's output sampler (the sprite layer's target, the
+  tile layer's `filter` option, default "linear") does the composite
+  resample to the box, and stays linear: "nearest" there snaps texels to
+  uneven widths at any fractional scale (a 3.6x designSize fit draws
+  source pixels 3 or 4 device pixels wide - shimmer standing still, boil
+  when scrolling). Proper resampling at a fractional or HiDPI scale is the
+  `oversample` factor: the layer renders at n texels per layer pixel
+  (nearest inside keeps blocks square), the linear composite spreads the
+  fraction over one device pixel at block edges. The components pick n
+  every layout from their leaf's window box (`getBoundingBoxViewport` x
+  `displayScale()`, which composes designSize fits and camera zoom), within
+  a budget of the window's own device pixel count; the
+  primitives default to 1 and take `{ oversample }` / `setOversample(n)`
+  - with `output` on `<SpriteLayer>` there is no built-in leaf, so set it
+  yourself. Never fix a shimmer by snapping the fit to an integer: the
+  scene should fill its box at any ratio.
+- Retro scrolling habits are the app's, not the layer's: keep the camera
+  fractional (rounding it to design pixels makes motion step at the
+  rounding rate, not the frame rate), and a game that wants whole-pixel
+  scrolling snaps its own camera.
 - A dirty chunk flush publishes and re-bakes that chunk in full. Fine on
   change-only cadence; per-frame setTile churn re-bakes chunks per frame -
   that is sprite-layer work, not tile work.

package/examples/sprites.tsx

@@ -48,6 +48,10 @@ function App() {
       h: SPRITE,
       frame: frames[i % 4],
       rotation: Math.random() * Math.PI * 2,
+      // A sprite faces its motion: mirrored on the UV side, so the flip is
+      // free of the pose and instant under any transition.
+      flipX: vx[i]! < 0,
+      flipY: vy[i]! < 0,
     })
   }
 
@@ -55,10 +59,14 @@ function App() {
     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
+      if (nx < SPRITE / 2 || nx > W - SPRITE / 2) {
+        vx[i] = -vx[i]!
+        setSprite(sprites[i]!, { flipX: vx[i]! < 0 })
+      } else x[i] = nx
+      if (ny < SPRITE / 2 || ny > H - SPRITE / 2) {
+        vy[i] = -vy[i]!
+        setSprite(sprites[i]!, { flipY: vy[i]! < 0 })
+      } else y[i] = ny
       setSprite(sprites[i]!, { x: x[i]!, y: y[i]!, rotation: tick / 1000 + i })
     }
   })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/2d",
-  "version": "0.0.52",
+  "version": "0.0.54",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -15,7 +15,7 @@
     "AGENTS.md"
   ],
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-rc.1",
-    "@solidrt/core": "0.0.52"
+    "@solidjs/signals": "2.0.0-rc.3",
+    "@solidrt/core": "0.0.54"
   }
 }

package/src/components.tsx

@@ -6,12 +6,21 @@
 // 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 { createContext, createEffect, createSignal, displayScale, For, getBoundingBoxViewport, onCleanup, onLayout, untrack, useContext, windowSize } 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 { fitOversample } from "./oversample.ts"
+
+// The window's device pixel count: the texel budget an auto-picked
+// oversample target stays within (see fitOversample).
+function windowTexels(): number {
+  let win = windowSize()
+  let scale = displayScale()
+  return win.width * scale * (win.height * scale)
+}
 import { createTileLayer } from "./tiles.ts"
 import type { TileChunk, TileLayer as TileLayerHandle } from "./tiles.ts"
 
@@ -45,6 +54,13 @@ export type SpriteLayerProps = {
   clearColor?: [number, number, number, number]
   /** Pan/zoom over the world; a shared-params write, never per-sprite. */
   camera?: CameraUpdate
+  /**
+   * Target texels per layer pixel. Absent, the component picks it every
+   * layout from the built-in leaf's on-screen size (display scale, any
+   * designSize fit, layout scaling), so the layer resamples properly at any
+   * scale; with `output` there is no built-in leaf, so set it yourself.
+   */
+  oversample?: number
   label?: string
   ref?: (layer: LayerHandle) => void
   /**
@@ -66,6 +82,8 @@ export type SpriteLayerProps = {
  * 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.
+ * A layout component: it cannot sit inside a d-* subtree; `output` with a
+ * `<d-texture>` is the detached form.
  * Children (`<Sprite>`) render nothing themselves - they populate the
  * retained layer through context.
  */
@@ -87,15 +105,37 @@ export let SpriteLayer: ParentComponent<SpriteLayerProps> = props => {
       if (camera) layer.setCamera(camera)
     },
   )
+  createEffect(
+    () => props.oversample,
+    n => {
+      if (n !== undefined) layer.setOversample(n)
+    },
+  )
   untrack(() => props.ref)?.(layer)
   let output = untrack(() => props.output)
   let events = untrack(() => props.events) !== false
+  // Auto oversample: the built-in leaf's window box, in device pixels, per
+  // layer pixel. Picked after every layout, and again when the display scale
+  // changes: the first layout runs before the resize event that reports the
+  // scale, and a scale change alone lays nothing out. onLayout is not a
+  // tracking scope; the reads there are plain.
+  let leaf: { id: number } | undefined
+  let pick = () => {
+    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)
+    layer.setOversample(fitOversample(scale, props.width, props.height, windowTexels()))
+  }
+  onLayout(pick)
+  createEffect(() => displayScale(), pick)
   return (
     <LayerContext value={layer}>
       {output ? (
         untrack(() => output(layer.texture))
       ) : (
         <texture
+          ref={(n: { id: number }) => (leaf = n)}
           src={layer.texture}
           width={props.width}
           height={props.height}
@@ -176,8 +216,8 @@ export let Sprite: VoidComponent<SpriteProps> = props => {
   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 }),
+    () => [props.x, props.y, props.w, props.h, props.frame, props.flipX, props.flipY, props.rotation, props.tint] as const,
+    ([x, y, w, h, frame, flipX, flipY, rotation, tint]) => setSprite(sprite, { x, y, w, h, frame, flipX, flipY, rotation, tint }),
   )
   // After the pose effect, so the mount pose snaps before writes animate.
   createEffect(
@@ -227,8 +267,16 @@ export type TileLayerProps = {
   /** 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. */
+  /** 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
   /** Chunk edge in tiles (default ~512px worth); see TileLayerOptions. */
   chunkTiles?: number
   /**
@@ -244,7 +292,9 @@ export type TileLayerProps = {
 /**
  * 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
+ * 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` - there
  * is no `<Tile>` component on purpose (a component per tile would
  * re-introduce the per-element cost the bake removes).
@@ -259,6 +309,25 @@ export let TileLayer: VoidComponent<TileLayerProps> = props => {
     }),
   )
   untrack(() => props.ref)?.(layer)
+  createEffect(
+    () => props.oversample,
+    n => {
+      if (n !== undefined) layer.setOversample(n)
+    },
+  )
+  // Auto oversample: the world view's window box (camera zoom and rotation
+  // included - a rotated world's AABB over-estimates, which only rounds up),
+  // in device pixels, per world pixel.
+  let world: { id: number } | undefined
+  let pick = () => {
+    if (!world || props.oversample !== undefined) return
+    let box = getBoundingBoxViewport(world)
+    if (!box) return
+    let scale = displayScale() * Math.max(box.width / layer.width, box.height / layer.height)
+    layer.setOversample(fitOversample(scale, layer.chunkW, layer.chunkH, windowTexels()))
+  }
+  onLayout(pick)
+  createEffect(() => displayScale(), 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())
@@ -270,6 +339,7 @@ export let TileLayer: VoidComponent<TileLayerProps> = props => {
   let camY = () => props.camera?.y ?? 0
   return (
     <view
+      ref={(n: { id: number }) => (world = n)}
       width={layer.width}
       height={layer.height}
       originX={camX()}

package/src/frames.ts

@@ -8,6 +8,29 @@
  */
 export type Frame = { u0: number; v0: number; u1: number; v1: number }
 
+/**
+ * Write a frame's four UVs at `at`, mirrored on the UV side when flipped:
+ * `flipX` swaps u0/u1, `flipY` swaps v0/v1. A flip is an involution, so the
+ * same call with the stored floats and only the CHANGED axes set toggles a
+ * flip in place, and reading back through it recovers the frame. Positional
+ * floats so the write allocates nothing.
+ */
+export function writeFrame(
+  data: Float32Array,
+  at: number,
+  u0: number,
+  v0: number,
+  u1: number,
+  v1: number,
+  flipX: boolean,
+  flipY: boolean,
+): void {
+  data[at] = flipX ? u1 : u0
+  data[at + 1] = flipY ? v1 : v0
+  data[at + 2] = flipX ? u0 : u1
+  data[at + 3] = flipY ? v0 : v1
+}
+
 export type GridOptions = {
   /** Pixel size of the atlas the pixel-space options below refer to. */
   width: number

package/src/layer.ts

@@ -38,8 +38,9 @@ import type { BufferId, TextureId } from "@solidrt/core/gpu"
 import * as spatial from "flux:spatial"
 import type { NodeId, NodeTransition } from "flux:spatial"
 import { on } from "srt:events"
+import { checkOversample } from "./oversample.ts"
 import type { Frame } from "./frames.ts"
-import { FULL_FRAME } from "./frames.ts"
+import { FULL_FRAME, writeFrame } from "./frames.ts"
 import type { RecordLayer } from "./records.ts"
 import { FRAGMENT, INSTANCE_ATTRIBUTES_SPLIT, VERTEX_SPLIT } from "./shaders.ts"
 
@@ -65,7 +66,7 @@ const BOX = new Float32Array(6)
 let declared = new Map<NodeId, Sprite | SpriteGroup>()
 let subscribed = false
 
-function declare(node: NodeId, handle: Sprite | SpriteGroup, transition: NodeTransition | string | null): void {
+function declareTransition(node: NodeId, handle: Sprite | SpriteGroup, transition: NodeTransition | string | null): void {
   if (transition === null) {
     declared.delete(node)
     return
@@ -108,6 +109,9 @@ export type Sprite = {
   _w: number
   _h: number
   _rot: number
+  /** Mirror flags (both layer kinds): re-applied to every frame write. */
+  _flipX: boolean
+  _flipY: boolean
   onPointerDown?: (event: SpritePointerEvent) => void
   onPointerMove?: (event: SpritePointerEvent) => void
   onPointerUp?: (event: SpritePointerEvent) => void
@@ -135,6 +139,11 @@ export type SpriteOptions = {
   h?: number
   /** Atlas frame (normalized UVs); default the whole atlas. */
   frame?: Frame
+  /** Mirror the frame horizontally / vertically about the sprite's center.
+   * A UV-side mirror: w/h stay the drawn size, a scale transition never
+   * sees it, picking is unchanged. Default false. */
+  flipX?: boolean
+  flipY?: boolean
   /** Rotation about the center, radians, clockwise (y-down space). */
   rotation?: number
   /** RGBA multiplier 0..1 each; default opaque white (the texture as-is). */
@@ -186,6 +195,15 @@ export type SpriteLayerOptions = {
   capacity?: number
   clearColor?: [number, number, number, number]
   label?: string
+  /**
+   * Target texels per layer pixel (positive integer, default 1). The layer
+   * renders at `oversample` times its size and is composited down, so a
+   * fractional or HiDPI display scale resamples properly instead of snapping
+   * (nearest) or smearing (linear); see setOversample. The components pick
+   * it from the leaf's on-screen size - set it here when composing the
+   * output yourself.
+   */
+  oversample?: number
   /** Skip the owner-scoped auto-dispose (see createSpriteLayer). */
   autoFree?: boolean
 }
@@ -233,6 +251,16 @@ export type LayerBase = {
   /** Live sprite count. */
   readonly count: number
   setSize(width: number, height: number): void
+  /** Target texels per layer pixel; see setOversample. */
+  readonly oversample: number
+  /**
+   * Re-render at `n` target texels per layer pixel (positive integer): the
+   * target resizes in place at its stable id, layer pixels, records, camera
+   * and picking are untouched. Pick `n` as the ceiling of the device pixels
+   * one layer pixel covers on screen (display scale times any designSize
+   * fit or layout scaling), which the components do in onLayout.
+   */
+  setOversample(n: number): void
   setCamera(update: CameraUpdate): void
   /** Topmost sprite whose rotated rect contains the layer-pixel point. */
   pick(x: number, y: number): Sprite | null
@@ -348,6 +376,15 @@ export function spriteDispatch(state: {
   }
 }
 
+/** The stored UVs at `at` un-mirrored by the sprite's flags: the frame as
+ * the caller gave it. Internal - records.ts reads through it too. */
+export function readFrame(data: Float32Array, at: number, sprite: Sprite): Frame {
+  let u0 = data[at]!, v0 = data[at + 1]!, u1 = data[at + 2]!, v1 = data[at + 3]!
+  return sprite._flipX || sprite._flipY
+    ? { u0: sprite._flipX ? u1 : u0, v0: sprite._flipY ? v1 : v0, u1: sprite._flipX ? u0 : u1, v1: sprite._flipY ? v0 : v1 }
+    : { u0, v0, u1, v1 }
+}
+
 /** Fill the shared transform scratch: xy translation, z rotation, xy scale
  * (a sprite's scale is its w/h - every sprite is a scaled unit quad). */
 function fillTransform(x: number, y: number, rot: number, sx: number, sy: number): void {
@@ -389,6 +426,8 @@ export function createSpriteLayer(
     throw new Error(`createSpriteLayer: capacity must be a positive integer, got ${capacity}`)
   }
   let label = opts?.label ?? "sprites"
+  let oversample = opts?.oversample ?? 1
+  checkOversample("createSpriteLayer", oversample, width, height)
   // One unit quad (triangle strip), reused by every instance.
   let quad = createBuffer(new Float32Array([-0.5, -0.5, 0.5, -0.5, -0.5, 0.5, 0.5, 0.5]), {
     label: `${label}-quad`,
@@ -399,8 +438,8 @@ export function createSpriteLayer(
   let texture = createPipelineTexture(
     VERTEX_SPLIT,
     FRAGMENT,
-    width,
-    height,
+    width * oversample,
+    height * oversample,
     { uViewport: [width, height], uCamera: [0, 0, 1, 1] },
     {
       label,
@@ -475,21 +514,28 @@ export function createSpriteLayer(
     styleDirty = true
   }
 
-  let writeStyle = (slot: number, opts: SpriteOptions) => {
-    let at = slot * STYLE_FLOATS
+  let writeStyle = (sprite: Sprite, opts: SpriteOptions) => {
+    let at = sprite._slot * STYLE_FLOATS
+    let flipX = opts.flipX !== undefined && opts.flipX !== sprite._flipX
+    let flipY = opts.flipY !== undefined && opts.flipY !== sprite._flipY
+    if (flipX) sprite._flipX = !sprite._flipX
+    if (flipY) sprite._flipY = !sprite._flipY
     if (opts.frame !== undefined) {
-      styleData[at] = opts.frame.u0
-      styleData[at + 1] = opts.frame.v0
-      styleData[at + 2] = opts.frame.u1
-      styleData[at + 3] = opts.frame.v1
+      let f = opts.frame
+      writeFrame(styleData, at, f.u0, f.v0, f.u1, f.v1, sprite._flipX, sprite._flipY)
+      styleDirty = true
+    } else if (flipX || flipY) {
+      // No new frame: toggle the changed axes on the stored UVs.
+      writeFrame(styleData, at, styleData[at]!, styleData[at + 1]!, styleData[at + 2]!, styleData[at + 3]!, flipX, flipY)
+      styleDirty = true
     }
     if (opts.tint !== undefined) {
       styleData[at + 4] = opts.tint[0]
       styleData[at + 5] = opts.tint[1]
       styleData[at + 6] = opts.tint[2]
       styleData[at + 7] = opts.tint[3]
+      styleDirty = true
     }
-    styleDirty = true
   }
 
   let dispatch = spriteDispatch({
@@ -506,11 +552,21 @@ export function createSpriteLayer(
     },
     setSize(w, h) {
       if (disposed || (w === width && h === height)) return
+      checkOversample("setSize", oversample, w, h)
       width = w
       height = h
-      setTargetSize(texture, w, h)
+      setTargetSize(texture, w * oversample, h * oversample)
       setTargetParams(texture, { uViewport: [w, h] })
     },
+    get oversample() {
+      return oversample
+    },
+    setOversample(n) {
+      if (disposed || n === oversample) return
+      checkOversample("setOversample", n, width, height)
+      oversample = n
+      setTargetSize(texture, width * n, height * n)
+    },
     setCamera(update) {
       if (disposed) return
       if (update.x !== undefined) camX = update.x
@@ -591,6 +647,8 @@ export function createSpriteLayer(
         _w: opts?.w ?? 0,
         _h: opts?.h ?? 0,
         _rot: opts?.rotation ?? 0,
+        _flipX: false,
+        _flipY: false,
       }
       fillTransform(sprite._x, sprite._y, sprite._rot, sprite._w, sprite._h)
       let node = spatial.createNode(TRANSFORM, true)
@@ -602,7 +660,7 @@ export function createSpriteLayer(
       spatial.setBounds(node, FLAT_BOUNDS)
       spatial.bindPoseRecord(node, pose, slot)
       byNode.set(node, sprite)
-      writeStyle(slot, { frame: FULL_FRAME, tint: [1, 1, 1, 1], ...opts })
+      writeStyle(sprite, { frame: FULL_FRAME, tint: [1, 1, 1, 1], ...opts })
       layer._schedule()
       return sprite
     },
@@ -614,7 +672,9 @@ export function createSpriteLayer(
       if (opts.h !== undefined && opts.h !== sprite._h) (sprite._h = opts.h), (moved = true)
       if (opts.rotation !== undefined && opts.rotation !== sprite._rot) (sprite._rot = opts.rotation), (moved = true)
       if (moved) writeTransform(sprite)
-      if (opts.frame !== undefined || opts.tint !== undefined) writeStyle(sprite._slot, opts)
+      if (opts.frame !== undefined || opts.tint !== undefined || opts.flipX !== undefined || opts.flipY !== undefined) {
+        writeStyle(sprite, opts)
+      }
       if (moved || styleDirty) layer._schedule()
     },
     _read(sprite) {
@@ -624,7 +684,9 @@ export function createSpriteLayer(
         y: sprite._y,
         w: sprite._w,
         h: sprite._h,
-        frame: { u0: styleData[at]!, v0: styleData[at + 1]!, u1: styleData[at + 2]!, v1: styleData[at + 3]! },
+        frame: readFrame(styleData, at, sprite),
+        flipX: sprite._flipX,
+        flipY: sprite._flipY,
         rotation: sprite._rot,
         tint: [styleData[at + 4]!, styleData[at + 5]!, styleData[at + 6]!, styleData[at + 7]!],
       }
@@ -715,7 +777,7 @@ export function setSpriteTransition(sprite: Sprite, transition: NodeTransition |
   if (sprite.layer === null) return
   if (sprite.node === null) throw new Error("setSpriteTransition: record sprites have no node transitions")
   spatial.setTransition(sprite.node, transition)
-  declare(sprite.node, sprite, transition)
+  declareTransition(sprite.node, sprite, transition)
 }
 
 /** The group counterpart of setSpriteTransition (`scale` is the group's
@@ -723,7 +785,7 @@ export function setSpriteTransition(sprite: Sprite, transition: NodeTransition |
 export function setGroupTransition(group: SpriteGroup, transition: NodeTransition | string | null): void {
   if (group.layer === null) return
   spatial.setTransition(group.node, transition)
-  declare(group.node, group, transition)
+  declareTransition(group.node, group, transition)
 }
 
 /** Add a transform group (see SpriteGroup). */

package/src/oversample.ts

@@ -0,0 +1,40 @@
+// The layer oversample: how many target texels one layer pixel is drawn
+// as. A layer renders at `oversample` times its size and is composited down
+// to its box, so a fractional or HiDPI display scale resamples properly: the
+// atlas is still sampled nearest inside (texels stay square blocks), the
+// composite samples linear (each block edge softens over one device pixel
+// instead of snapping to uneven widths). okf/backlog/2d-layer-display-scale.md.
+import { limits } from "@solidrt/core/gpu"
+
+/** Tolerance under a whole number when rounding a display scale up, so a
+ * scale that is 3 up to float noise picks 3, not 4. */
+const FIT_EPSILON = 1e-6
+
+/** Validate an oversample against the target it scales; throws (dev policy). */
+export function checkOversample(verb: string, n: number, width: number, height: number): void {
+  if (!(Number.isInteger(n) && n >= 1)) {
+    throw new Error(`${verb}: oversample must be a positive integer, got ${n}`)
+  }
+  let max = limits.maxTextureSize
+  if (width * n > max || height * n > max) {
+    throw new Error(`${verb}: ${width} x ${height} at oversample ${n} exceeds maxTextureSize ${max}`)
+  }
+}
+
+/**
+ * The oversample for a layer shown at `scale` device pixels per layer pixel:
+ * the ceiling of the scale, so no device pixel goes without a target texel.
+ * Bounded by `budget` texels for the `targetW x targetH` target (the
+ * window's own device pixel count: a target beyond it buys nothing on
+ * screen, and a layer stretched far past the window inside a scroller must
+ * not ask for one) and by what the target can grow to on this device.
+ */
+export function fitOversample(scale: number, targetW: number, targetH: number, budget: number): number {
+  // The budget bounds the scale, not the rounded factor: the ceiling may
+  // still round a fit that fills the window up by one (a 320 x 200 design
+  // on a 2560 x 1440 panel fits at 7.2 and needs 8).
+  let byBudget = Math.sqrt(budget / (targetW * targetH))
+  let n = Math.max(1, Math.ceil(Math.min(scale, byBudget) - FIT_EPSILON))
+  let byDevice = Math.floor(limits.maxTextureSize / Math.max(targetW, targetH))
+  return Math.max(1, Math.min(n, byDevice))
+}

package/src/records.ts

@@ -30,10 +30,11 @@ import {
   setTargetSize,
 } from "@solidrt/core/gpu"
 import type { BufferId, TextureId } from "@solidrt/core/gpu"
-import { FULL_FRAME } from "./frames.ts"
-import { spriteDispatch } from "./layer.ts"
+import { FULL_FRAME, writeFrame } from "./frames.ts"
+import { readFrame, spriteDispatch } from "./layer.ts"
 import type { LayerBase, Sprite, SpriteHandlers, SpriteLayerOptions, SpriteOptions } from "./layer.ts"
 import { pointInSprite } from "./pick.ts"
+import { checkOversample } from "./oversample.ts"
 import { FRAGMENT, INSTANCE_ATTRIBUTES, VERTEX } from "./shaders.ts"
 
 // Floats per instance record:
@@ -84,11 +85,13 @@ export function createRecordLayer(
     label: `${label}-records`,
     autoFree: false,
   })
+  let oversample = opts?.oversample ?? 1
+  checkOversample("createRecordLayer", oversample, width, height)
   let texture = createPipelineTexture(
     VERTEX,
     FRAGMENT,
-    width,
-    height,
+    width * oversample,
+    height * oversample,
     { uViewport: [width, height], uCamera: [0, 0, 1, 1] },
     {
       label,
@@ -154,11 +157,16 @@ export function createRecordLayer(
     if (opts.y !== undefined) r[at + 1] = opts.y
     if (opts.w !== undefined) r[at + 2] = opts.w
     if (opts.h !== undefined) r[at + 3] = opts.h
+    let flipX = opts.flipX !== undefined && opts.flipX !== sprite._flipX
+    let flipY = opts.flipY !== undefined && opts.flipY !== sprite._flipY
+    if (flipX) sprite._flipX = !sprite._flipX
+    if (flipY) sprite._flipY = !sprite._flipY
     if (opts.frame !== undefined) {
-      r[at + 4] = opts.frame.u0
-      r[at + 5] = opts.frame.v0
-      r[at + 6] = opts.frame.u1
-      r[at + 7] = opts.frame.v1
+      let f = opts.frame
+      writeFrame(r, at + 4, f.u0, f.v0, f.u1, f.v1, sprite._flipX, sprite._flipY)
+    } else if (flipX || flipY) {
+      // No new frame: toggle the changed axes on the stored UVs.
+      writeFrame(r, at + 4, r[at + 4]!, r[at + 5]!, r[at + 6]!, r[at + 7]!, flipX, flipY)
     }
     if (opts.rotation !== undefined) r[at + 8] = opts.rotation
     if (opts.tint !== undefined) {
@@ -183,11 +191,21 @@ export function createRecordLayer(
     },
     setSize(w, h) {
       if (disposed || (w === width && h === height)) return
+      checkOversample("setSize", oversample, w, h)
       width = w
       height = h
-      setTargetSize(texture, w, h)
+      setTargetSize(texture, w * oversample, h * oversample)
       setTargetParams(texture, { uViewport: [w, h] })
     },
+    get oversample() {
+      return oversample
+    },
+    setOversample(n) {
+      if (disposed || n === oversample) return
+      checkOversample("setOversample", n, width, height)
+      oversample = n
+      setTargetSize(texture, width * n, height * n)
+    },
     setCamera(update) {
       if (disposed) return
       if (update.x !== undefined) camX = update.x
@@ -231,7 +249,7 @@ export function createRecordLayer(
         next.set(layer.records)
         layer.records = next
       }
-      let sprite: Sprite = { layer, node: null, _slot: index, _x: 0, _y: 0, _w: 0, _h: 0, _rot: 0 }
+      let sprite: Sprite = { layer, node: null, _slot: index, _x: 0, _y: 0, _w: 0, _h: 0, _rot: 0, _flipX: false, _flipY: false }
       layer._order.push(sprite)
       writeRecord(sprite, {
         x: 0,
@@ -258,7 +276,9 @@ export function createRecordLayer(
         y: r[at + 1]!,
         w: r[at + 2]!,
         h: r[at + 3]!,
-        frame: { u0: r[at + 4]!, v0: r[at + 5]!, u1: r[at + 6]!, v1: r[at + 7]! },
+        frame: readFrame(r, at + 4, sprite),
+        flipX: sprite._flipX,
+        flipY: sprite._flipY,
         rotation: r[at + 8]!,
         tint: [r[at + 9]!, r[at + 10]!, r[at + 11]!, r[at + 12]!],
       }

package/src/tiles.ts

@@ -30,9 +30,11 @@ import {
   endBufferWrite,
   limits,
   renderTarget,
+  setTargetSize,
 } from "@solidrt/core/gpu"
 import type { BufferId, FilterMode, TextureId } from "@solidrt/core/gpu"
 import type { Frame } from "./frames.ts"
+import { checkOversample } from "./oversample.ts"
 import { FLOATS_PER_SPRITE } from "./records.ts"
 import { FRAGMENT, INSTANCE_ATTRIBUTES, VERTEX } from "./shaders.ts"
 
@@ -45,11 +47,19 @@ export type TileLayerOptions = {
   /** Per-chunk clear color; empty (never-written) chunks render nothing. */
   clearColor?: [number, number, number, number]
   /**
-   * Sampler filter for the baked chunk textures (what the camera zoom
-   * scales at composite time); default "linear". Pixel art wants "nearest"
-   * - hard pixels under integer upscales.
+   * Sampler filter for the baked chunk textures at composite time; default
+   * "linear", which with `oversample` is the proper resample at any scale.
+   * Hard pixels belong to the ATLAS sampler (createAtlas `filter:
+   * "nearest"`), not here: "nearest" on the chunks snaps texels to uneven
+   * widths at a fractional scale.
    */
   filter?: FilterMode
+  /**
+   * Target texels per world pixel in the baked chunks (positive integer,
+   * default 1); see TileLayer.setOversample. `<TileLayer>` picks it from
+   * the world view's on-screen size.
+   */
+  oversample?: number
   /**
    * Chunk edge in TILES; default sized so a chunk is ~512px. The tuning
    * knob between re-bake granularity (smaller = finer dirty regions) and
@@ -80,6 +90,20 @@ export type TileLayer = {
   /** World size in pixels: cols * tileW x rows * tileH. */
   width: number
   height: number
+  /** Chunk size in world pixels (chunkTiles * tile size): the target a
+   * chunk bakes into, before `oversample`. */
+  chunkW: number
+  chunkH: number
+  /** Target texels per world pixel; see setOversample. */
+  readonly oversample: number
+  /**
+   * Re-bake at `n` target texels per world pixel (positive integer): every
+   * resident chunk resizes in place and re-bakes once; world pixels, records
+   * and the camera are untouched. Pick `n` as the ceiling of the device
+   * pixels one world pixel covers on screen (display scale times camera
+   * zoom times any designSize fit), which `<TileLayer>` does in onLayout.
+   */
+  setOversample(n: number): void
   /**
    * The resident chunks, in allocation order - the layer's output.
    * Composite each as a texture leaf at its world rect (`<TileLayer>` does
@@ -140,6 +164,8 @@ export function createTileLayer(
     )
   }
   let label = opts?.label ?? "tiles"
+  let oversample = opts?.oversample ?? 1
+  checkOversample("createTileLayer", oversample, chunkW, chunkH)
   let chunkCols = Math.ceil(cols / chunkTiles)
   let perChunk = chunkTiles * chunkTiles
   // One unit quad (triangle strip), shared by every chunk's pipeline.
@@ -185,8 +211,8 @@ export function createTileLayer(
     let texture = createPipelineTexture(
       VERTEX,
       FRAGMENT,
-      chunkW,
-      chunkH,
+      chunkW * oversample,
+      chunkH * oversample,
       { uViewport: [chunkW, chunkH], uCamera: [x, y, 1, 1] },
       {
         label: `${label}-chunk`,
@@ -228,7 +254,23 @@ export function createTileLayer(
     tileH,
     width: cols * tileW,
     height: rows * tileH,
+    chunkW,
+    chunkH,
     chunks: [],
+    get oversample() {
+      return oversample
+    },
+    setOversample(n) {
+      if (disposed || n === oversample) return
+      checkOversample("setOversample", n, chunkW, chunkH)
+      oversample = n
+      // Resizing a target re-renders it, but a manual target's content is
+      // its last bake: mark every chunk so the flush bakes it at the new size.
+      for (let chunk of resident.values()) {
+        setTargetSize(chunk.texture, chunkW * n, chunkH * n)
+        touch(chunk)
+      }
+    },
     setTile(col, row, frame) {
       if (disposed) return
       let [index, at] = locate(col, row, "setTile")