@forgeax/engine-render 0.0.0-dev.8d955ade1c79

package/src/ssao-buffers.ts

@@ -0,0 +1,334 @@
+// @forgeax/engine-runtime — SSAO per-runtime persistent GPU buffers.
+//
+// feat-20260612-hdrp-ssao M1 / w4.
+//
+// Owner of 3 SSAO GPU resources, lazily allocated per RenderSystemRuntime,
+// following the getOrCreateHdrpBuffers WeakMap pattern (research F12):
+//   (1) kernel UBO  — 64 padded vec4 samples (1024 B), label hdrp-ssao-kernel
+//   (2) noise texture — 4x4 rgba32float, label hdrp-ssao-noise, NEAREST/REPEAT
+//   (3) uniform UBO   — 3 mat4 + vec4 intensityPad (256 B aligned),
+//                       label hdrp-ssao-uniform
+//
+// plan-strategy D-1: uniform carries view + projection + inverseProjection.
+// plan-strategy D-C: intensity, radius, and bias are carried at offset 192
+//   (the existing vec4 slot), so the lighting shader can mix(1.0, ssao*ao,
+//   intensity) without a new UBO.
+// The kernel uses a uniform buffer on every backend. 1024 B is below the
+// WebGL2 minimum fragment UBO size, so SSAO does not need a storage-buffer
+// capability gate.
+
+import type { Buffer, Sampler, Texture, TextureView } from '@forgeax/engine-rhi';
+import { GPU_TEXTURE_USAGE_COPY_DST, GPU_TEXTURE_USAGE_TEXTURE_BINDING } from './gpu-texture-usage';
+import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from './gpu-usage';
+import type { RenderSystemRuntime } from './record/render-context';
+
+// Deterministic host-side SSAO data is owned by the buffer allocator because
+// these values have no consumer outside the resources they initialize.
+export const SSAO_KERNEL_SAMPLE_COUNT = 64;
+const NOISE_SIZE = 16;
+
+function mulberry32(seed: number): () => number {
+  let state = seed | 0;
+  return () => {
+    state = (state + 0x6d2b79f5) | 0;
+    let t = Math.imul(state ^ (state >>> 15), 1 | state);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function lerp(a: number, b: number, t: number): number {
+  return a + t * (b - a);
+}
+
+export function generateSsaoKernel(seed: number = 0): readonly Float32Array[] {
+  const rand = mulberry32(seed);
+  const kernel: Float32Array[] = [];
+  for (let i = 0; i < SSAO_KERNEL_SAMPLE_COUNT; i++) {
+    let x = rand() * 2 - 1;
+    let y = rand() * 2 - 1;
+    let z = rand();
+    const len = Math.sqrt(x * x + y * y + z * z);
+    x /= len;
+    y /= len;
+    z /= len;
+    const r = rand();
+    x *= r;
+    y *= r;
+    z *= r;
+    const scale = lerp(0.1, 1.0, (i / SSAO_KERNEL_SAMPLE_COUNT) ** 2);
+    const sample = new Float32Array(3);
+    sample[0] = x * scale;
+    sample[1] = y * scale;
+    sample[2] = z * scale;
+    kernel.push(sample);
+  }
+  return kernel;
+}
+
+export function generateSsaoNoise(seed: number = 0): Float32Array {
+  const rand = mulberry32(seed);
+  const noise = new Float32Array(NOISE_SIZE * 3);
+  for (let i = 0; i < NOISE_SIZE; i++) {
+    noise[i * 3 + 0] = rand() * 2 - 1;
+    noise[i * 3 + 1] = rand() * 2 - 1;
+    noise[i * 3 + 2] = 0;
+  }
+  return noise;
+}
+
+// Each vec3<f32> in a WGSL array is 16B (12B payload + 4B padding).
+// 64 samples * 16 B/sample = 1024 B.
+const BYTES_PER_KERNEL_ELEMENT = 16;
+
+// SSAO uniform layout (plan-strategy §D-1 + §D-C, M7 round-2):
+//   bytes [0..63]    view              mat4x4<f32>
+//   bytes [64..127]  projection        mat4x4<f32>
+//   bytes [128..191] inverseProjection mat4x4<f32>
+//   bytes [192..207] intensityPad      vec4<f32>  // x = intensity, y = radius, z = bias, w = pad
+//   bytes [208..255] padding           // align to 256B WebGPU UBO offset
+//
+// The total is rounded to 256B so the same UBO can host an additional
+// shader-side scalar binding at the tail without re-allocation.
+const UNIFORM_INTENSITY_OFFSET_BYTES = 192;
+const UNIFORM_BYTES = 256;
+export const SSAO_UNIFORM_INTENSITY_OFFSET = UNIFORM_INTENSITY_OFFSET_BYTES;
+export const SSAO_UNIFORM_BYTES = UNIFORM_BYTES;
+
+// ── 1x1 white fallback texture (plan-strategy §D-B) ───────────────────────
+//
+// Single-PSO invariant: the HDRP unified BGL always declares a binding 7
+// texture_2d<f32>. When SSAO is disabled (or its resources are not yet
+// allocated), the bind group binds this 1x1 r8unorm texture filled with
+// 0xFF. r8unorm normalizes 255 -> 1.0, so the lighting shader reads
+// `ssaoFactor = 1.0`, and `mix(1.0, ssao*ao, intensity) = ao` collapses
+// back to the round-1 baseline (ambient = baked-AO only). No shader
+// recompile across enable/disable.
+
+interface SsaoFallbackResources {
+  readonly texture: Texture;
+  readonly view: TextureView;
+  readonly sampler: Sampler;
+}
+
+const fallbackCache = new WeakMap<RenderSystemRuntime, SsaoFallbackResources>();
+
+/**
+ * Lazily allocate the 1x1 r8unorm white fallback texture + a sampler for
+ * SSAO disabled / resource-missing path. Cached per RenderSystemRuntime so
+ * subsequent calls reuse the same resources (charter P5 one-owner).
+ *
+ * Returns `null` if `device.createTexture` / `createTextureView` /
+ * `createSampler` / `queue.writeTexture` fails; the caller (createBindGroup)
+ * propagates the structured RhiError that landed on `runtime.errorRegistry`.
+ */
+export function getOrCreateSsaoFallbackTexture(
+  runtime: RenderSystemRuntime,
+): SsaoFallbackResources | null {
+  const cached = fallbackCache.get(runtime);
+  if (cached !== undefined) return cached;
+
+  const device = runtime.device;
+  const texRes = device.createTexture({
+    label: 'hdrp-ssao-fallback-white',
+    size: { width: 1, height: 1, depthOrArrayLayers: 1 },
+    mipLevelCount: 1,
+    sampleCount: 1,
+    dimension: '2d',
+    format: 'r8unorm',
+    usage: GPU_TEXTURE_USAGE_TEXTURE_BINDING | GPU_TEXTURE_USAGE_COPY_DST,
+    textureBindingViewDimension: undefined,
+  });
+  if (!texRes.ok) {
+    runtime.errorRegistry.fire(texRes.error);
+    return null;
+  }
+
+  // r8unorm: a single byte 0xFF normalizes to 1.0 (white => AO = 1.0).
+  const whitePixel = new Uint8Array([255]);
+  const writeRes = device.queue.writeTexture(
+    {
+      texture: texRes.value,
+      mipLevel: 0,
+      origin: { x: 0, y: 0, z: 0 },
+    },
+    whitePixel,
+    { offset: 0, bytesPerRow: 256, rowsPerImage: 1 },
+    { width: 1, height: 1, depthOrArrayLayers: 1 },
+  );
+  if (!writeRes.ok) {
+    runtime.errorRegistry.fire(writeRes.error);
+    return null;
+  }
+
+  const viewRes = device.createTextureView(texRes.value, {
+    label: 'hdrp-ssao-fallback-white-view',
+    format: 'r8unorm',
+    dimension: '2d',
+    aspect: 'all',
+    baseMipLevel: 0,
+    mipLevelCount: 1,
+    baseArrayLayer: 0,
+    arrayLayerCount: 1,
+  });
+  if (!viewRes.ok) {
+    runtime.errorRegistry.fire(viewRes.error);
+    return null;
+  }
+
+  const samplerRes = device.createSampler({
+    label: 'hdrp-ssao-fallback-sampler',
+    magFilter: 'linear',
+    minFilter: 'linear',
+    mipmapFilter: 'linear',
+    addressModeU: 'clamp-to-edge',
+    addressModeV: 'clamp-to-edge',
+    addressModeW: 'clamp-to-edge',
+  });
+  if (!samplerRes.ok) {
+    runtime.errorRegistry.fire(samplerRes.error);
+    return null;
+  }
+
+  const resources: SsaoFallbackResources = {
+    texture: texRes.value,
+    view: viewRes.value,
+    sampler: samplerRes.value,
+  };
+  fallbackCache.set(runtime, resources);
+  return resources;
+}
+
+/**
+ * SSAO GPU resources owned by this module (plan-strategy D-1, D-4).
+ *
+ * Fields are readonly per charter P5: one resource, one owner.
+ */
+export interface SsaoBuffers {
+  /** 64 padded vec4 uniform buffer for hemisphere samples. */
+  readonly kernelBuffer: Buffer;
+  readonly kernelBytes: number;
+  /** 4x4 rgba32float noise texture for per-pixel TBN rotation. */
+  readonly noiseTexture: Texture;
+  /** SSAO uniform UBO: view (mat4) + projection (mat4) + inverseProjection (mat4). */
+  readonly uniformBuffer: Buffer;
+  readonly uniformBytes: number;
+}
+
+const cache = new WeakMap<RenderSystemRuntime, SsaoBuffers>();
+
+/**
+ * Lazily allocate the 3 SSAO GPU resources for `runtime`. Returns the
+ * same `SsaoBuffers` object on subsequent calls (per-RenderSystem
+ * stable identity, WeakMap).
+ *
+ * On `device.createBuffer` / `device.createTexture` failure, fires a
+ * structured error on the runtime's error registry and returns `null`.
+ *
+ * @returns SsaoBuffers on success, null if an allocation fails.
+ */
+export function getOrCreateSsaoBuffers(runtime: RenderSystemRuntime): SsaoBuffers | null {
+  const cached = cache.get(runtime);
+  if (cached !== undefined) return cached;
+
+  const device = runtime.device;
+
+  // (1) Kernel UBO — 64 padded vec4 samples (1024 B).
+  const kernelSamples = generateSsaoKernel();
+  const kernelData = new Float32Array(SSAO_KERNEL_SAMPLE_COUNT * 4); // 4 floats per padded vec3
+  for (let i = 0; i < SSAO_KERNEL_SAMPLE_COUNT; i++) {
+    const s = kernelSamples[i];
+    if (s === undefined) continue;
+    kernelData[i * 4 + 0] = s[0] ?? 0;
+    kernelData[i * 4 + 1] = s[1] ?? 0;
+    kernelData[i * 4 + 2] = s[2] ?? 0;
+    // kernelData[i * 4 + 3] = 0 (padding for std140 vec3 alignment)
+  }
+
+  const kernelBufferRes = device.createBuffer({
+    label: 'hdrp-ssao-kernel',
+    size: SSAO_KERNEL_SAMPLE_COUNT * BYTES_PER_KERNEL_ELEMENT,
+    usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+    mappedAtCreation: false,
+  });
+  if (!kernelBufferRes.ok) {
+    runtime.errorRegistry.fire(kernelBufferRes.error);
+    return null;
+  }
+
+  // Upload kernel data to the buffer.
+  const kernelWriteRes = device.queue.writeBuffer(kernelBufferRes.value, 0, kernelData);
+  if (!kernelWriteRes.ok) {
+    runtime.errorRegistry.fire(kernelWriteRes.error);
+    return null;
+  }
+
+  // (2) Noise texture — 4x4 rgba32float, NEAREST/REPEAT.
+  const noiseData = generateSsaoNoise();
+  // Pad to rgba32float: 16 texels * 4 floats = 64 floats.
+  const noiseRgba = new Float32Array(16 * 4);
+  for (let i = 0; i < 16; i++) {
+    noiseRgba[i * 4 + 0] = noiseData[i * 3 + 0] ?? 0;
+    noiseRgba[i * 4 + 1] = noiseData[i * 3 + 1] ?? 0;
+    noiseRgba[i * 4 + 2] = 0;
+    noiseRgba[i * 4 + 3] = 1; // alpha = 1 for rgba32float
+  }
+
+  const noiseTexRes = device.createTexture({
+    label: 'hdrp-ssao-noise',
+    size: { width: 4, height: 4, depthOrArrayLayers: 1 },
+    mipLevelCount: 1,
+    sampleCount: 1,
+    dimension: '2d',
+    format: 'rgba32float',
+    usage: GPU_TEXTURE_USAGE_COPY_DST | GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+    textureBindingViewDimension: undefined,
+  });
+  if (!noiseTexRes.ok) {
+    runtime.errorRegistry.fire(noiseTexRes.error);
+    return null;
+  }
+
+  // Direct CPU-to-GPU upload via writeTexture (no alignment requirement
+  // unlike copyBufferToTexture; WebGPU spec §19.2). 4x4 rgba32float texture
+  // = 16 texels * 4 floats * 4 bytes/float = 256 bytes.
+  // The forgeax Texture brand wraps a raw GPUTexture; cast through unknown
+  // follows the createRenderer.ts fallback-pixel pattern (line 4330).
+  const noiseCopyRes = device.queue.writeTexture(
+    {
+      texture: noiseTexRes.value,
+      mipLevel: 0,
+      origin: { x: 0, y: 0, z: 0 },
+    },
+    noiseRgba,
+    { offset: 0, bytesPerRow: 4 * 4 * 4, rowsPerImage: 4 },
+    { width: 4, height: 4, depthOrArrayLayers: 1 },
+  );
+  if (!noiseCopyRes.ok) {
+    runtime.errorRegistry.fire(noiseCopyRes.error);
+    return null;
+  }
+
+  // (3) SSAO uniform UBO — 3 mat4 (192 B).
+  const uniformBufRes = device.createBuffer({
+    label: 'hdrp-ssao-uniform',
+    size: UNIFORM_BYTES,
+    usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+    mappedAtCreation: false,
+  });
+  if (!uniformBufRes.ok) {
+    runtime.errorRegistry.fire(uniformBufRes.error);
+    return null;
+  }
+
+  const buffers: SsaoBuffers = {
+    kernelBuffer: kernelBufferRes.value,
+    kernelBytes: SSAO_KERNEL_SAMPLE_COUNT * BYTES_PER_KERNEL_ELEMENT,
+    noiseTexture: noiseTexRes.value,
+    uniformBuffer: uniformBufRes.value,
+    uniformBytes: UNIFORM_BYTES,
+  };
+
+  cache.set(runtime, buffers);
+  return buffers;
+}

package/src/ssao-config.ts

@@ -0,0 +1,61 @@
+// @forgeax/engine-render - SSAO parameter authority.
+
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { PostProcessError } from './post-process-errors';
+
+export const SSAO_DEFAULT_RADIUS = 0.5;
+export const SSAO_DEFAULT_BIAS = 0.025;
+export const SSAO_DEFAULT_INTENSITY = 1.0;
+
+export interface SsaoParameterConfig {
+  readonly radius?: number | undefined;
+  readonly bias?: number | undefined;
+  readonly intensity?: number | undefined;
+}
+
+export interface ResolvedSsaoParameters {
+  readonly radius: number;
+  readonly bias: number;
+  readonly intensity: number;
+}
+
+/**
+ * Apply the public defaults without deciding whether the values are valid.
+ * The record stage uses this only after the graph build has validated the
+ * active HDRP configuration, or for the disabled/default fallback payload.
+ */
+export function getSsaoParameters(config: SsaoParameterConfig | undefined): ResolvedSsaoParameters {
+  return {
+    radius: config?.radius ?? SSAO_DEFAULT_RADIUS,
+    bias: config?.bias ?? SSAO_DEFAULT_BIAS,
+    intensity: config?.intensity ?? SSAO_DEFAULT_INTENSITY,
+  };
+}
+
+/**
+ * Resolve and validate the SSAO configuration used by both graph routes.
+ * Invalid values remain structured PostProcessErrors instead of becoming
+ * NaNs or silently falling back to shader literals.
+ */
+export function resolveSsaoParameters(
+  config: SsaoParameterConfig | undefined,
+): Result<ResolvedSsaoParameters, PostProcessError> {
+  const resolved = getSsaoParameters(config);
+  if (resolved.radius <= 0) {
+    return err(
+      new PostProcessError({
+        code: 'ssao-radius-non-positive',
+        detail: { paramName: 'radius', value: resolved.radius },
+      }),
+    );
+  }
+  if (resolved.bias < 0) {
+    return err(
+      new PostProcessError({
+        code: 'ssao-bias-negative',
+        detail: { paramName: 'bias', value: resolved.bias },
+      }),
+    );
+  }
+  return ok(resolved);
+}

package/src/systems/active-camera.ts

@@ -0,0 +1,116 @@
+// @forgeax/engine-runtime - ActiveCamera KV resource + selection helper.
+//
+// feat-20260630-viewport-2x2-run-x-display-redesign M2 w12 / plan-strategy D-2.
+//
+// PROBLEM (research Finding 4): the render extract stage selects the camera by
+// archetype-query FIRST-HIT (`cameras[0]`) and fires `render-system-multi-camera`
+// when more than one [Camera, Transform, Entity] entity exists. A single engine
+// world that carries BOTH an editor orbit camera AND a game camera therefore
+// cannot pick which one renders. This module adds the minimum neutral mechanism:
+// an `ActiveCamera { entity }` resource naming the entity to render through.
+//
+// ENGINE-NEUTRAL (requirements OOS-4 / AC-16): the engine knows only entity IDs.
+// It does NOT know which entity is "editor" or "game" -- the caller (editor side)
+// decides what `ActiveCamera.entity` points at. No editor concept enters this
+// file or the engine layer.
+//
+// BACKWARD COMPATIBLE (plan-strategy D-2): when the resource is ABSENT, or the
+// named entity is not among the queried cameras, selection falls back to the
+// existing first-hit behavior unchanged. Single-camera scenes are unaffected.
+//
+// Surface:
+//   - interface  ActiveCamera { entity: number }
+//   - constant   ACTIVE_CAMERA_KEY = 'ActiveCamera'
+//   - helper     getActiveCamera(world): ActiveCamera | undefined
+//   - helper     setActiveCamera(world, entity): void
+//   - pure       selectActiveCameraIndex(cameraEntities, activeEntity): number
+//
+// @new-surface KV resource: ECS has no defineResource factory; the TS POD
+//   interface + string KV key form is the minimum-new-surface route, mirroring
+//   TransparentSortConfig. The world resource store
+//   (insertResource / getResource / hasResource) is reused unchanged.
+// @derives world.hasResource / world.insertResource / world.getResource KV API.
+// @fallback getActiveCamera KV missing returns undefined; no warn; no throw
+//   (absent ActiveCamera is a legal state -> first-hit fallback in extract).
+//
+// charter mapping: F1 (single-import barrel + single entity pointer, smallest
+// concept face vs a multi-field priority/enabled scheme) + P4 (consistent
+// abstraction -- same world.{has,get,insert}Resource KV API as every other
+// engine resource consumer).
+
+import type { World } from '@forgeax/engine-ecs';
+
+// ────────────────────────────────────────────────────────────────────────────
+// POD interface + KV key
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Active-camera pointer (plain-data POD). Lives as a world-level resource keyed
+ * by `ACTIVE_CAMERA_KEY`. `entity` is the packed entity id (engine `EntityHandle`
+ * is a branded number) of the camera the renderer should use.
+ *
+ * The engine treats `entity` as an opaque id; whether it names an editor camera
+ * or a game camera is a caller-side decision (OOS-4 — engine stays neutral).
+ */
+export interface ActiveCamera {
+  readonly entity: number;
+}
+
+/** World resource key for the `ActiveCamera` KV entry. */
+export const ACTIVE_CAMERA_KEY = 'ActiveCamera' as const;
+
+// ────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Read the world's `ActiveCamera` resource.
+ *
+ * @fallback KV missing returns `undefined` — absent ActiveCamera is a legal
+ * state (the renderer falls back to archetype first-hit). NO warn, NO throw.
+ * The `hasResource` guard precedes the read so this helper never trips
+ * `ResourceNotFoundError` from `world.getResource`.
+ *
+ * @example
+ *   const a = getActiveCamera(world);   // undefined when not set
+ *   if (a) { ... a.entity ... }
+ */
+export function getActiveCamera(world: World): ActiveCamera | undefined {
+  if (!world.hasResource(ACTIVE_CAMERA_KEY)) return undefined;
+  return world.getResource<ActiveCamera>(ACTIVE_CAMERA_KEY);
+}
+
+/**
+ * Write the world's `ActiveCamera` resource (idempotent last-write-wins via
+ * `world.insertResource`). The renderer will use the camera whose entity id
+ * equals `entity`, or fall back to first-hit if that id is not a queried camera.
+ *
+ * @example
+ *   setActiveCamera(world, gameCameraEntity);  // render through the game camera
+ */
+export function setActiveCamera(world: World, entity: number): void {
+  world.insertResource<ActiveCamera>(ACTIVE_CAMERA_KEY, { entity });
+}
+
+/**
+ * Pure selection: given the entity ids of every camera surfaced by the extract
+ * archetype query (in query order) and the optional active-camera entity id,
+ * return the index of the active camera in `cameraEntities`, or `-1` to signal
+ * "no selection — use first-hit fallback".
+ *
+ * `-1` is returned when `activeEntity` is `undefined` (resource absent) OR when
+ * the id is not present among `cameraEntities` (stale / non-camera entity).
+ * Both cases preserve the existing first-hit behavior (plan-strategy D-2).
+ *
+ * @example
+ *   selectActiveCameraIndex([10, 20, 30], 20) === 1   // pick the 2nd camera
+ *   selectActiveCameraIndex([10, 20, 30], undefined) === -1  // first-hit
+ *   selectActiveCameraIndex([10, 20, 30], 999) === -1        // first-hit
+ */
+export function selectActiveCameraIndex(
+  cameraEntities: readonly number[],
+  activeEntity: number | undefined,
+): number {
+  if (activeEntity === undefined) return -1;
+  return cameraEntities.indexOf(activeEntity);
+}

package/src/systems/pass-selector.ts

@@ -0,0 +1,49 @@
+// M3 / w19: PassSelector matching logic
+// (feat-20260526-material-asset-multipass-renderstate)
+//
+// Pure-function helpers for matching MaterialPass tags against
+// a PassSelector. Plan-strategy D-4: Tags free Record + PassSelector
+// Record<string, string[]>. Requirements AC-05.
+
+import type { MaterialPass, PassSelector } from '@forgeax/engine-types';
+
+/**
+ * Test whether a pass's tags match a {@link PassSelector}.
+ *
+ * Matching rule (AC-05): every key in the selector must exist in the pass's
+ * `tags` and the pass's tag value must be in the selector's value list for
+ * that key. An empty selector matches every pass.
+ *
+ * @param tags The pass-level tags (free key-value pairs)
+ * @param selector The selector to match against
+ */
+export function matchPass(tags: Record<string, string>, selector: PassSelector): boolean {
+  if (Object.keys(selector).length === 0) return true;
+  for (const [key, allowedValues] of Object.entries(selector)) {
+    const passValue = tags[key];
+    if (passValue === undefined) return false;
+    if ((allowedValues as readonly string[]).length === 0) return false;
+    if (!(allowedValues as readonly string[]).includes(passValue)) return false;
+  }
+  return true;
+}
+
+/**
+ * Filter passes whose tags match the given {@link PassSelector}.
+ *
+ * An empty selector matches all passes (returns the input array reference).
+ * Otherwise each pass is checked via {@link matchPass}.
+ *
+ * @param passes The material's pass descriptors
+ * @param selector The pass selector
+ * @returns Filtered array of matching passes
+ */
+export function selectPasses(
+  passes: readonly MaterialPass[],
+  selector: PassSelector,
+): readonly MaterialPass[] {
+  if (Object.keys(selector).length === 0) return passes;
+  return passes.filter((p) =>
+    matchPass((p.renderState?.tags as Record<string, string> | undefined) ?? {}, selector),
+  );
+}