@forgeax/engine-render 0.1.19 → 0.1.21

package/src/targets/contracts.ts

@@ -0,0 +1,182 @@
+import type { RenderError } from '../errors/render';
+import {
+  RenderTargetCapabilityMissingError,
+  RenderTargetDescriptorInvalidError,
+} from '../errors/render';
+import type { RenderResult } from '../render-contract';
+
+export type RenderTargetFormat = 'rgba16float' | 'rgba8unorm' | 'rgba8unorm-srgb';
+export type RenderTargetShape = '2d' | 'cube';
+export type RenderTargetMipLevels = 1 | 'full';
+export type RenderTargetSampleCount = 1 | 4;
+export type RenderTargetDepthFormat = 'depth24plus-stencil8' | 'depth32float';
+
+export interface RenderTargetDescriptor {
+  readonly shape: RenderTargetShape;
+  readonly width: number;
+  readonly height: number;
+  readonly format: RenderTargetFormat;
+  readonly mipLevels: RenderTargetMipLevels;
+  readonly sampleCount: RenderTargetSampleCount;
+  readonly depth?: RenderTargetDepthFormat;
+  readonly sampled: boolean;
+  readonly readback: boolean;
+}
+
+declare const RenderTargetBrand: unique symbol;
+declare const RenderTargetTextureSourceBrand: unique symbol;
+declare const RenderTargetReadbackTicketBrand: unique symbol;
+
+/** Opaque logical target lease owned by one Renderer. */
+export interface RenderTarget {
+  readonly [RenderTargetBrand]: 'RenderTarget';
+}
+
+export type RenderTargetTextureAspect = 'color';
+
+export interface RenderTargetTextureSourceOptions {
+  readonly aspect: RenderTargetTextureAspect;
+  readonly dimension: RenderTargetShape;
+  readonly mipLevel: number;
+}
+
+/** Renderer-local runtime material source; it is not an asset handle. */
+export interface RenderTargetTextureSource {
+  readonly [RenderTargetTextureSourceBrand]: 'RenderTargetTextureSource';
+}
+
+export interface RenderTargetReadbackRequest {
+  readonly mipLevel: number;
+  /** Cube array layer to copy; 2D targets accept only the omitted form. */
+  readonly face?: number;
+}
+
+/** One-shot readback request bound to a future matching FrameReceipt. */
+export interface RenderTargetReadbackTicket {
+  readonly [RenderTargetReadbackTicketBrand]: 'RenderTargetReadbackTicket';
+}
+
+/** Bytes released by observe after the ticket's matching frame completes. */
+export interface RenderTargetReadbackData {
+  readonly ticket: RenderTargetReadbackTicket;
+  readonly bytes: Uint8Array;
+  readonly frameId: number;
+  readonly deviceGeneration: number;
+  readonly mipLevel: number;
+  readonly face?: number;
+  readonly bytesPerRow: number;
+  readonly byteLength: number;
+}
+
+export interface RenderTargetAdmissionLimits {
+  readonly maxTextureDimension2D: number;
+  readonly maxBytesPerTarget: number;
+  readonly renderableFormats: readonly RenderTargetFormat[];
+  readonly sampleCounts: readonly RenderTargetSampleCount[];
+  readonly depthFormats: readonly RenderTargetDepthFormat[];
+}
+
+const FORMAT_BYTES: Readonly<Record<RenderTargetFormat, number>> = {
+  rgba16float: 8,
+  rgba8unorm: 4,
+  'rgba8unorm-srgb': 4,
+};
+
+function mipFactor(mipLevels: RenderTargetMipLevels): number {
+  return mipLevels === 'full' ? 4 / 3 : 1;
+}
+
+function estimatedBytes(descriptor: RenderTargetDescriptor): number {
+  const layers = descriptor.shape === 'cube' ? 6 : 1;
+  const samples = descriptor.sampleCount;
+  const depthBytes = descriptor.depth === undefined ? 0 : 4;
+  return Math.ceil(
+    descriptor.width *
+      descriptor.height *
+      FORMAT_BYTES[descriptor.format] *
+      layers *
+      samples *
+      mipFactor(descriptor.mipLevels) +
+      descriptor.width *
+        descriptor.height *
+        depthBytes *
+        layers *
+        samples *
+        mipFactor(descriptor.mipLevels),
+  );
+}
+
+function invalid(
+  field: string,
+  value: unknown,
+  expected: string,
+): RenderResult<never, RenderError> {
+  return {
+    ok: false,
+    error: new RenderTargetDescriptorInvalidError({ field, value, expected }),
+  };
+}
+
+/** Validate descriptor facts before a renderer allocates a physical target. */
+export function admitRenderTargetDescriptor(
+  descriptor: RenderTargetDescriptor,
+  limits: RenderTargetAdmissionLimits,
+): RenderResult<RenderTargetDescriptor, RenderError> {
+  if (!Number.isInteger(descriptor.width) || descriptor.width < 1) {
+    return invalid('width', descriptor.width, 'an integer >= 1');
+  }
+  if (!Number.isInteger(descriptor.height) || descriptor.height < 1) {
+    return invalid('height', descriptor.height, 'an integer >= 1');
+  }
+  if (
+    descriptor.width > limits.maxTextureDimension2D ||
+    descriptor.height > limits.maxTextureDimension2D
+  ) {
+    return invalid(
+      'extent',
+      { width: descriptor.width, height: descriptor.height },
+      `width and height <= ${limits.maxTextureDimension2D}`,
+    );
+  }
+  if (descriptor.shape === 'cube' && descriptor.width !== descriptor.height) {
+    return invalid('shape', descriptor.shape, 'cube width === height');
+  }
+  if (!limits.renderableFormats.includes(descriptor.format)) {
+    return {
+      ok: false,
+      error: new RenderTargetCapabilityMissingError({
+        operation: 'create',
+        requested: descriptor.format,
+        capability: 'renderableFormats',
+        actual: limits.renderableFormats.join(', '),
+      }),
+    };
+  }
+  if (!limits.sampleCounts.includes(descriptor.sampleCount)) {
+    return {
+      ok: false,
+      error: new RenderTargetCapabilityMissingError({
+        operation: 'create',
+        requested: String(descriptor.sampleCount),
+        capability: 'sampleCounts',
+        actual: limits.sampleCounts.join(', '),
+      }),
+    };
+  }
+  if (descriptor.depth !== undefined && !limits.depthFormats.includes(descriptor.depth)) {
+    return {
+      ok: false,
+      error: new RenderTargetCapabilityMissingError({
+        operation: 'create',
+        requested: descriptor.depth,
+        capability: 'depthFormats',
+        actual: limits.depthFormats.join(', '),
+      }),
+    };
+  }
+  const bytes = estimatedBytes(descriptor);
+  if (bytes > limits.maxBytesPerTarget) {
+    return invalid('bytes', bytes, `estimated allocation <= ${limits.maxBytesPerTarget}`);
+  }
+  return { ok: true, value: descriptor };
+}

package/src/targets/graph-projection.ts

@@ -0,0 +1,169 @@
+import type {
+  GraphTexture,
+  GraphTextureView,
+  GraphTextureViewDescriptor,
+  RenderGraphBuilder,
+  RenderGraphFrame,
+} from '@forgeax/engine-render-graph';
+import type { Texture, TextureFormat, TextureView } from '@forgeax/engine-rhi';
+import type { RenderError } from '../errors/render';
+import { RenderTargetOperationFailedError, RenderTargetStateInvalidError } from '../errors/render';
+import type { RenderResult } from '../render-contract';
+import type { RenderTarget, RenderTargetDescriptor } from './contracts';
+
+export interface RenderTargetGraphInput {
+  readonly target: RenderTarget;
+  readonly generation: number;
+  readonly descriptor: RenderTargetDescriptor;
+  readonly texture: Texture;
+  readonly view: TextureView;
+  readonly resolveView?: TextureView | undefined;
+}
+
+export interface RenderTargetGraphSubresource {
+  readonly mipLevel?: number;
+  readonly face?: number;
+}
+
+export interface RenderTargetGraphProjection {
+  readonly ownership: 'imported';
+  readonly generation: number;
+  readonly texture: GraphTexture;
+  readonly view: GraphTextureView;
+  readonly sampleView: GraphTextureView;
+  readonly resolveView?: GraphTextureView | undefined;
+  readonly viewDescriptor: GraphTextureViewDescriptor;
+  readonly usage: readonly ('sampled-read' | 'copy-src')[];
+}
+
+function operationFailed(generation: number, cause: unknown): RenderResult<never, RenderError> {
+  return {
+    ok: false,
+    error: new RenderTargetOperationFailedError({
+      operation: 'source',
+      stage: 'copy',
+      generation,
+      cause,
+      recovery: 'retry',
+    }),
+  };
+}
+
+function mipCount(descriptor: RenderTargetDescriptor): number {
+  if (descriptor.mipLevels === 1) return 1;
+  return Math.floor(Math.log2(Math.max(descriptor.width, descriptor.height))) + 1;
+}
+
+function viewDescriptor(
+  descriptor: RenderTargetDescriptor,
+  subresource: RenderTargetGraphSubresource,
+): GraphTextureViewDescriptor {
+  const mipLevel = subresource.mipLevel ?? 0;
+  return {
+    dimension: descriptor.shape,
+    baseMipLevel: mipLevel,
+    mipLevelCount: 1,
+    ...(descriptor.shape === 'cube' && subresource.face === undefined
+      ? {}
+      : subresource.face === undefined
+        ? {}
+        : { baseArrayLayer: subresource.face, arrayLayerCount: 1 }),
+  };
+}
+
+function validateSubresource(
+  descriptor: RenderTargetDescriptor,
+  subresource: RenderTargetGraphSubresource,
+): RenderResult<void, RenderError> {
+  const mipLevel = subresource.mipLevel ?? 0;
+  if (!Number.isInteger(mipLevel) || mipLevel < 0 || mipLevel >= mipCount(descriptor)) {
+    return {
+      ok: false,
+      error: new RenderTargetStateInvalidError({
+        operation: 'source',
+        reason: 'uninitialized',
+        state: 'uninitialized',
+        generation: 0,
+      }),
+    };
+  }
+  if (
+    subresource.face !== undefined &&
+    (!Number.isInteger(subresource.face) || subresource.face < 0 || subresource.face > 5)
+  ) {
+    return {
+      ok: false,
+      error: new RenderTargetStateInvalidError({
+        operation: 'source',
+        reason: 'uninitialized',
+        state: 'uninitialized',
+        generation: 0,
+      }),
+    };
+  }
+  return { ok: true, value: undefined };
+}
+
+export function projectRenderTargetGraph<FrameCtx extends RenderGraphFrame>(
+  graph: RenderGraphBuilder<FrameCtx>,
+  input: RenderTargetGraphInput,
+  subresource: RenderTargetGraphSubresource = {},
+): RenderResult<RenderTargetGraphProjection, RenderError> {
+  const valid = validateSubresource(input.descriptor, subresource);
+  if (!valid.ok) return valid;
+  if (input.descriptor.sampleCount === 4 && input.resolveView === undefined) {
+    return operationFailed(
+      input.generation,
+      new Error('multisample target requires a single-sample resolve view before sampling'),
+    );
+  }
+  const descriptor = viewDescriptor(input.descriptor, subresource);
+  const imported = graph.importTexture(
+    `render-target.${input.generation}`,
+    {
+      format: input.descriptor.format as TextureFormat,
+      size: {
+        width: input.descriptor.width,
+        height: input.descriptor.height,
+        depthOrArrayLayers: input.descriptor.shape === 'cube' ? 6 : 1,
+      },
+      mipLevelCount: mipCount(input.descriptor),
+      sampleCount: input.descriptor.sampleCount,
+      dimension: '2d',
+      usage: 0x10 | 0x04 | (input.descriptor.readback ? 0x01 : 0),
+    },
+    () => input.texture,
+  );
+  if (!imported.ok) return operationFailed(input.generation, imported.error);
+  const view = graph.importView(imported.value, descriptor, () => input.view);
+  if (!view.ok) return operationFailed(input.generation, view.error);
+  let resolveView: GraphTextureView | undefined;
+  if (input.resolveView !== undefined) {
+    const resolved = graph.importView(
+      imported.value,
+      descriptor,
+      () => input.resolveView as TextureView,
+    );
+    if (!resolved.ok) return operationFailed(input.generation, resolved.error);
+    resolveView = resolved.value;
+  }
+  const sampleView = input.descriptor.sampleCount === 4 ? resolveView : view.value;
+  if (sampleView === undefined)
+    return operationFailed(input.generation, new Error('missing sample view'));
+  return {
+    ok: true,
+    value: {
+      ownership: 'imported',
+      generation: input.generation,
+      texture: imported.value,
+      view: view.value,
+      sampleView,
+      resolveView,
+      viewDescriptor: descriptor,
+      usage: [
+        ...(input.descriptor.sampled ? (['sampled-read'] as const) : []),
+        ...(input.descriptor.readback ? (['copy-src'] as const) : []),
+      ],
+    },
+  };
+}

package/src/targets/material-source.ts

@@ -0,0 +1,143 @@
+import type { TextureView } from '@forgeax/engine-rhi';
+import type { RenderError } from '../errors/render';
+import {
+  RenderTargetDescriptorInvalidError,
+  RenderTargetStateInvalidError,
+} from '../errors/render';
+import type { RenderResult } from '../render-contract';
+import type {
+  RenderTarget,
+  RenderTargetDescriptor,
+  RenderTargetTextureSource,
+  RenderTargetTextureSourceOptions,
+} from './contracts';
+
+export interface RenderTargetMaterialSourceView {
+  readonly dimension: RenderTargetTextureSourceOptions['dimension'];
+  readonly mipLevel: number;
+  readonly resolveRequired: boolean;
+}
+
+export interface RenderTargetMaterialSourceBinding {
+  readonly source: RenderTargetTextureSource;
+  readonly target: RenderTarget;
+  readonly generation: number;
+  readonly shape: RenderTargetDescriptor['shape'];
+  readonly format: RenderTargetDescriptor['format'];
+  readonly view: RenderTargetMaterialSourceView;
+  /** Renderer-local physical view, present only for the active generation. */
+  readonly textureView?: TextureView;
+}
+
+export interface RenderTargetMaterialSourceExpectation {
+  readonly target: RenderTarget;
+  readonly generation: number;
+  readonly shape: RenderTargetDescriptor['shape'];
+  readonly format: RenderTargetDescriptor['format'];
+  readonly dimension: RenderTargetTextureSourceOptions['dimension'];
+  readonly mipLevel: number;
+}
+
+const sourceBindings = new WeakMap<object, RenderTargetMaterialSourceBinding>();
+
+function sourceToken(): RenderTargetTextureSource {
+  return Object.freeze({}) as RenderTargetTextureSource;
+}
+
+/** Resolve a source only inside the renderer-owned material projection. */
+export function resolveRenderTargetMaterialSource(
+  source: RenderTargetTextureSource,
+): RenderTargetMaterialSourceBinding | undefined {
+  return sourceBindings.get(source as object);
+}
+
+function invalid(
+  field: string,
+  value: unknown,
+  expected: string,
+): RenderResult<never, RenderError> {
+  return {
+    ok: false,
+    error: new RenderTargetDescriptorInvalidError({ field, value, expected }),
+  };
+}
+
+export function createRenderTargetMaterialSource(
+  target: RenderTarget,
+  descriptor: RenderTargetDescriptor,
+  options: RenderTargetTextureSourceOptions & { readonly generation: number },
+): RenderResult<RenderTargetMaterialSourceBinding, RenderError> {
+  if (options.aspect !== 'color') return invalid('aspect', options.aspect, 'color');
+  if (options.dimension !== descriptor.shape) {
+    return invalid('dimension', options.dimension, `dimension matches ${descriptor.shape}`);
+  }
+  const mipCount =
+    descriptor.mipLevels === 1
+      ? 1
+      : Math.floor(Math.log2(Math.max(descriptor.width, descriptor.height))) + 1;
+  if (!Number.isInteger(options.mipLevel) || options.mipLevel < 0 || options.mipLevel >= mipCount) {
+    return invalid('mipLevel', options.mipLevel, `an admitted mip level below ${mipCount}`);
+  }
+  if (!Number.isInteger(options.generation) || options.generation < 0) {
+    return invalid('generation', options.generation, 'a non-negative device generation');
+  }
+  const result: RenderResult<RenderTargetMaterialSourceBinding, RenderError> = {
+    ok: true,
+    value: Object.freeze({
+      source: sourceToken(),
+      target,
+      generation: options.generation,
+      shape: descriptor.shape,
+      format: descriptor.format,
+      view: Object.freeze({
+        dimension: options.dimension,
+        mipLevel: options.mipLevel,
+        resolveRequired: descriptor.sampleCount === 4,
+      }),
+    }),
+  };
+  sourceBindings.set(result.value.source as object, result.value);
+  return result;
+}
+
+export function validateRenderTargetMaterialSource(
+  binding: RenderTargetMaterialSourceBinding,
+  expected: RenderTargetMaterialSourceExpectation,
+): RenderResult<void, RenderError> {
+  if (binding.target !== expected.target) {
+    return {
+      ok: false,
+      error: new RenderTargetStateInvalidError({
+        operation: 'source',
+        reason: 'foreign-renderer',
+        state: 'active',
+        generation: binding.generation,
+      }),
+    };
+  }
+  if (binding.generation !== expected.generation) {
+    return {
+      ok: false,
+      error: new RenderTargetStateInvalidError({
+        operation: 'source',
+        reason: 'generation-mismatch',
+        state: 'active',
+        generation: binding.generation,
+      }),
+    };
+  }
+  if (binding.shape !== expected.shape || binding.format !== expected.format) {
+    return invalid(
+      'descriptor',
+      { shape: binding.shape, format: binding.format },
+      'matching target descriptor',
+    );
+  }
+  if (
+    binding.view.dimension !== expected.dimension ||
+    binding.view.mipLevel !== expected.mipLevel
+  ) {
+    return invalid('view', binding.view, 'matching target view subresource');
+  }
+  return { ok: true, value: undefined };
+}

package/src/targets/owner.ts

@@ -0,0 +1,214 @@
+import type { RenderError } from '../errors/render';
+import { RenderTargetOperationFailedError, RenderTargetStateInvalidError } from '../errors/render';
+import type { RenderResult } from '../render-contract';
+import type { RenderTarget, RenderTargetDescriptor } from './contracts';
+
+export type RenderTargetOwnerState =
+  | 'uninitialized'
+  | 'candidate'
+  | 'active'
+  | 'rebuilding'
+  | 'destroyed';
+
+export interface RenderTargetPhysicalCandidate {
+  readonly generation: number;
+  readonly descriptor: RenderTargetDescriptor;
+}
+
+export interface RenderTargetOwnerInspection {
+  readonly token: RenderTarget;
+  readonly state: RenderTargetOwnerState;
+  readonly generation: number;
+  readonly descriptor: RenderTargetDescriptor;
+  readonly candidate?: RenderTargetPhysicalCandidate;
+}
+
+export interface RenderTargetOwnerOptions {
+  readonly rendererId: symbol;
+  readonly initialGeneration: number;
+}
+
+export interface RenderTargetOwner {
+  create(descriptor: RenderTargetDescriptor): RenderResult<RenderTarget, RenderError>;
+  stage(
+    target: RenderTarget,
+    descriptor?: RenderTargetDescriptor,
+  ): RenderResult<RenderTargetPhysicalCandidate, RenderError>;
+  promote(target: RenderTarget, generation: number): RenderResult<void, RenderError>;
+  rejectCandidate(
+    target: RenderTarget,
+    generation: number,
+    stage: 'allocation' | 'compile' | 'write' | 'submit',
+  ): RenderResult<void, RenderError>;
+  beginRecovery(target: RenderTarget, generation: number): RenderResult<void, RenderError>;
+  finishRecovery(target: RenderTarget): RenderResult<void, RenderError>;
+  retire(target: RenderTarget, generation: number): RenderResult<void, RenderError>;
+  destroy(target: RenderTarget): RenderResult<void, RenderError>;
+  inspect(target: RenderTarget): RenderResult<RenderTargetOwnerInspection, RenderError>;
+}
+
+interface TargetState {
+  readonly target: RenderTarget;
+  readonly rendererId: symbol;
+  state: RenderTargetOwnerState;
+  generation: number;
+  descriptor: RenderTargetDescriptor;
+  candidate: RenderTargetPhysicalCandidate | undefined;
+  retiredGenerations: Set<number>;
+}
+
+function frozenDescriptor(descriptor: RenderTargetDescriptor): RenderTargetDescriptor {
+  return Object.freeze({ ...descriptor });
+}
+
+function invalid(
+  operation: 'inspect' | 'resize' | 'source' | 'readback' | 'destroy',
+  reason: 'foreign-renderer' | 'destroyed' | 'uninitialized' | 'generation-mismatch',
+  state: RenderTargetOwnerState,
+  generation: number,
+): RenderResult<never, RenderError> {
+  return {
+    ok: false,
+    error: new RenderTargetStateInvalidError({ operation, reason, state, generation }),
+  };
+}
+
+function token(): RenderTarget {
+  return Object.freeze({}) as RenderTarget;
+}
+
+export function createRenderTargetOwner(options: RenderTargetOwnerOptions): RenderTargetOwner {
+  const targets = new WeakMap<object, TargetState>();
+  const requireTarget = (
+    target: RenderTarget,
+    operation: 'inspect' | 'resize' | 'source' | 'readback' | 'destroy',
+  ): RenderResult<TargetState, RenderError> => {
+    const state = targets.get(target as object);
+    if (state === undefined) return invalid(operation, 'foreign-renderer', 'destroyed', 0);
+    if (state.rendererId !== options.rendererId) {
+      return invalid(operation, 'foreign-renderer', state.state, state.generation);
+    }
+    if (state.state === 'destroyed') {
+      return invalid(operation, 'destroyed', state.state, state.generation);
+    }
+    return { ok: true, value: state };
+  };
+
+  return {
+    create(descriptor) {
+      const target = token();
+      targets.set(target as object, {
+        target,
+        rendererId: options.rendererId,
+        state: 'uninitialized',
+        generation: 0,
+        descriptor: frozenDescriptor(descriptor),
+        candidate: undefined,
+        retiredGenerations: new Set(),
+      });
+      return { ok: true, value: target };
+    },
+    stage(target, descriptor) {
+      const found = requireTarget(target, 'resize');
+      if (!found.ok) return found;
+      const state = found.value;
+      if (state.state === 'rebuilding') {
+        return invalid('resize', 'generation-mismatch', state.state, state.generation);
+      }
+      const candidate = Object.freeze({
+        generation: state.state === 'uninitialized' ? options.initialGeneration : state.generation,
+        descriptor: frozenDescriptor(descriptor ?? state.descriptor),
+      });
+      state.candidate = candidate;
+      state.state = 'candidate';
+      return { ok: true, value: candidate };
+    },
+    promote(target, generation) {
+      const found = requireTarget(target, 'resize');
+      if (!found.ok) return found;
+      const state = found.value;
+      if (state.candidate?.generation !== generation) {
+        return invalid('resize', 'generation-mismatch', state.state, state.generation);
+      }
+      state.descriptor = state.candidate.descriptor;
+      state.generation = generation;
+      state.candidate = undefined;
+      state.state = 'active';
+      return { ok: true, value: undefined };
+    },
+    rejectCandidate(target, generation, stage) {
+      const found = requireTarget(target, 'resize');
+      if (!found.ok) return found;
+      const state = found.value;
+      if (state.candidate?.generation !== generation) {
+        return invalid('resize', 'generation-mismatch', state.state, state.generation);
+      }
+      state.candidate = undefined;
+      state.state = state.generation === 0 ? 'uninitialized' : 'active';
+      return {
+        ok: false,
+        error: new RenderTargetOperationFailedError({
+          operation: 'resize',
+          stage,
+          generation,
+          cause: new Error(`candidate ${generation} failed during ${stage}`),
+          recovery: state.generation === 0 ? 'retry' : 'retain-last-known-good',
+        }),
+      };
+    },
+    beginRecovery(target, generation) {
+      const found = requireTarget(target, 'resize');
+      if (!found.ok) return found;
+      const state = found.value;
+      if (state.state !== 'active' || generation <= state.generation) {
+        return invalid('resize', 'generation-mismatch', state.state, state.generation);
+      }
+      state.generation = generation;
+      state.candidate = undefined;
+      state.state = 'rebuilding';
+      return { ok: true, value: undefined };
+    },
+    finishRecovery(target) {
+      const found = requireTarget(target, 'resize');
+      if (!found.ok) return found;
+      const state = found.value;
+      if (state.state !== 'rebuilding') {
+        return invalid('resize', 'generation-mismatch', state.state, state.generation);
+      }
+      state.state = 'uninitialized';
+      return { ok: true, value: undefined };
+    },
+    retire(target, generation) {
+      const found = requireTarget(target, 'destroy');
+      if (!found.ok) return found;
+      found.value.retiredGenerations.add(generation);
+      return { ok: true, value: undefined };
+    },
+    destroy(target) {
+      const state = targets.get(target as object);
+      if (state === undefined) return invalid('destroy', 'foreign-renderer', 'destroyed', 0);
+      if (state.rendererId !== options.rendererId) {
+        return invalid('destroy', 'foreign-renderer', state.state, state.generation);
+      }
+      if (state.state === 'destroyed') return { ok: true, value: undefined };
+      state.candidate = undefined;
+      state.state = 'destroyed';
+      return { ok: true, value: undefined };
+    },
+    inspect(target) {
+      const found = requireTarget(target, 'inspect');
+      if (!found.ok) return found;
+      const state = found.value;
+      return {
+        ok: true,
+        value: Object.freeze({
+          token: state.target,
+          state: state.state,
+          generation: state.generation,
+          descriptor: state.descriptor,
+          ...(state.candidate === undefined ? {} : { candidate: state.candidate }),
+        }),
+      };
+    },
+  };
+}