@haiyue/extensions 0.1.0 → 0.2.0

package/src/animation/Animation2DRenderSystem.ts

@@ -1,1026 +0,0 @@
-import {
-  alignUp4,
-  beginRenderCommandPass,
-  cloneRenderPassDescriptor,
-  estimateTextureBytes,
-  getExtensionGPUResourceTracker,
-  requireEngineDevice,
-  type IEngine,
-  type ExtensionGPUResourceTracker,
-  type RenderCommandContext,
-  getExtensionSharedRendererResource,
-} from '@haiyue/engine/extension-authoring';
-import { Entity, type World } from '@haiyue/engine/ecs';
-import { RenderSystem2DBase, type RenderSystem2DBaseOptions } from '../utils/RenderSystem2DBase';
-import {
-  createCamera2DGpu,
-  createCamera2DLayout,
-  destroyCamera2DGpu,
-  type Camera2DGpu,
-} from '../utils/render2dGpu';
-import animation2dWgsl from '../shaders/generated/2d-ui-animation-2d.generated.wgsl';
-import { AnimationVisual2D } from './AnimationVisual2D';
-import type { AnimationCompositeLayer } from '@haiyue/animation-spec';
-
-export interface Animation2DRenderSystemOptions extends RenderSystem2DBaseOptions {
-  /** Bounds view-sized alpha targets used by masks and mattes. */
-  maxMaskTargets?: number;
-}
-
-export interface Animation2DRenderStats {
-  readonly visualCount: number;
-  readonly maskTargetCount: number;
-  readonly compositeLayerCount: number;
-  readonly droppedCompositeCount: number;
-  readonly maskPixels: number;
-  readonly effectTargetCount: number;
-  readonly droppedEffectCount: number;
-  /** Counts the reusable ping-pong RGBA targets owned by each active view. */
-  readonly effectPixels: number;
-}
-
-interface EntityGpu {
-  buffer: GPUBuffer;
-  bindGroup: GPUBindGroup;
-  data: Float32Array;
-  externalTexture: GPUTexture | null;
-  externalSource: ImageBitmap | HTMLCanvasElement | HTMLImageElement | null;
-  externalVersion: number;
-  externalWidth: number;
-  externalHeight: number;
-  externalBindGroup: GPUBindGroup | null;
-}
-
-interface GeometryGpu {
-  vertexBuffer: GPUBuffer;
-  indexBuffer: GPUBuffer | null;
-  indexCount: number;
-  vertexCount: number;
-  indexFormat: GPUIndexFormat;
-  version: number;
-}
-
-interface MaskTarget {
-  texture: GPUTexture;
-  view: GPUTextureView;
-  width: number;
-  height: number;
-  lastFrame: number;
-}
-
-interface EffectTarget {
-  textures: readonly [GPUTexture, GPUTexture];
-  views: readonly [GPUTextureView, GPUTextureView];
-  width: number;
-  height: number;
-  lastFrame: number;
-}
-
-interface AnimationRenderItem {
-  entity: Entity;
-  visual: AnimationVisual2D;
-}
-
-const SHADER = animation2dWgsl;
-const MAX_COMPOSITE_LAYERS = 8;
-const COMPOSITE_PARAMS_OFFSET = 28;
-const COMPOSITE_EXPANSION_OFFSET = COMPOSITE_PARAMS_OFFSET + MAX_COMPOSITE_LAYERS * 4;
-const GRADIENT_PARAMS_OFFSET = COMPOSITE_EXPANSION_OFFSET + MAX_COMPOSITE_LAYERS;
-const GRADIENT_GEOMETRY_OFFSET = GRADIENT_PARAMS_OFFSET + 4;
-const GRADIENT_COLORS_OFFSET = GRADIENT_GEOMETRY_OFFSET + 4;
-const GRADIENT_OFFSETS_OFFSET = GRADIENT_COLORS_OFFSET + 8 * 4;
-const EFFECT_KINDS_OFFSET = GRADIENT_OFFSETS_OFFSET + 8;
-const EFFECT_DATA_OFFSET = EFFECT_KINDS_OFFSET + 8;
-const EFFECT_FLOATS = 24;
-const MAX_EFFECTS = 8;
-const OBJECT_FLOATS = EFFECT_DATA_OFFSET + MAX_EFFECTS * EFFECT_FLOATS;
-const OBJECT_BYTES = OBJECT_FLOATS * 4;
-
-interface Animation2DSharedGpu {
-  readonly cameraLayout: GPUBindGroupLayout;
-  readonly objectLayout: GPUBindGroupLayout;
-  readonly textureLayout: GPUBindGroupLayout;
-  readonly compositeLayout: GPUBindGroupLayout;
-  readonly sampler: GPUSampler;
-  readonly shader: GPUShaderModule;
-  readonly pipelineLayout: GPUPipelineLayout;
-  readonly pipelines: Map<string, GPURenderPipeline>;
-  readonly whiteTexture: GPUTexture;
-  readonly whiteBindGroup: GPUBindGroup;
-  readonly emptyCompositeBindGroup: GPUBindGroup;
-  readonly transparentTexture: GPUTexture;
-  readonly transparentBindGroup: GPUBindGroup;
-  destroy(): void;
-}
-
-function getAnimation2DSharedGpu(
-  device: GPUDevice,
-  tracker: ExtensionGPUResourceTracker | undefined,
-): Animation2DSharedGpu {
-  return getExtensionSharedRendererResource(
-    device,
-    'Animation2D.sharedGpu:v1',
-    () => createAnimation2DSharedGpu(device, tracker),
-  );
-}
-
-function createAnimation2DSharedGpu(
-  device: GPUDevice,
-  tracker: ExtensionGPUResourceTracker | undefined,
-): Animation2DSharedGpu {
-  const cameraLayout = createCamera2DLayout(device);
-  const objectLayout = device.createBindGroupLayout({
-    entries: [{
-      binding: 0,
-      visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
-      buffer: { type: 'uniform' },
-    }],
-  });
-  const textureLayout = device.createBindGroupLayout({ entries: [
-    { binding: 0, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: 'float' } },
-    { binding: 1, visibility: GPUShaderStage.FRAGMENT, sampler: { type: 'filtering' } },
-  ] });
-  const compositeLayout = device.createBindGroupLayout({ entries: [
-    ...Array.from({ length: MAX_COMPOSITE_LAYERS }, (_, binding) => ({
-      binding,
-      visibility: GPUShaderStage.FRAGMENT,
-      texture: { sampleType: 'float' as const },
-    })),
-    { binding: MAX_COMPOSITE_LAYERS, visibility: GPUShaderStage.FRAGMENT, sampler: { type: 'filtering' } },
-  ] });
-  const sampler = device.createSampler({ magFilter: 'linear', minFilter: 'linear' });
-  const shader = device.createShaderModule({ label: 'Animation2D.shader', code: SHADER });
-  const pipelineLayout = device.createPipelineLayout({
-    bindGroupLayouts: [cameraLayout, objectLayout, textureLayout, compositeLayout],
-  });
-  const createTextureBindGroup = (texture: GPUTexture): GPUBindGroup => device.createBindGroup({
-    layout: textureLayout,
-    entries: [
-      { binding: 0, resource: texture.createView() },
-      { binding: 1, resource: sampler },
-    ],
-  });
-  const whiteTexture = device.createTexture({
-    size: [1, 1],
-    format: 'rgba8unorm',
-    usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
-  });
-  tracker?.trackTexture(whiteTexture, 'Animation2D.sharedWhiteTexture', 4);
-  device.queue.writeTexture(
-    { texture: whiteTexture },
-    new Uint8Array([255, 255, 255, 255]),
-    { bytesPerRow: 4 },
-    [1, 1],
-  );
-  const whiteBindGroup = createTextureBindGroup(whiteTexture);
-  const emptyCompositeBindGroup = device.createBindGroup({
-    layout: compositeLayout,
-    entries: [
-      ...Array.from({ length: MAX_COMPOSITE_LAYERS }, (_, binding) => ({
-        binding,
-        resource: whiteTexture.createView(),
-      })),
-      { binding: MAX_COMPOSITE_LAYERS, resource: sampler },
-    ],
-  });
-  const transparentTexture = device.createTexture({
-    size: [1, 1],
-    format: 'rgba8unorm',
-    usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
-  });
-  tracker?.trackTexture(transparentTexture, 'Animation2D.sharedTransparentTexture', 4);
-  device.queue.writeTexture(
-    { texture: transparentTexture },
-    new Uint8Array([255, 255, 255, 0]),
-    { bytesPerRow: 4 },
-    [1, 1],
-  );
-  const transparentBindGroup = createTextureBindGroup(transparentTexture);
-  return {
-    cameraLayout,
-    objectLayout,
-    textureLayout,
-    compositeLayout,
-    sampler,
-    shader,
-    pipelineLayout,
-    pipelines: new Map(),
-    whiteTexture,
-    whiteBindGroup,
-    emptyCompositeBindGroup,
-    transparentTexture,
-    transparentBindGroup,
-    destroy(): void {
-      tracker?.untrackTexture(whiteTexture);
-      tracker?.untrackTexture(transparentTexture);
-      whiteTexture.destroy();
-      transparentTexture.destroy();
-      this.pipelines.clear();
-    },
-  };
-}
-
-export class Animation2DRenderSystem extends RenderSystem2DBase {
-  private readonly maxMaskTargets: number;
-  private rendererReady = false;
-  private cameraGpu!: Camera2DGpu;
-  private objectLayout!: GPUBindGroupLayout;
-  private textureLayout!: GPUBindGroupLayout;
-  private compositeLayout!: GPUBindGroupLayout;
-  private sampler!: GPUSampler;
-  private whiteTexture!: GPUTexture;
-  private whiteBindGroup!: GPUBindGroup;
-  private emptyCompositeBindGroup!: GPUBindGroup;
-  private transparentTexture!: GPUTexture;
-  private transparentBindGroup!: GPUBindGroup;
-  private shader!: GPUShaderModule;
-  private pipelineLayout!: GPUPipelineLayout;
-  private pipelines!: Map<string, GPURenderPipeline>;
-  private readonly entityGpu = new Map<number, EntityGpu>();
-  private readonly geometryGpu = new Map<number, GeometryGpu>();
-  private textureBindGroups = new WeakMap<GPUTexture, GPUBindGroup>();
-  private readonly maskTargets = new Map<string, MaskTarget>();
-  private readonly effectTargets = new Map<string, EffectTarget>();
-  private readonly items: AnimationRenderItem[] = [];
-  private readonly sourceItems = new Map<string, AnimationRenderItem[]>();
-  private readonly sourceGroupPool: AnimationRenderItem[][] = [];
-  private readonly activeMaskTargets = new Map<string, MaskTarget>();
-  private readonly compositeBindGroups = new Map<string, GPUBindGroup>();
-  private readonly liveGeometryIds = new Set<number>();
-  private _visualCount = 0;
-  private _maskTargetCount = 0;
-  private _compositeLayerCount = 0;
-  private _droppedCompositeCount = 0;
-  private _maskPixels = 0;
-  private _effectTargetCount = 0;
-  private _droppedEffectCount = 0;
-  private _effectPixels = 0;
-
-  constructor(engine: IEngine, cameraEntity: Entity, options: Animation2DRenderSystemOptions = {}) {
-    // Optional extension subpaths can be bundled as independent module graphs.
-    // Query by the stable global component symbol so a visual created by the
-    // HYA state-machine subpath is visible to the animation renderer subpath.
-    super({ all: [AnimationVisual2D.UniqueSymbol] }, engine, cameraEntity, { ...options, loadOp: options.loadOp ?? 'load' }, 'Animation2DRenderSystem');
-    this.maxMaskTargets = positiveInteger(options.maxMaskTargets ?? 32, 'maxMaskTargets');
-  }
-
-  get stats(): Animation2DRenderStats {
-    return Object.freeze({
-      visualCount: this._visualCount,
-      maskTargetCount: this._maskTargetCount,
-      compositeLayerCount: this._compositeLayerCount,
-      droppedCompositeCount: this._droppedCompositeCount,
-      maskPixels: this._maskPixels,
-      effectTargetCount: this._effectTargetCount,
-      droppedEffectCount: this._droppedEffectCount,
-      effectPixels: this._effectPixels,
-    });
-  }
-
-  get renderPipelineOptions() {
-    return { pass: 'isolated' as const, loadOp: this.loadOp, sort: this.priority };
-  }
-
-  record(world: World, context: RenderCommandContext): this {
-    if (this.disabled) return this;
-    if (!this.rendererReady) this.prepare();
-    if (!this.writeCameraBuffer(context.device.queue, this.cameraGpu.buffer, context)) return this;
-    const liveEntities = this.beginLiveEntityTracking();
-    this.items.length = 0;
-    const entities = this.entitySet.get(world);
-    if (entities) for (const entity of entities) {
-      if (!this.isEntityRenderable(entity)) continue;
-      const visual = entity.getComponent(AnimationVisual2D.UniqueSymbol) as AnimationVisual2D | null;
-      if (!visual) continue;
-      this.items.push({ entity, visual });
-      this.markEntityLive(entity);
-    }
-    this.items.sort(compareItems);
-
-    const frame = context.frameData?.frameId ?? 0;
-    this.sourceItems.clear();
-    let sourceGroupCount = 0;
-    for (const item of this.items) {
-      if (!item.visual.sourceOnly) continue;
-      const key = visualNodeKey(item.visual);
-      let group = this.sourceItems.get(key);
-      if (!group) {
-        group = this.sourceGroupPool[sourceGroupCount] ?? [];
-        group.length = 0;
-        this.sourceGroupPool[sourceGroupCount++] = group;
-        this.sourceItems.set(key, group);
-      }
-      group.push(item);
-    }
-
-    const maskTargets = this.activeMaskTargets;
-    maskTargets.clear();
-    let maskPixels = 0;
-    let maskCount = 0;
-    let droppedCompositeCount = 0;
-    let compositeLayerCount = 0;
-    let effectCount = 0;
-    let droppedEffectCount = 0;
-    let effectPixels = 0;
-    for (const sourceKey of orderSourceGroups(this.sourceItems)) {
-      const sources = this.sourceItems.get(sourceKey)!;
-      if (maskCount >= this.maxMaskTargets) break;
-      const targetKey = `${context.view?.key ?? 'default'}:${sourceKey}`;
-      const target = this.getMaskTarget(targetKey, context, frame);
-      maskPixels += target.width * target.height;
-      maskCount++;
-      let initialized = false;
-      for (const source of sources) {
-        const resolved = this.resolveCompositeBindGroup(source.visual, maskTargets, context.view?.key ?? 'default');
-        if (!resolved) { droppedCompositeCount++; continue; }
-        compositeLayerCount += source.visual.compositeLayers.length;
-        const effectTarget = source.visual.effects.length > 0 && !context.passEncoder
-          ? this.renderEffectStack(source, context, resolved, frame)
-          : null;
-        if (effectTarget) {
-          effectCount++;
-          if (effectPixels === 0) effectPixels = effectTarget.width * effectTarget.height * 2;
-        } else if (source.visual.effects.length > 0) droppedEffectCount++;
-        const pass = this.beginMaskSegment(context, target, sourceKey, initialized);
-        if (effectTarget) {
-          pass.setPipeline(this.getPresentPipeline('rgba8unorm', 1, false, false));
-          this.drawEffectResult(pass, source.entity, effectTarget.texture);
-        } else {
-          pass.setPipeline(this.getPipeline('rgba8unorm', 1, false, false));
-          this.draw(pass, source.entity, source.visual, context, resolved, true);
-        }
-        pass.end();
-        initialized = true;
-      }
-      if (!initialized) this.beginMaskSegment(context, target, sourceKey, false).end();
-      maskTargets.set(sourceKey, target);
-    }
-
-    const pending: Array<{ item: AnimationRenderItem; composite: GPUBindGroup }> = [];
-    const outputFormat = context.view?.target.format ?? this.engine.format;
-    let firstOutputSegment = true;
-    let visualCount = 0;
-    const flushOutput = (effectItem?: AnimationRenderItem, effectTexture?: GPUTexture): void => {
-      if (pending.length === 0 && !effectItem && !firstOutputSegment) return;
-      const { passEncoder, ownsPass } = this.beginOutputSegment(context, firstOutputSegment);
-      firstOutputSegment = false;
-      applyViewport(passEncoder, context);
-      passEncoder.setBindGroup(0, this.cameraGpu.bindGroup);
-      for (const entry of pending) {
-        passEncoder.setPipeline(this.getPipeline(
-          outputFormat, context.view?.sampleCount ?? this.engine.msaaSamples, true, context.view?.reverseZ ?? this.engine.reverseZ,
-        ));
-        this.draw(passEncoder, entry.item.entity, entry.item.visual, context, entry.composite, false);
-        visualCount++;
-      }
-      pending.length = 0;
-      if (effectItem && effectTexture) {
-        passEncoder.setPipeline(this.getPresentPipeline(
-          outputFormat, context.view?.sampleCount ?? this.engine.msaaSamples, true, context.view?.reverseZ ?? this.engine.reverseZ,
-        ));
-        this.drawEffectResult(passEncoder, effectItem.entity, effectTexture);
-        visualCount++;
-      }
-      if (ownsPass) passEncoder.end();
-    };
-    for (const item of this.items) {
-      const { visual } = item;
-      if (visual.sourceOnly) continue;
-      const resolved = this.resolveCompositeBindGroup(visual, maskTargets, context.view?.key ?? 'default');
-      if (!resolved) { droppedCompositeCount++; continue; }
-      compositeLayerCount += visual.compositeLayers.length;
-      if (visual.effects.length > 0 && !context.passEncoder) {
-        const effectTarget = this.renderEffectStack(item, context, resolved, frame);
-        effectCount++;
-        if (effectPixels === 0) effectPixels = effectTarget.width * effectTarget.height * 2;
-        flushOutput(item, effectTarget.texture);
-      } else {
-        if (visual.effects.length > 0) droppedEffectCount++;
-        pending.push({ item, composite: resolved });
-      }
-    }
-    flushOutput();
-
-    this.releaseEntityGpuEntriesNotIn(this.entityGpu, gpu => this.destroyEntityGpu(gpu), liveEntities);
-    this.sweepGeometryGpu();
-    this.sweepMaskTargets(frame, context);
-    this.sweepEffectTargets(frame, context);
-    this._visualCount = visualCount;
-    this._maskTargetCount = maskCount;
-    this._compositeLayerCount = compositeLayerCount;
-    this._droppedCompositeCount = droppedCompositeCount;
-    this._maskPixels = maskPixels;
-    this._effectTargetCount = effectCount > 0 ? 1 : 0;
-    this._droppedEffectCount = droppedEffectCount;
-    this._effectPixels = effectPixels;
-    return this;
-  }
-
-  override destroy(): this {
-    this.releaseGpuResourcesForRecovery();
-    return super.destroy();
-  }
-
-  protected releaseGpuResourcesForRecovery(): void {
-    if (!this.rendererReady) return;
-    destroyCamera2DGpu(this.cameraGpu);
-    this.destroyEntityGpuEntries(this.entityGpu, gpu => this.destroyEntityGpu(gpu));
-    for (const gpu of this.geometryGpu.values()) this.destroyGeometryGpu(gpu);
-    this.geometryGpu.clear();
-    for (const target of this.maskTargets.values()) this.destroyMaskTarget(target);
-    this.maskTargets.clear();
-    for (const target of this.effectTargets.values()) this.destroyEffectTarget(target);
-    this.effectTargets.clear();
-    this.activeMaskTargets.clear();
-    this.compositeBindGroups.clear();
-    this.textureBindGroups = new WeakMap();
-    this.rendererReady = false;
-  }
-
-  private prepare(): void {
-    const device = requireEngineDevice(this.engine);
-    const tracker = getExtensionGPUResourceTracker(this.engine);
-    const shared = getAnimation2DSharedGpu(device, tracker);
-    this.cameraGpu = createCamera2DGpu(device, tracker, shared.cameraLayout);
-    this.objectLayout = shared.objectLayout;
-    this.textureLayout = shared.textureLayout;
-    this.compositeLayout = shared.compositeLayout;
-    this.sampler = shared.sampler;
-    this.whiteTexture = shared.whiteTexture;
-    this.whiteBindGroup = shared.whiteBindGroup;
-    this.emptyCompositeBindGroup = shared.emptyCompositeBindGroup;
-    this.transparentTexture = shared.transparentTexture;
-    this.transparentBindGroup = shared.transparentBindGroup;
-    this.shader = shared.shader;
-    this.pipelineLayout = shared.pipelineLayout;
-    this.pipelines = shared.pipelines;
-    this.rendererReady = true;
-  }
-
-  private beginMaskSegment(
-    context: RenderCommandContext,
-    target: MaskTarget,
-    sourceKey: string,
-    initialized: boolean,
-  ): GPURenderPassEncoder {
-    const pass = context.encoder.beginRenderPass({
-      label: `Animation2D.mask:${sourceKey}`,
-      colorAttachments: [{
-        view: target.view,
-        clearValue: { r: 0, g: 0, b: 0, a: 0 },
-        loadOp: initialized ? 'load' : 'clear',
-        storeOp: 'store',
-      }],
-    });
-    applyViewport(pass, context);
-    pass.setBindGroup(0, this.cameraGpu.bindGroup);
-    return pass;
-  }
-
-  private beginOutputSegment(
-    context: RenderCommandContext,
-    first: boolean,
-  ): { passEncoder: GPURenderPassEncoder; ownsPass: boolean } {
-    if (first) return beginRenderCommandPass(context);
-    if (!context.descriptor) throw new Error('Animation2D ordered effects require an isolated render-pass descriptor.');
-    return { passEncoder: context.encoder.beginRenderPass(cloneRenderPassDescriptor(context.descriptor, 'load')), ownsPass: true };
-  }
-
-  private getPipeline(format: GPUTextureFormat, sampleCount: 1 | 4, withDepth: boolean, reverseZ: boolean): GPURenderPipeline {
-    const depthFormat = withDepth ? this.engine.getDepthFormat(reverseZ) : 'none';
-    const key = `visual:${format}:${sampleCount}:${depthFormat}:${reverseZ ? 1 : 0}`;
-    const cached = this.pipelines.get(key);
-    if (cached) return cached;
-    const pipeline = requireEngineDevice(this.engine).createRenderPipeline({
-      label: `Animation2D.pipeline:${key}`,
-      layout: this.pipelineLayout,
-      vertex: { module: this.shader, entryPoint: 'vs_main', buffers: [{
-        arrayStride: 16,
-        attributes: [
-          { shaderLocation: 0, offset: 0, format: 'float32x2' },
-          { shaderLocation: 1, offset: 8, format: 'float32x2' },
-        ],
-      }] },
-      fragment: { module: this.shader, entryPoint: 'fs_main', targets: [{ format, blend: {
-        color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
-        alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
-      } }] },
-      primitive: { topology: 'triangle-list', cullMode: 'none' },
-      ...(withDepth ? { depthStencil: {
-        format: depthFormat as GPUTextureFormat,
-        depthWriteEnabled: false,
-        depthCompare: 'always' as const,
-      } } : {}),
-      multisample: { count: sampleCount },
-    });
-    this.pipelines.set(key, pipeline);
-    return pipeline;
-  }
-
-  private getEffectPipeline(): GPURenderPipeline {
-    const key = 'effect:rgba8unorm';
-    const cached = this.pipelines.get(key);
-    if (cached) return cached;
-    const pipeline = requireEngineDevice(this.engine).createRenderPipeline({
-      label: 'Animation2D.effectPipeline',
-      layout: this.pipelineLayout,
-      vertex: { module: this.shader, entryPoint: 'vs_effect' },
-      fragment: { module: this.shader, entryPoint: 'fs_effect', targets: [{ format: 'rgba8unorm' }] },
-      primitive: { topology: 'triangle-list', cullMode: 'none' },
-    });
-    this.pipelines.set(key, pipeline);
-    return pipeline;
-  }
-
-  private getPresentPipeline(format: GPUTextureFormat, sampleCount: 1 | 4, withDepth: boolean, reverseZ: boolean): GPURenderPipeline {
-    const depthFormat = withDepth ? this.engine.getDepthFormat(reverseZ) : 'none';
-    const key = `present:${format}:${sampleCount}:${depthFormat}:${reverseZ ? 1 : 0}`;
-    const cached = this.pipelines.get(key);
-    if (cached) return cached;
-    const pipeline = requireEngineDevice(this.engine).createRenderPipeline({
-      label: `Animation2D.presentPipeline:${key}`,
-      layout: this.pipelineLayout,
-      vertex: { module: this.shader, entryPoint: 'vs_effect' },
-      fragment: { module: this.shader, entryPoint: 'fs_present', targets: [{ format, blend: {
-        color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
-        alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
-      } }] },
-      primitive: { topology: 'triangle-list', cullMode: 'none' },
-      ...(withDepth ? { depthStencil: {
-        format: depthFormat as GPUTextureFormat, depthWriteEnabled: false, depthCompare: 'always' as const,
-      } } : {}),
-      multisample: { count: sampleCount },
-    });
-    this.pipelines.set(key, pipeline);
-    return pipeline;
-  }
-
-  private draw(
-    pass: GPURenderPassEncoder,
-    entity: Entity,
-    visual: AnimationVisual2D,
-    context: RenderCommandContext,
-    compositeBindGroup: GPUBindGroup,
-    outputMask: boolean,
-  ): void {
-    const device = requireEngineDevice(this.engine);
-    const object = this.getEntityGpu(entity);
-    object.data.set(this.getWorldMatrix2D(entity, context), 0);
-    object.data.set(visual.color, 16);
-    object.data[20] = visual.compositeLayers.length;
-    object.data[21] = outputMask ? 1 : 0;
-    object.data[22] = Math.min(MAX_EFFECTS, visual.effects.length);
-    object.data[23] = 0;
-    object.data.set(visual.uvRect, 24);
-    object.data.fill(0, COMPOSITE_PARAMS_OFFSET);
-    for (let index = 0; index < visual.compositeLayers.length; index++) {
-      const layer = visual.compositeLayers[index]!;
-      const offset = COMPOSITE_PARAMS_OFFSET + index * 4;
-      object.data[offset] = compositeModeCode(layer.mode);
-      object.data[offset + 1] = compositeOperationCode(layer.operation ?? 'add');
-      object.data[offset + 2] = layer.feather?.[0] ?? 0;
-      object.data[offset + 3] = layer.feather?.[1] ?? 0;
-      object.data[COMPOSITE_EXPANSION_OFFSET + index] = layer.expansion ?? 0;
-    }
-    const gradient = visual.gradient;
-    if (gradient) {
-      const stopCount = Math.min(8, gradient.stops.length / 5);
-      object.data[GRADIENT_PARAMS_OFFSET] = gradient.kind === 'linear' ? 1 : 2;
-      object.data[GRADIENT_PARAMS_OFFSET + 1] = stopCount;
-      object.data[GRADIENT_PARAMS_OFFSET + 2] = gradient.opacity;
-      object.data.set(gradient.start, GRADIENT_GEOMETRY_OFFSET);
-      object.data.set(gradient.end, GRADIENT_GEOMETRY_OFFSET + 2);
-      for (let index = 0; index < stopCount; index++) {
-        const source = index * 5;
-        const colorOffset = GRADIENT_COLORS_OFFSET + index * 4;
-        object.data[colorOffset] = gradient.stops[source + 1] ?? 1;
-        object.data[colorOffset + 1] = gradient.stops[source + 2] ?? 1;
-        object.data[colorOffset + 2] = gradient.stops[source + 3] ?? 1;
-        object.data[colorOffset + 3] = gradient.stops[source + 4] ?? 1;
-        object.data[GRADIENT_OFFSETS_OFFSET + index] = gradient.stops[source] ?? 0;
-      }
-    }
-    for (let index = 0; index < Math.min(MAX_EFFECTS, visual.effects.length); index++) {
-      const effect = visual.effects[index]!;
-      object.data[EFFECT_KINDS_OFFSET + index] = effectKindCode(effect.kind);
-      object.data.set(effect.values.subarray(0, EFFECT_FLOATS), EFFECT_DATA_OFFSET + index * EFFECT_FLOATS);
-    }
-    device.queue.writeBuffer(object.buffer, 0, object.data as ArrayBufferView<ArrayBuffer>);
-    const geometry = this.getGeometryGpu(visual);
-    pass.setBindGroup(1, object.bindGroup);
-    pass.setBindGroup(2, this.getVisualTextureBindGroup(entity, visual, object, context));
-    pass.setBindGroup(3, compositeBindGroup);
-    pass.setVertexBuffer(0, geometry.vertexBuffer);
-    if (geometry.indexBuffer && geometry.indexCount > 0) {
-      pass.setIndexBuffer(geometry.indexBuffer, geometry.indexFormat);
-      pass.drawIndexed(geometry.indexCount);
-    } else {
-      pass.draw(geometry.vertexCount);
-    }
-  }
-
-  private renderEffectStack(
-    item: AnimationRenderItem,
-    context: RenderCommandContext,
-    compositeBindGroup: GPUBindGroup,
-    frame: number,
-  ): { texture: GPUTexture; width: number; height: number } {
-    // One reusable ping-pong pair per view. Command ordering presents each result
-    // before the next visual overwrites it, so memory is O(view), not O(entities).
-    const key = context.view?.key ?? 'default';
-    const target = this.getEffectTarget(key, context, frame);
-    const sourcePass = context.encoder.beginRenderPass({
-      label: `Animation2D.effectSource:${item.entity.id}`,
-      colorAttachments: [{
-        view: target.views[0], clearValue: { r: 0, g: 0, b: 0, a: 0 }, loadOp: 'clear', storeOp: 'store',
-      }],
-    });
-    applyViewport(sourcePass, context);
-    sourcePass.setPipeline(this.getPipeline('rgba8unorm', 1, false, false));
-    sourcePass.setBindGroup(0, this.cameraGpu.bindGroup);
-    this.draw(sourcePass, item.entity, item.visual, context, compositeBindGroup, false);
-    sourcePass.end();
-
-    const object = this.getEntityGpu(item.entity);
-    let sourceIndex: 0 | 1 = 0;
-    for (let index = 0; index < Math.min(MAX_EFFECTS, item.visual.effects.length); index++) {
-      const outputIndex: 0 | 1 = sourceIndex === 0 ? 1 : 0;
-      const pass = context.encoder.beginRenderPass({
-        label: `Animation2D.effect:${item.entity.id}:${index}`,
-        colorAttachments: [{
-          view: target.views[outputIndex], clearValue: { r: 0, g: 0, b: 0, a: 0 }, loadOp: 'clear', storeOp: 'store',
-        }],
-      });
-      applyViewport(pass, context);
-      pass.setPipeline(this.getEffectPipeline());
-      pass.setBindGroup(0, this.cameraGpu.bindGroup);
-      pass.setBindGroup(1, object.bindGroup);
-      pass.setBindGroup(2, this.getTextureBindGroup(target.textures[sourceIndex]));
-      pass.setBindGroup(3, this.emptyCompositeBindGroup);
-      pass.draw(3, 1, 0, index);
-      pass.end();
-      sourceIndex = outputIndex;
-    }
-    return { texture: target.textures[sourceIndex], width: target.width, height: target.height };
-  }
-
-  private drawEffectResult(pass: GPURenderPassEncoder, entity: Entity, texture: GPUTexture): void {
-    pass.setBindGroup(1, this.getEntityGpu(entity).bindGroup);
-    pass.setBindGroup(2, this.getTextureBindGroup(texture));
-    pass.setBindGroup(3, this.emptyCompositeBindGroup);
-    pass.draw(3);
-  }
-
-  private getEntityGpu(entity: Entity): EntityGpu {
-    return this.getOrCreateEntityGpu(this.entityGpu, entity, () => {
-      const device = requireEngineDevice(this.engine);
-      const buffer = device.createBuffer({ size: OBJECT_BYTES, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
-      getExtensionGPUResourceTracker(this.engine)?.trackBuffer(buffer, 'Animation2D.objectBuffer', OBJECT_BYTES);
-      return {
-        buffer,
-        bindGroup: device.createBindGroup({ layout: this.objectLayout, entries: [{ binding: 0, resource: { buffer } }] }),
-        data: new Float32Array(OBJECT_FLOATS),
-        externalTexture: null,
-        externalSource: null,
-        externalVersion: -1,
-        externalWidth: 0,
-        externalHeight: 0,
-        externalBindGroup: null,
-      };
-    });
-  }
-
-  private getVisualTextureBindGroup(
-    entity: Entity,
-    visual: AnimationVisual2D,
-    object: EntityGpu,
-    context: RenderCommandContext,
-  ): GPUBindGroup {
-    const texture = visual.resolveTexture();
-    if (texture) return this.getTextureBindGroup(texture);
-    const material = visual.textMaterial;
-    const source = material?.texture;
-    if (material && isExternalImageSource(source)) {
-      const size = externalImageSize(source);
-      if (!object.externalTexture || object.externalWidth !== size.width || object.externalHeight !== size.height) {
-        const retiredTexture = object.externalTexture;
-        if (retiredTexture) {
-          const retire = () => {
-            getExtensionGPUResourceTracker(this.engine)?.untrackTexture(retiredTexture);
-            retiredTexture.destroy();
-          };
-          if (context.afterSubmit) {
-            context.afterSubmit(queue => {
-              void queue.onSubmittedWorkDone()
-                .then(retire)
-                .catch(retire);
-            });
-          } else {
-            retire();
-          }
-        }
-        object.externalTexture = requireEngineDevice(this.engine).createTexture({
-          label: `Animation2D.text:${entity.id}`,
-          size: [size.width, size.height],
-          format: 'rgba8unorm',
-          // WebGPU copyExternalImageToTexture requires RENDER_ATTACHMENT in addition
-          // to COPY_DST for browser-backed image sources.
-          usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT,
-        });
-        getExtensionGPUResourceTracker(this.engine)?.trackTexture(object.externalTexture, 'Animation2D.textTexture', size.width * size.height * 4);
-        object.externalBindGroup = this.createTextureBindGroup(object.externalTexture);
-        object.externalWidth = size.width;
-        object.externalHeight = size.height;
-        object.externalVersion = -1;
-      }
-      if (object.externalSource !== source || object.externalVersion !== material.textureVersion) {
-        requireEngineDevice(this.engine).queue.copyExternalImageToTexture({ source }, { texture: object.externalTexture! }, [size.width, size.height]);
-        object.externalSource = source;
-        object.externalVersion = material.textureVersion;
-      }
-      return object.externalBindGroup!;
-    }
-    return visual.requiresTexture ? this.transparentBindGroup : this.whiteBindGroup;
-  }
-
-  private getGeometryGpu(visual: AnimationVisual2D): GeometryGpu {
-    const geometry = visual.geometry;
-    let gpu = this.geometryGpu.get(geometry.id);
-    if (gpu && gpu.version === geometry.version) return gpu;
-    if (gpu) this.destroyGeometryGpu(gpu);
-    const vertices = buildVertices(geometry.positions);
-    const device = requireEngineDevice(this.engine);
-    const vertexBuffer = device.createBuffer({ size: vertices.byteLength, usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST });
-    device.queue.writeBuffer(vertexBuffer, 0, vertices as ArrayBufferView<ArrayBuffer>);
-    let indexBuffer: GPUBuffer | null = null;
-    if (geometry.indices?.length) {
-      const allocationBytes = alignUp4(geometry.indices.byteLength);
-      indexBuffer = device.createBuffer({ size: allocationBytes, usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST });
-      writeBufferAligned(device.queue, indexBuffer, geometry.indices);
-    }
-    const tracker = getExtensionGPUResourceTracker(this.engine);
-    tracker?.trackBuffer(vertexBuffer, 'Animation2D.vertexBuffer', vertices.byteLength);
-    if (indexBuffer && geometry.indices) tracker?.trackBuffer(indexBuffer, 'Animation2D.indexBuffer', alignUp4(geometry.indices.byteLength));
-    gpu = {
-      vertexBuffer,
-      indexBuffer,
-      indexCount: geometry.indices?.length ?? 0,
-      vertexCount: geometry.vertexCount,
-      indexFormat: geometry.indices instanceof Uint32Array ? 'uint32' : 'uint16',
-      version: geometry.version,
-    };
-    this.geometryGpu.set(geometry.id, gpu);
-    return gpu;
-  }
-
-  private getTextureBindGroup(texture: GPUTexture): GPUBindGroup {
-    let bindGroup = this.textureBindGroups.get(texture);
-    if (!bindGroup) {
-      bindGroup = this.createTextureBindGroup(texture);
-      this.textureBindGroups.set(texture, bindGroup);
-    }
-    return bindGroup;
-  }
-
-  private createTextureBindGroup(texture: GPUTexture): GPUBindGroup {
-    return requireEngineDevice(this.engine).createBindGroup({ layout: this.textureLayout, entries: [
-      { binding: 0, resource: texture.createView() },
-      { binding: 1, resource: this.sampler },
-    ] });
-  }
-
-  private resolveCompositeBindGroup(
-    visual: AnimationVisual2D,
-    targets: ReadonlyMap<string, MaskTarget>,
-    viewKey: string,
-  ): GPUBindGroup | null {
-    if (visual.compositeLayers.length === 0) return this.emptyCompositeBindGroup;
-    const resolved: MaskTarget[] = [];
-    for (const key of visual.compositeKeys) {
-      const target = targets.get(key);
-      if (!target) return null;
-      resolved.push(target);
-    }
-    const key = `${viewKey}:${visual.compositeKeys.join('|')}`;
-    let bindGroup = this.compositeBindGroups.get(key);
-    if (!bindGroup) {
-      bindGroup = this.createCompositeBindGroup(resolved.map(target => target.texture));
-      this.compositeBindGroups.set(key, bindGroup);
-    }
-    return bindGroup;
-  }
-
-  private createCompositeBindGroup(textures: readonly GPUTexture[]): GPUBindGroup {
-    return requireEngineDevice(this.engine).createBindGroup({
-      layout: this.compositeLayout,
-      entries: [
-        ...Array.from({ length: MAX_COMPOSITE_LAYERS }, (_, binding) => ({
-          binding,
-          resource: (textures[binding] ?? this.whiteTexture).createView(),
-        })),
-        { binding: MAX_COMPOSITE_LAYERS, resource: this.sampler },
-      ],
-    });
-  }
-
-  private getMaskTarget(key: string, context: RenderCommandContext, frame: number): MaskTarget {
-    const width = context.view?.target.width ?? this.engine.width;
-    const height = context.view?.target.height ?? this.engine.height;
-    let target = this.maskTargets.get(key);
-    if (target && target.width === width && target.height === height) { target.lastFrame = frame; return target; }
-    if (target) {
-      this.maskTargets.delete(key);
-      this.compositeBindGroups.clear();
-      const retired = target;
-      context.afterSubmit?.(queue => void queue.onSubmittedWorkDone().then(() => this.destroyMaskTarget(retired)).catch(() => this.destroyMaskTarget(retired)));
-      if (!context.afterSubmit) this.destroyMaskTarget(retired);
-    }
-    const texture = requireEngineDevice(this.engine).createTexture({
-      label: `Animation2D.mask:${key}`,
-      size: [width, height],
-      format: 'rgba8unorm',
-      usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
-    });
-    getExtensionGPUResourceTracker(this.engine)?.trackTexture(texture, 'Animation2D.maskTexture', estimateTextureBytes([width, height, 1], 'rgba8unorm'));
-    target = { texture, view: texture.createView(), width, height, lastFrame: frame };
-    this.maskTargets.set(key, target);
-    return target;
-  }
-
-  private getEffectTarget(key: string, context: RenderCommandContext, frame: number): EffectTarget {
-    const width = context.view?.target.width ?? this.engine.width;
-    const height = context.view?.target.height ?? this.engine.height;
-    let target = this.effectTargets.get(key);
-    if (target && target.width === width && target.height === height) { target.lastFrame = frame; return target; }
-    if (target) {
-      this.effectTargets.delete(key);
-      const retired = target;
-      context.afterSubmit?.(queue => void queue.onSubmittedWorkDone().then(() => this.destroyEffectTarget(retired)).catch(() => this.destroyEffectTarget(retired)));
-      if (!context.afterSubmit) this.destroyEffectTarget(retired);
-    }
-    const device = requireEngineDevice(this.engine);
-    const makeTexture = (index: number): GPUTexture => device.createTexture({
-      label: `Animation2D.effect:${key}:${index}`,
-      size: [width, height],
-      format: 'rgba8unorm',
-      usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
-    });
-    const textures = [makeTexture(0), makeTexture(1)] as const;
-    const bytes = estimateTextureBytes([width, height, 1], 'rgba8unorm');
-    const tracker = getExtensionGPUResourceTracker(this.engine);
-    tracker?.trackTexture(textures[0], 'Animation2D.effectTexture', bytes);
-    tracker?.trackTexture(textures[1], 'Animation2D.effectTexture', bytes);
-    target = { textures, views: [textures[0].createView(), textures[1].createView()], width, height, lastFrame: frame };
-    this.effectTargets.set(key, target);
-    return target;
-  }
-
-  private sweepMaskTargets(frame: number, context: RenderCommandContext): void {
-    let swept = false;
-    for (const [key, target] of this.maskTargets) {
-      if (target.lastFrame >= frame - 1) continue;
-      this.maskTargets.delete(key);
-      swept = true;
-      context.afterSubmit?.(queue => void queue.onSubmittedWorkDone().then(() => this.destroyMaskTarget(target)).catch(() => this.destroyMaskTarget(target)));
-      if (!context.afterSubmit) this.destroyMaskTarget(target);
-    }
-    if (swept) this.compositeBindGroups.clear();
-  }
-
-  private sweepEffectTargets(frame: number, context: RenderCommandContext): void {
-    for (const [key, target] of this.effectTargets) {
-      if (target.lastFrame >= frame - 1) continue;
-      this.effectTargets.delete(key);
-      context.afterSubmit?.(queue => void queue.onSubmittedWorkDone().then(() => this.destroyEffectTarget(target)).catch(() => this.destroyEffectTarget(target)));
-      if (!context.afterSubmit) this.destroyEffectTarget(target);
-    }
-  }
-
-  private sweepGeometryGpu(): void {
-    this.liveGeometryIds.clear();
-    for (const item of this.items) this.liveGeometryIds.add(item.visual.geometry.id);
-    for (const [id, gpu] of this.geometryGpu) if (!this.liveGeometryIds.has(id)) { this.destroyGeometryGpu(gpu); this.geometryGpu.delete(id); }
-  }
-
-  private destroyEntityGpu(gpu: EntityGpu): void {
-    getExtensionGPUResourceTracker(this.engine)?.untrackBuffer(gpu.buffer);
-    gpu.buffer.destroy();
-    if (gpu.externalTexture) getExtensionGPUResourceTracker(this.engine)?.untrackTexture(gpu.externalTexture);
-    gpu.externalTexture?.destroy();
-  }
-
-  private destroyGeometryGpu(gpu: GeometryGpu): void {
-    const tracker = getExtensionGPUResourceTracker(this.engine);
-    tracker?.untrackBuffer(gpu.vertexBuffer);
-    gpu.vertexBuffer.destroy();
-    if (gpu.indexBuffer) tracker?.untrackBuffer(gpu.indexBuffer);
-    gpu.indexBuffer?.destroy();
-  }
-
-  private destroyMaskTarget(target: MaskTarget): void {
-    getExtensionGPUResourceTracker(this.engine)?.untrackTexture(target.texture);
-    target.texture.destroy();
-  }
-
-  private destroyEffectTarget(target: EffectTarget): void {
-    const tracker = getExtensionGPUResourceTracker(this.engine);
-    for (const texture of target.textures) {
-      tracker?.untrackTexture(texture);
-      texture.destroy();
-    }
-  }
-}
-
-function writeBufferAligned(
-  queue: GPUQueue,
-  buffer: GPUBuffer,
-  source: Uint16Array | Uint32Array,
-): void {
-  if (source.byteLength % 4 === 0) {
-    queue.writeBuffer(buffer, 0, source as ArrayBufferView<ArrayBuffer>);
-    return;
-  }
-  const padded = new Uint8Array(alignUp4(source.byteLength));
-  padded.set(new Uint8Array(source.buffer, source.byteOffset, source.byteLength));
-  queue.writeBuffer(buffer, 0, padded);
-}
-
-function isExternalImageSource(value: unknown): value is ImageBitmap | HTMLCanvasElement | HTMLImageElement {
-  if (!value || typeof value !== 'object') return false;
-  return (typeof ImageBitmap !== 'undefined' && value instanceof ImageBitmap)
-    || (typeof HTMLCanvasElement !== 'undefined' && value instanceof HTMLCanvasElement)
-    || (typeof HTMLImageElement !== 'undefined' && value instanceof HTMLImageElement);
-}
-
-function externalImageSize(source: ImageBitmap | HTMLCanvasElement | HTMLImageElement): { width: number; height: number } {
-  const isImage = typeof HTMLImageElement !== 'undefined' && source instanceof HTMLImageElement;
-  return {
-    width: Math.max(1, isImage ? source.naturalWidth || source.width : source.width),
-    height: Math.max(1, isImage ? source.naturalHeight || source.height : source.height),
-  };
-}
-
-function compareItems(a: AnimationRenderItem, b: AnimationRenderItem): number {
-  return a.visual.instanceId - b.visual.instanceId || a.visual.order - b.visual.order || a.entity.id - b.entity.id;
-}
-
-function orderSourceGroups(groups: ReadonlyMap<string, readonly AnimationRenderItem[]>): string[] {
-  const ordered: string[] = [];
-  const states = new Map<string, 1 | 2>();
-  const visit = (key: string): void => {
-    if (states.get(key) === 2) return;
-    if (states.get(key) === 1) return;
-    states.set(key, 1);
-    for (const item of groups.get(key) ?? []) {
-      for (const dependency of item.visual.compositeKeys) if (groups.has(dependency)) visit(dependency);
-    }
-    states.set(key, 2);
-    ordered.push(key);
-  };
-  for (const key of groups.keys()) visit(key);
-  return ordered;
-}
-
-function compositeModeCode(mode: AnimationCompositeLayer['mode']): number {
-  return mode === 'alpha' ? 0 : mode === 'alpha-inverted' ? 1 : mode === 'luma' ? 2 : 3;
-}
-
-function compositeOperationCode(operation: NonNullable<AnimationCompositeLayer['operation']>): number {
-  return operation === 'add' ? 0 : operation === 'subtract' ? 1 : operation === 'intersect' ? 2 : 3;
-}
-
-function effectKindCode(kind: AnimationVisual2D['effects'][number]['kind']): number {
-  return kind === 'tint' ? 1 : kind === 'fill' ? 2 : kind === 'opacity' ? 3
-    : kind === 'color-matrix' ? 4 : kind === 'blur' ? 5 : 6;
-}
-
-function visualNodeKey(visual: AnimationVisual2D): string { return visual.nodeKey; }
-
-function buildVertices(positions: Float32Array): Float32Array {
-  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
-  for (let i = 0; i < positions.length; i += 2) {
-    const x = positions[i]!, y = positions[i + 1]!;
-    minX = Math.min(minX, x); maxX = Math.max(maxX, x);
-    minY = Math.min(minY, y); maxY = Math.max(maxY, y);
-  }
-  const width = Math.max(maxX - minX, 1e-6), height = Math.max(maxY - minY, 1e-6);
-  const out = new Float32Array(positions.length * 2);
-  for (let source = 0, target = 0; source < positions.length; source += 2) {
-    const x = positions[source]!, y = positions[source + 1]!;
-    out[target++] = x; out[target++] = y;
-    out[target++] = (x - minX) / width; out[target++] = 1 - (y - minY) / height;
-  }
-  return out;
-}
-
-function applyViewport(pass: GPURenderPassEncoder, context: RenderCommandContext): void {
-  const viewport = context.view?.viewport;
-  if (viewport) pass.setViewport(viewport.x, viewport.y, viewport.width, viewport.height, viewport.minDepth ?? 0, viewport.maxDepth ?? 1);
-  const scissor = context.view?.scissor;
-  if (scissor) pass.setScissorRect(scissor.x, scissor.y, scissor.width, scissor.height);
-}
-
-function positiveInteger(value: number, label: string): number {
-  if (!Number.isSafeInteger(value) || value < 1) throw new RangeError(`${label} must be a positive safe integer.`);
-  return value;
-}