@forgeax/engine-render 0.1.7 → 0.1.19

package/src/errors/render.ts

@@ -13,6 +13,11 @@
 // SpotLight / PointLightShadow component validators (forward cross-directory
 // import, no cycle -- research Finding C2).
 
+import type {
+  RenderSurfaceFailureDetail,
+  SurfaceFailureCode,
+  SurfaceFailureKind,
+} from '@forgeax/engine-render-graph';
 import type { DeviceResourceKind, DeviceScopeReceipt } from '../device/resource-types';
 import type {
   PreparedKind,
@@ -20,6 +25,8 @@ import type {
   RenderFeatureRecovery,
   RenderFeatureStage,
 } from '../features/vocabulary';
+import type { SceneDataLane, SceneDataSchemaId } from '../temporal/scene-data';
+import type { TransmissionCapabilityFact } from '../transmission/backdrop';
 
 export interface LifecycleConstructionFailureDetail {
   readonly owner: string;
@@ -47,6 +54,68 @@ export class LifecycleConstructionError extends Error {
   }
 }
 
+const SURFACE_FAILURE_POLICY: Readonly<
+  Record<SurfaceFailureCode, { readonly expected: string; readonly hint: string }>
+> = {
+  'surface-allocation-failed': {
+    expected: 'the required surface resource can be allocated with its declared format and usage',
+    hint: 'inspect the capability detail, release transient resources, and retry the candidate graph',
+  },
+  'surface-attachment-failed': {
+    expected: 'the float target is renderable as the declared attachment',
+    hint: 'verify float color attachment support and retry without hiding the failure',
+  },
+  'surface-sampled-read-failed': {
+    expected: 'the float target can be sampled by the next post-processing stage',
+    hint: 'verify sampled-read support for the declared format before rebuilding the graph',
+  },
+  'surface-view-domain-failed': {
+    expected: 'surface storage and display views preserve their declared color domains',
+    hint: 'repair the explicit format/domain pair and retry the candidate graph',
+  },
+  'surface-raw-endpoint-failed': {
+    expected: 'the surface presentation endpoint has descriptor, acquisition, and validation proof',
+    hint: 'run the concrete presentation probe; keep the last-known-good surface when proof is absent',
+  },
+};
+
+/** Render-surface failure with an exhaustive code and actionable detail. */
+export class RenderSurfaceError<
+  Code extends SurfaceFailureCode = SurfaceFailureCode,
+> extends Error {
+  readonly code: Code;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: RenderSurfaceFailureDetail;
+
+  constructor(code: Code, detail: RenderSurfaceFailureDetail) {
+    const policy = SURFACE_FAILURE_POLICY[code];
+    if (policy === undefined) {
+      throw new Error(`unknown render surface failure code: ${code}`);
+    }
+    super(`[RenderSurfaceError ${code}] expected: ${policy.expected}; hint: ${policy.hint}`);
+    this.name = 'RenderSurfaceError';
+    this.code = code;
+    this.expected = policy.expected;
+    this.hint = policy.hint;
+    this.detail = detail;
+  }
+}
+
+export type { RenderSurfaceFailureDetail, SurfaceFailureCode, SurfaceFailureKind };
+
+export type RenderSurfaceExpectedError = {
+  readonly [Code in SurfaceFailureCode]: RenderSurfaceError<Code>;
+}[SurfaceFailureCode];
+
+/** Construct the closed surface error from its failure-stage discriminant. */
+export function createRenderSurfaceError(
+  kind: SurfaceFailureKind,
+  detail: RenderSurfaceFailureDetail,
+): RenderSurfaceExpectedError {
+  return new RenderSurfaceError(`surface-${kind}-failed` as SurfaceFailureCode, detail);
+}
+
 // ── ShadowInvalidConfigError ──────────────────────────────────────────────
 
 /**
@@ -563,6 +632,36 @@ export class MaterialSkinAttrMissingError extends Error {
   }
 }
 
+export interface TransmissionCapabilityMissingDetail {
+  readonly material: string;
+  readonly capability: 'transmission';
+  readonly stage: 'prepare' | 'record';
+  readonly lane: 'standard-forward';
+  readonly format: string;
+  readonly missing: readonly TransmissionCapabilityFact[];
+}
+
+export class TransmissionCapabilityMissingError extends Error {
+  readonly code = 'transmission-capability-missing' as const;
+  readonly expected = 'the renderer exposes the transmission capability for this material';
+  readonly hint = 'disable transmission or provide the renderer capability before drawing';
+  readonly detail: TransmissionCapabilityMissingDetail;
+
+  constructor(
+    material: string,
+    stage: 'prepare' | 'record',
+    evidence: {
+      readonly lane: 'standard-forward';
+      readonly format: string;
+      readonly missing: readonly TransmissionCapabilityFact[];
+    },
+  ) {
+    super(`transmission capability is missing for material '${material}'`);
+    this.name = 'TransmissionCapabilityMissingError';
+    this.detail = { material, capability: 'transmission', stage, ...evidence };
+  }
+}
+
 // -- RenderFeature errors ---------------------------------------------------
 
 export type RenderFeatureErrorCode =
@@ -931,6 +1030,63 @@ export class ObservationUnavailableError extends Error {
   }
 }
 
+export type SceneDataUnavailableReason =
+  | 'capability-missing'
+  | 'producer-missing'
+  | 'coverage-incomplete'
+  | 'renderer-recovering';
+export interface SceneDataUnavailableDetail {
+  readonly featureIdentity: string;
+  readonly schema: SceneDataSchemaId;
+  readonly lane: SceneDataLane;
+  readonly reason: SceneDataUnavailableReason;
+  readonly missingContributorIds: readonly string[];
+  readonly omittedMissingContributorCount: number;
+  readonly recovery: 'enable-capability' | 'next-frame' | 'renderer-recover';
+}
+export class SceneDataUnavailableError extends Error {
+  readonly code = 'scene-data-unavailable' as const;
+  readonly expected = 'the requested semantic scene data is available for the active plan';
+  readonly hint: string;
+  readonly detail: SceneDataUnavailableDetail;
+  constructor(detail: SceneDataUnavailableDetail) {
+    const hint =
+      detail.recovery === 'enable-capability'
+        ? 'enable rgba16floatRenderable and retry the current frame'
+        : detail.recovery === 'renderer-recover'
+          ? 'wait for renderer recovery, then retry the frame'
+          : 'restore the producer coverage and retry on the next frame';
+    super(`scene data '${detail.schema}' unavailable for '${detail.featureIdentity}'`);
+    this.name = 'SceneDataUnavailableError';
+    this.hint = hint;
+    this.detail = Object.freeze({
+      ...detail,
+      missingContributorIds: Object.freeze([...detail.missingContributorIds].slice(0, 32)),
+      omittedMissingContributorCount: Math.max(
+        detail.omittedMissingContributorCount,
+        Math.max(0, detail.missingContributorIds.length - 32),
+      ),
+    });
+  }
+}
+
+export class TaaUnavailableError extends Error {
+  readonly code = 'taa-unavailable' as const;
+  readonly expected =
+    'Standard TAA has a renderable rgba16float target and a complete resolve path';
+  readonly hint =
+    'enable rgba16float rendering or select none/fxaa explicitly; do not treat TAA as no-AA';
+  readonly detail: {
+    readonly reason: 'capability' | 'topology' | 'history';
+    readonly observed?: string;
+  };
+  constructor(reason: 'capability' | 'topology' | 'history', observed?: string) {
+    super(`taa-unavailable: ${reason}`);
+    this.name = 'TaaUnavailableError';
+    this.detail = observed === undefined ? { reason } : { reason, observed };
+  }
+}
+
 export interface FrameReceiptStaleDetail {
   readonly frameId: number;
   readonly receiptGeneration: number;
@@ -970,6 +1126,126 @@ export class RendererContractFailureError extends Error {
   }
 }
 
+export interface EnvironmentSourceConflictDetail {
+  readonly owners: readonly {
+    readonly kind: 'image' | 'atmosphere';
+    readonly entityKey: number;
+    readonly sourceKey: string;
+  }[];
+}
+
+export class EnvironmentSourceConflictError extends Error {
+  readonly code = 'environment-source-conflict' as const;
+  readonly expected = 'exactly one environment source owns the frame';
+  readonly hint = 'remove all but one image or atmosphere environment owner';
+  readonly detail: EnvironmentSourceConflictDetail;
+
+  constructor(owners: readonly EnvironmentSourceConflictDetail['owners'][number][]) {
+    super('environment source owners conflict');
+    this.name = 'EnvironmentSourceConflictError';
+    this.detail = { owners: owners.map((owner) => Object.freeze({ ...owner })) };
+  }
+}
+
+export interface FogCardinalityDetail {
+  readonly count: number;
+}
+
+export class FogCardinalityError extends Error {
+  readonly code = 'fog-cardinality' as const;
+  readonly expected = 'zero or one Fog owner contributes to a frame';
+  readonly hint = 'remove extra Fog owners so the resource owner has at most one';
+  readonly detail: FogCardinalityDetail;
+
+  constructor(count: number) {
+    super(`Fog owner cardinality is ${count}`);
+    this.name = 'FogCardinalityError';
+    this.detail = { count };
+  }
+}
+
+export interface TaaCapsInsufficientDetail {
+  readonly required: readonly string[];
+  readonly available: readonly string[];
+}
+
+export class TaaCapsInsufficientError extends Error {
+  readonly code = 'taa-caps-insufficient' as const;
+  readonly expected = 'the backend exposes the capabilities required by TAA';
+  readonly hint = 'select a backend with the required TAA capabilities or disable TAA on Camera';
+  readonly detail: TaaCapsInsufficientDetail;
+
+  constructor(required: readonly string[], available: readonly string[]) {
+    super('TAA capabilities are insufficient');
+    this.name = 'TaaCapsInsufficientError';
+    this.detail = { required: [...required], available: [...available] };
+  }
+}
+
+export interface EnvironmentGenerationFailedDetail {
+  readonly sourceKey: string;
+  readonly stage: 'prepare' | 'build' | 'execute' | 'finish' | 'submit';
+}
+
+export class EnvironmentGenerationFailedError extends Error {
+  readonly code = 'environment-generation-failed' as const;
+  readonly expected = 'the selected environment generation completes its owner stage';
+  readonly hint = 'inspect the stage and sourceKey, then retry after correcting the environment';
+  readonly detail: EnvironmentGenerationFailedDetail;
+
+  constructor(sourceKey: string, stage: EnvironmentGenerationFailedDetail['stage']) {
+    super(`environment generation failed during ${stage}`);
+    this.name = 'EnvironmentGenerationFailedError';
+    this.detail = { sourceKey, stage };
+  }
+}
+
+export interface AtmosphereInvalidParameterDetail {
+  readonly field: string;
+  readonly value: number;
+}
+
+export interface AtmosphereParameterRange {
+  readonly min: number;
+  readonly max: number;
+}
+
+export class AtmosphereInvalidParameterError extends Error {
+  readonly code = 'atmosphere-invalid-parameter' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: AtmosphereInvalidParameterDetail;
+
+  constructor(field: string, value: number, range: AtmosphereParameterRange) {
+    super(`Atmosphere.${field} is invalid`);
+    this.name = 'AtmosphereInvalidParameterError';
+    this.detail = { field, value };
+    const rangeText = Number.isFinite(range.max)
+      ? `[${range.min}, ${range.max}]`
+      : `>= ${range.min}`;
+    this.expected = `Atmosphere.${field} must be finite and ${rangeText}`;
+    this.hint = `set Atmosphere.${field} to a finite value ${rangeText}`;
+  }
+}
+
+export interface OwnerStageFailedDetail {
+  readonly owner: 'environment' | 'temporal' | 'fog' | 'renderer';
+  readonly stage: 'extract' | 'prepare' | 'record' | 'finish' | 'submit';
+}
+
+export class OwnerStageFailedError extends Error {
+  readonly code = 'owner-stage-failed' as const;
+  readonly expected = 'the owner completes its current frame stage';
+  readonly hint = 'inspect the owner and stage, keep the last-known-good frame, and retry';
+  readonly detail: OwnerStageFailedDetail;
+
+  constructor(owner: OwnerStageFailedDetail['owner'], stage: OwnerStageFailedDetail['stage']) {
+    super(`${owner} owner failed during ${stage}`);
+    this.name = 'OwnerStageFailedError';
+    this.detail = { owner, stage };
+  }
+}
+
 export interface RendererOperationCause {
   readonly code: string;
   readonly expected: string;
@@ -1256,6 +1532,8 @@ export type RenderError =
   | FrameReceiptStaleError
   | RendererContractFailureError
   | ObservationUnavailableError
+  | SceneDataUnavailableError
+  | TaaUnavailableError
   | ShadowInvalidConfigError
   | EquirectProjectionFailedError
   | HdrpLightBudgetExceededError
@@ -1269,6 +1547,7 @@ export type RenderError =
   | SkinPaletteOverflowError
   | SkinMaterialMismatchError
   | MaterialSkinAttrMissingError
+  | TransmissionCapabilityMissingError
   | RenderFeatureRegistrationConflictError
   | RenderFeatureStageFailedError
   | RenderFeatureCapabilityMissingError
@@ -1276,6 +1555,12 @@ export type RenderError =
   | RenderFeaturePreparationFailedError
   | RenderFeaturePreparedStateMismatchError
   | RenderFeatureDrawRecordingFailedError
+  | EnvironmentSourceConflictError
+  | FogCardinalityError
+  | TaaCapsInsufficientError
+  | EnvironmentGenerationFailedError
+  | AtmosphereInvalidParameterError
+  | OwnerStageFailedError
   | PointsLinesInvalidStyleError
   | PointsLinesTopologyMismatchError
   | PointsLinesStyleUnsupportedError

package/src/extract/camera.ts

@@ -0,0 +1,78 @@
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import { readRenderArrayView } from '@forgeax/engine-ecs/projection';
+import { mat4, vec3 } from '@forgeax/engine-math';
+import { Transform } from '@forgeax/engine-scene';
+import {
+  antialiasFromF32,
+  bloomEnabledFromF32,
+  Camera,
+  cameraProjectionFromF32,
+  tonemapFromF32,
+} from '../components/camera';
+import { MotionBlur } from '../components/motion-blur';
+import type { CameraSnapshot } from '../render-contract';
+import { getActiveCamera, selectActiveCameraIndex } from '../systems/active-camera';
+
+function readWorldMatrix(world: World, entity: EntityHandle): Float32Array | undefined {
+  const view = readRenderArrayView(world, entity, Transform, 'world');
+  return view === undefined ? undefined : new Float32Array(view);
+}
+
+/** Extract the selected camera once at the frame boundary. */
+export function extractCameraSnapshots(world: World): CameraSnapshot[] {
+  const cameras: CameraSnapshot[] = [];
+  const cameraEntities: number[] = [];
+  const cameraQuery = world
+    .query({ read: [Camera], optional: [MotionBlur], with: [Transform] })
+    .unwrap();
+  for (const row of cameraQuery) {
+    const cam = row.get(Camera);
+    const motionBlur = row.get(MotionBlur);
+    const entity = row.entity as EntityHandle;
+    const worldMat = readWorldMatrix(world, entity);
+    if (worldMat === undefined) continue;
+    cameras.push({
+      entityKey: entity as number,
+      historyVersion: cam.historyVersion,
+      position: mat4.getTranslation(vec3.create(), worldMat),
+      world: worldMat,
+      fov: cam.fov,
+      aspect: cam.aspect,
+      near: cam.near,
+      far: cam.far,
+      projection: cameraProjectionFromF32(cam.projection),
+      orthoLeft: cam.left,
+      orthoRight: cam.right,
+      orthoBottom: cam.bottom,
+      orthoTop: cam.top,
+      tonemap: tonemapFromF32(cam.tonemap),
+      exposure: cam.exposure,
+      whitePoint: cam.whitePoint,
+      antialias: antialiasFromF32(cam.antialias),
+      bloom: bloomEnabledFromF32(cam.bloom),
+      bloomThreshold: cam.bloomThreshold,
+      bloomIntensity: cam.bloomIntensity,
+      bloomBlurRadius: cam.bloomBlurRadius,
+      clearColor: [
+        cam.clearColor[0] ?? 0,
+        cam.clearColor[1] ?? 0,
+        cam.clearColor[2] ?? 0,
+        cam.clearColor[3] ?? 1,
+      ],
+      ...(motionBlur === undefined
+        ? {}
+        : {
+            motionBlur: {
+              shutterAngle: motionBlur.shutterAngle,
+              maxRadiusPixels: motionBlur.maxRadiusPixels,
+              sampleCount: motionBlur.sampleCount,
+            },
+          }),
+    });
+    cameraEntities.push(entity as number);
+  }
+  const selected = selectActiveCameraIndex(cameraEntities, getActiveCamera(world)?.entity);
+  if (selected < 0) return cameras;
+  const camera = cameras[selected];
+  return camera === undefined ? cameras : [camera];
+}

package/src/extract/environment.ts

@@ -0,0 +1,171 @@
+import type { World } from '@forgeax/engine-ecs';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { environmentFactSignatures } from '../environment/signature';
+import {
+  AtmosphereInvalidParameterError,
+  type AtmosphereParameterRange,
+  EnvironmentSourceConflictError,
+  FogCardinalityError,
+  type RenderError,
+} from '../errors/render';
+import type { TemporalView } from '../temporal/view';
+
+/** The retained projection's environment extraction owner. */
+export interface EnvironmentExtractionContext {
+  readonly resourceOwner: number;
+  readonly world: World;
+}
+
+/** Keep environment reads at the resource-owner frame boundary. */
+export function createEnvironmentExtractionContext(
+  world: World,
+  resourceOwner: number,
+): EnvironmentExtractionContext {
+  return Object.freeze({ world, resourceOwner });
+}
+
+export type EnvironmentCandidate =
+  | { readonly kind: 'image'; readonly entityKey: number; readonly sourceKey: string }
+  | {
+      readonly kind: 'atmosphere';
+      readonly entityKey: number;
+      readonly sourceKey: string;
+      readonly atmosphere: AtmosphereParameters;
+    };
+
+export interface AtmosphereParameters {
+  readonly turbidity: number;
+  readonly rayleigh: number;
+  readonly mieCoefficient: number;
+  readonly mieDirectionalG: number;
+  readonly sunAngularRadius: number;
+}
+
+/** Shared CPU contract for values accepted by the atmosphere shaders. */
+export const ATMOSPHERE_PARAMETER_RANGES: Readonly<
+  Record<keyof AtmosphereParameters, AtmosphereParameterRange>
+> = Object.freeze({
+  turbidity: Object.freeze({ min: 1, max: 20 }),
+  rayleigh: Object.freeze({ min: 0, max: Number.POSITIVE_INFINITY }),
+  mieCoefficient: Object.freeze({ min: 0, max: Number.POSITIVE_INFINITY }),
+  mieDirectionalG: Object.freeze({ min: 0, max: 0.999 }),
+  sunAngularRadius: Object.freeze({ min: 0, max: Number.POSITIVE_INFINITY }),
+});
+
+export interface FogCandidate {
+  readonly entityKey: number;
+  readonly color: readonly [number, number, number];
+  readonly density: number;
+  readonly heightFalloff: number;
+  readonly maxOpacity: number;
+}
+
+export type EnvironmentSource =
+  | { readonly kind: 'none' }
+  | {
+      readonly kind: 'image';
+      readonly entityKey: number;
+      readonly sourceKey: string;
+    }
+  | {
+      readonly kind: 'atmosphere';
+      readonly entityKey: number;
+      readonly sourceKey: string;
+      readonly atmosphere: AtmosphereParameters;
+    };
+
+export interface FogFrame extends FogCandidate {}
+
+export interface EnvironmentFrame {
+  readonly source: EnvironmentSource;
+  /** Descriptor of the real environment resource adopted for this frame. */
+  readonly resourceDescriptor?: Readonly<{
+    readonly width: number;
+    readonly height: number;
+    readonly bytesPerPixel: number;
+  }>;
+  readonly fog: FogFrame | undefined;
+  readonly environmentSignature: string;
+  readonly fogSignature: string;
+  readonly signature: string;
+  readonly revision: number;
+}
+
+export interface FramePlan {
+  readonly environment: EnvironmentFrame;
+  readonly temporal: TemporalView;
+}
+
+function freezeFog(candidate: FogCandidate): FogFrame {
+  return Object.freeze({
+    ...candidate,
+    color: Object.freeze([...candidate.color] as unknown as FogFrame['color']),
+  });
+}
+
+function freezeAtmosphere(parameters: AtmosphereParameters): AtmosphereParameters {
+  return Object.freeze({ ...parameters });
+}
+
+/** Return the first invalid analytic atmosphere field at the extraction boundary. */
+export function validateAtmosphereParameters(
+  parameters: AtmosphereParameters,
+): AtmosphereInvalidParameterError | undefined {
+  for (const field of Object.keys(ATMOSPHERE_PARAMETER_RANGES) as (keyof AtmosphereParameters)[]) {
+    const value = parameters[field];
+    const range = ATMOSPHERE_PARAMETER_RANGES[field];
+    if (!Number.isFinite(value) || value < range.min || value > range.max) {
+      return new AtmosphereInvalidParameterError(field, value, range);
+    }
+  }
+  return undefined;
+}
+
+/** Select immutable environment and independent Fog facts at the frame boundary. */
+export function selectEnvironmentFrame(
+  candidates: readonly EnvironmentCandidate[],
+  fogCandidates: readonly FogCandidate[],
+): Result<EnvironmentFrame, RenderError> {
+  if (candidates.length > 1) {
+    return err(
+      new EnvironmentSourceConflictError(
+        candidates.map(({ kind, entityKey, sourceKey }) => ({ kind, entityKey, sourceKey })),
+      ),
+    );
+  }
+  if (fogCandidates.length > 1) return err(new FogCardinalityError(fogCandidates.length));
+  const candidate = candidates[0];
+  if (candidate?.kind === 'atmosphere') {
+    const invalid = validateAtmosphereParameters(candidate.atmosphere);
+    if (invalid !== undefined) return err(invalid);
+  }
+  const source: EnvironmentSource =
+    candidate === undefined
+      ? { kind: 'none' }
+      : candidate.kind === 'atmosphere'
+        ? {
+            kind: 'atmosphere',
+            entityKey: candidate.entityKey,
+            sourceKey: candidate.sourceKey,
+            atmosphere: freezeAtmosphere(candidate.atmosphere),
+          }
+        : {
+            kind: 'image',
+            entityKey: candidate.entityKey,
+            sourceKey: candidate.sourceKey,
+          };
+  const fog = fogCandidates[0] === undefined ? undefined : freezeFog(fogCandidates[0]);
+  const signatures = environmentFactSignatures({
+    environments: candidate === undefined ? [] : [candidate],
+    fogs: fogCandidates,
+    suns: [],
+  });
+  return ok(
+    Object.freeze({
+      source: Object.freeze(source),
+      fog,
+      ...signatures,
+      revision: 0,
+    }),
+  );
+}

package/src/extract/visibility.ts

@@ -1,4 +1,4 @@
-import { Entity, type EntityHandle, type World } from '@forgeax/engine-ecs';
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
 import {
   projectHierarchy,
   type SceneHierarchyDiagnostic,
@@ -45,34 +45,53 @@ export function resolveVisibility(
   world: World,
   hierarchy: SceneHierarchySnapshot = projectHierarchy(world),
 ): VisibilitySnapshot {
-  const query = world.query({ read: [Entity], optional: [Visibility] });
+  // Visibility is an opt-in component. Query only the owning archetypes
+  // instead of walking every Entity row with an optional column; the latter
+  // made a World with no visibility intents pay a full-scene scan on each
+  // extraction. QueryRow.entity is sourced from the essential Entity column,
+  // so the required Visibility read retains the same handle and intent
+  // semantics while keeping the hot path sparse.
+  const query = world.query({ read: [Visibility] });
+  const visitVisibilityRows = (visit: (entity: EntityHandle, rawState: number) => void): void => {
+    if (!query.ok) return;
+    // Dense component spans keep the per-frame summary on typed-array reads
+    // instead of allocating a QueryRow facade for every visibility-bearing
+    // entity. Keep the row path as a defensive fallback if a future storage
+    // mode cannot expose spans.
+    const spans = query.value.spans();
+    if (spans.ok) {
+      for (const span of spans.value) {
+        const states = span.get(Visibility).state;
+        for (let index = 0; index < span.length; index += 1) {
+          visit(span.entities[index] as EntityHandle, states[index] ?? 0);
+        }
+      }
+      return;
+    }
+    for (const row of query.value) {
+      visit(row.entity, row.get(Visibility).state);
+    }
+  };
   let intentCount = 0;
   let hasAnyHiddenIntent = false;
-  if (query.ok) {
-    for (const row of query.value) {
-      const visibility = row.get(Visibility);
-      if (visibility === undefined) continue;
-      intentCount += 1;
-      if (visibility.state === VisibilityStateValue.hidden) {
-        hasAnyHiddenIntent = true;
-      }
+  visitVisibilityRows((_entity, rawState) => {
+    intentCount += 1;
+    if (rawState === VisibilityStateValue.hidden) {
+      hasAnyHiddenIntent = true;
     }
-  }
+  });
 
   let resolveEntity: ((entity: EntityHandle) => ResolutionState | undefined) | undefined;
   let hasIntent: ((entity: EntityHandle) => boolean) | undefined;
   const ensureResolver = (): void => {
     if (resolveEntity !== undefined) return;
     const intentByEntity = new Map<EntityHandle, VisibilityState>();
-    if (query.ok) {
-      for (const row of query.value) {
-        const raw = row.get(Visibility);
-        const intent = raw === undefined ? undefined : visibilityStateFromU32(raw.state);
-        if (intent !== undefined) {
-          intentByEntity.set(row.entity, intent);
-        }
+    visitVisibilityRows((entity, rawState) => {
+      const intent = visibilityStateFromU32(rawState);
+      if (intent !== undefined) {
+        intentByEntity.set(entity, intent);
       }
-    }
+    });
     hasIntent = (entity: EntityHandle): boolean => intentByEntity.has(entity);
     const resolved = new Map<EntityHandle, ResolutionState>();
     const resolving = new Set<EntityHandle>();