@godot-scene-web/html 0.1.0

package/dist/extents-R8RIim2S.d.ts

@@ -0,0 +1,1223 @@
+import { GodotNode, GodotResource, GodotResourceRefValue, GodotVariant } from "@godot-scene-web/core";
+import { InstanceBuffer, ParticleRenderConfig, sampleParticleGradient } from "@godot-scene-web/effects/particles";
+import { uploadWebglTexture } from "@godot-scene-web/canvas-effects/webgl";
+import { GodotBlendMode } from "@godot-scene-web/effects/shaders";
+import { GodotSceneTreeDiagnostic } from "@godot-scene-web/layout";
+import { GodotAnchorMap } from "@godot-scene-web/layout/anchors";
+import { GodotResourceLoadStatus, GodotResourceStatus } from "@godot-scene-web/scene-graph";
+
+//#region src/content-scale.d.ts
+interface GodotContentScaleSize {
+  width: number;
+  height: number;
+}
+type GodotContentScaleAspect = "ignore" | "keep" | "keep_width" | "keep_height" | "expand";
+type GodotContentScaleTechnique = "container" | "transform";
+interface GodotContentScale {
+  /** Godot `content_scale_aspect`. Only `"keep"` is implemented for now. */
+  aspect: GodotContentScaleAspect;
+  /**
+   * How the uniform scale is realized in the DOM:
+   * - `"container"` (default): CSS-only, every length in the stage subtree is
+   *   expressed in container-query units. No JavaScript; identical in Vue and the
+   *   static HTML document.
+   * - `"transform"`: the stage keeps its px layout and is scaled with
+   *   `transform: scale(var(--godot-scale))`; the factor is set by JS on resize.
+   */
+  technique?: GodotContentScaleTechnique;
+  /** Base/reference resolution (Godot `content_scale_size`). Defaults to the model viewport. */
+  baseSize?: GodotContentScaleSize;
+  /** Letterbox/pillarbox bar color painted by the frame around the centered stage. */
+  background?: string;
+}
+interface ResolvedContentScale {
+  aspect: GodotContentScaleAspect;
+  technique: GodotContentScaleTechnique;
+  base: GodotContentScaleSize;
+  background?: string;
+}
+declare function resolveContentScale(contentScale: GodotContentScale | undefined, viewport: GodotContentScaleSize): ResolvedContentScale | null;
+declare function rewritePxLengths(text: string, base: GodotContentScaleSize): string;
+declare function scaleStyleRecord(style: Record<string, string>, base: GodotContentScaleSize): void;
+declare function contentScaleStageStyle(resolved: ResolvedContentScale): Record<string, string>;
+declare function observeContentScale(frame: HTMLElement, base: GodotContentScaleSize): () => void;
+declare function contentScaleScript(base: GodotContentScaleSize): string;
+//#endregion
+//#region src/text-scale.d.ts
+declare const TEXT_SCALE_VAR = "--godot-text-scale";
+interface GodotTextScale {
+  exemptAutoFit?: boolean;
+}
+type GodotTextScaleOption = boolean | GodotTextScale;
+interface ResolvedTextScale {
+  exemptAutoFit: boolean;
+}
+declare function resolveTextScale(option: GodotTextScaleOption | undefined): ResolvedTextScale | null;
+declare function textScaleLength(px: number, enabled: boolean): string;
+declare function setGodotTextScale(element: HTMLElement, value: number): void;
+//#endregion
+//#region src/types.d.ts
+/**
+ * A `<filter>` referenced by a self-layer's `filter: url(#id)` (an external
+ * texture's color-matrix tint, or a consumer-supplied shader-fallback effect).
+ * `markup` is the filter's inner SVG (e.g. a `feColorMatrix`, or a
+ * luminance→band→flood chain). Emitted once per render into a hidden
+ * `<svg><defs>` by every renderer.
+ */
+interface GodotHtmlTintFilter {
+  id: string;
+  markup: string;
+}
+interface GodotHtmlModel {
+  viewport: {
+    width: number;
+    height: number;
+  };
+  nodes: GodotHtmlNode[];
+  fontFaces: GodotHtmlFontFace[];
+  tintFilters: GodotHtmlTintFilter[];
+  diagnostics: GodotSceneTreeDiagnostic[];
+  resourceStatuses: GodotResourceStatus[];
+  css: string;
+  contentScale: ResolvedContentScale | null;
+}
+type GodotHtmlPositioning = "root" | "absolute" | "container-managed";
+type GodotHtmlContainerLayout = "box" | "flow" | "grid" | "center" | "margin" | "panel" | "scroll" | "aspect-ratio";
+interface GodotHtmlNode {
+  kind?: "hidden-placeholder";
+  path: string;
+  name: string;
+  type: string;
+  parentPath: string | null;
+  children: string[];
+  positioning: GodotHtmlPositioning;
+  containerLayout: GodotHtmlContainerLayout | null;
+  attributes: Record<string, string>;
+  className: string;
+  style: Record<string, string>;
+  selfAttributes: Record<string, string>;
+  selfStyle: Record<string, string>;
+  text: string | null;
+  html: string | null;
+}
+interface GodotResolvedResource {
+  status?: GodotResourceLoadStatus;
+  type?: string;
+  path?: string;
+  url?: string;
+  document?: GodotResource;
+  atlas?: GodotResolvedResource;
+  shader?: GodotResolvedResource;
+  region?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  margin?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  atlasCrop?: {
+    region: {
+      x: number;
+      y: number;
+      width: number;
+      height: number;
+    };
+    margin: {
+      x: number;
+      y: number;
+      width: number;
+      height: number;
+    };
+  };
+  size?: {
+    width: number;
+    height: number;
+  };
+  fontFamily?: string;
+  fontUrl?: string;
+  fontStyle?: "normal" | "italic";
+  fontWeight?: number | string;
+  glyphSpacing?: number;
+  fontMsdf?: boolean;
+  message?: string;
+}
+interface GodotHtmlFontFace {
+  fontFamily: string;
+  url: string;
+  style: "normal" | "italic";
+  weight: string;
+}
+interface GodotTextAutoFitNominalMetrics {
+  contentWidthPx: number;
+  contentHeightPx: number;
+  lines?: {
+    widthPx?: number;
+    heightPx?: number;
+  }[];
+  metricSource?: string;
+}
+interface GodotTextAutoFitDirective {
+  minFontSizePx: number;
+  maxFontSizePx: number;
+  nominalFontSizePx?: number;
+  /**
+   * Paragraph geometry the host engine (Godot) measured at `nominalFontSizePx`.
+   * When present, auto-fit scales these by `candidate / nominalFontSizePx` to pick
+   * a size that matches the engine, instead of measuring the live DOM (which drifts
+   * before web fonts resolve). Absent => fall back to DOM measurement.
+   */
+  nominalMetrics?: GodotTextAutoFitNominalMetrics;
+  fitWidth: boolean;
+  fitHeight: boolean;
+  wrapMode?: string;
+  textOverrunBehavior?: string;
+}
+interface GodotShaderLoadingFallback {
+  background: string;
+  clipPath?: string;
+  borderRadius?: string;
+}
+type GodotBbcodeTagDescriptor = {
+  kind: "color";
+  value: string;
+} | {
+  kind: "style";
+  css: Record<string, string>;
+} | {
+  kind: "effect";
+  perChar?: boolean;
+  perWord?: boolean;
+  className?: string;
+};
+interface GodotHtmlRenderOptions {
+  classPrefix?: string;
+  textAutoFitByPath?: Record<string, GodotTextAutoFitDirective>;
+  resolveResource?: (ref: GodotResourceRefValue, node: GodotNode) => unknown;
+  resolveResourcePath?: (path: string, node: GodotNode) => unknown;
+  resolveTheme?: (node: GodotNode, name: string) => GodotVariant | undefined;
+  bbcodeTags?: Record<string, GodotBbcodeTagDescriptor>;
+  contentScale?: GodotContentScale;
+  textScale?: GodotTextScaleOption;
+  tintFilterIdPrefix?: string;
+  anchorsByPath?: GodotAnchorMap;
+  enableWebglShaders?: boolean;
+  shaderLoadingFallbacksByPath?: Record<string, GodotShaderLoadingFallback>;
+  webglShaderNodesByPath?: Record<string, boolean>;
+  webglShaderIds?: string[];
+  hiddenRawShaderFallbacksByPath?: Record<string, boolean>;
+  hiddenRawShaderFallbackShaderIds?: string[];
+  hsvAdjustShaderIds?: string[];
+  shaderFallbackFiltersByPath?: Record<string, string>;
+  enableParticles?: boolean;
+  particleNodesByPath?: Record<string, boolean>;
+  particleIds?: string[];
+  godotRenderer?: "forward_plus" | "mobile" | "gl_compatibility";
+}
+/**
+ * What the effect runtimes know about the frame they just presented/handled, handed to
+ * `GodotHtmlRenderOptions.onBindingRendered` alongside the node and its canvas.
+ *
+ * ADDITIVE, and it stays that way because of how TypeScript reads a callback: a
+ * consumer that declares `(node, canvas) => …` still satisfies the option, so the
+ * two-argument callers that existed before this parameter are untouched.
+ *
+ * WHY THESE THREE. A consumer that COMPOSITES the canvas itself — rather than
+ * leaving it in the DOM where the runtime placed it — has to reproduce two things
+ * the runtime otherwise expresses through CSS, and refuse a third:
+ *
+ * - `blend` is the shader's Godot `render_mode`. The runtime writes it onto the
+ *   node as a `mix-blend-mode` (see `blendToMixBlendMode`), which only means
+ *   anything while the canvas is painted by the page's compositor; a consumer
+ *   drawing the same pixels into its own surface needs the mode itself.
+ * - `usesScreenTexture` says the frame was shaded against a capture of what the
+ *   page had already painted BEHIND the node. That capture is a DOM composite
+ *   (see `enableScreenTextureCapture`), so it describes the page's stacking — not
+ *   a consumer's own surface — and a consumer whose scene is somewhere else
+ *   should treat the frame as content it cannot reproduce faithfully.
+ * - `usesScreenUv` is the weaker twin: the shader read SCREEN_UV, so its output
+ *   depends on where the node sits in the viewport, and moving the pixels
+ *   elsewhere moves what they mean.
+ *
+ * The PARTICLE runtime reports a constant (`"mix"`, neither screen flag): a
+ * particle system's own additive mode is resolved INSIDE its canvas, whose
+ * finished pixels are premultiplied and composite source-over like any other.
+ *
+ * …AND A FOURTH, `staticKey`, which is about identity rather than about how to
+ * composite one frame: see its own note below.
+ */
+interface GodotEffectRenderInfo {
+  /** The shader sampled SCREEN_TEXTURE. Always false for particles. */
+  usesScreenTexture: boolean;
+  /** The shader read SCREEN_UV. Always false for particles. */
+  usesScreenUv: boolean;
+  /** The shader's `render_mode` blend; always `"mix"` for particles. */
+  blend: GodotBlendMode;
+  /**
+   * The NAME OF THE FRAME this canvas now holds — the runtime's own static-frame
+   * key — or null when the frame is not content-addressed at all (live/animating
+   * mode, a screen-space shader, textures still decoding, a particle state the
+   * live loop has stepped, a blank that ends a burst).
+   *
+   * WHAT IT PROMISES: the frame is a PURE FUNCTION of this string. It is the same
+   * key the static-frame cache stores the bitmap under and the same one the image
+   * swap dedupes by, and it is what licenses those two to hand ONE binding's
+   * pixels to another. So two canvases reporting one key hold the same picture,
+   * and a host that uploads these canvases into its own renderer can upload ONE
+   * texture and point every twin at it — which on a hand of identical card glows
+   * is one upload instead of seven, of a surface that can be megabytes.
+   *
+   * A null key means "assume nothing": that frame may be unique to this binding,
+   * and a host must key it privately (its node id) as it always did.
+   */
+  staticKey: string | null;
+}
+//#endregion
+//#region src/diagnostics.d.ts
+type UnsupportedRenderKind = "shader" | "particle";
+interface UnsupportedRenderInfo {
+  kind: UnsupportedRenderKind;
+  /** Shader identity (uid/path) or particle node path — enough to locate the offending node. */
+  id: string;
+  /** Short reason, e.g. "unsupported shader construct", "shader failed to compile", "shader source
+   *  unresolved", "malformed particle spec". */
+  reason: string;
+  /** The underlying error, when the failure threw. */
+  error?: unknown;
+}
+type UnsupportedRenderReporter = (info: UnsupportedRenderInfo) => void;
+declare function reportUnsupportedRender(info: UnsupportedRenderInfo, onUnsupported?: UnsupportedRenderReporter): void;
+//#endregion
+//#region src/effects-loop-pacing.d.ts
+/** How a capped effect loop arms its next tick (see `GodotHtmlRenderOptions.effectsLoopPacing`). */
+type EffectsLoopPacing = "timer" | "raf";
+/** Slop (seconds) around a cap boundary, `"timer"` pacing only (see the module doc). */
+declare const PARK_SLOP_S = 0.004;
+/** The wakeup scheduler of one capped effect loop (see `createEffectsLoopPacer`). */
+interface EffectsLoopPacer {
+  /** Whether a boundary `remaining` seconds away counts as reached now (absorbs the park slop). */
+  isDue(remaining: number): boolean;
+  /** Whether a wakeup (rAF or park timer) is already in flight. */
+  isArmed(): boolean;
+  /** Arm the next tick `remaining` seconds from now. No-op while already armed. */
+  arm(remaining: number): void;
+  /** Drop a pending park (NOT a pending rAF) — for a cap change that invalidates its deadline. */
+  cancelPark(): void;
+  /** Drop every pending wakeup. */
+  cancel(): void;
+}
+/**
+ * Create the wakeup scheduler for one capped effect loop. `tick` is the loop body; it runs
+ * inside a rAF callback in both pacing modes.
+ */
+declare function createEffectsLoopPacer(tick: () => void, pacing: EffectsLoopPacing | undefined): EffectsLoopPacer;
+//#endregion
+//#region src/surface-image-swap.d.ts
+/** The DOM attribute stamped on the `<img>` that stands in for a frozen surface's canvas. */
+declare const STATIC_SURFACE_IMAGE_ATTR = "data-godot-shader-image";
+/** Default `content-key` gate: how many consecutive unchanged observations of a surface's content key
+ *  are required before it is swapped. Small on purpose — the revert is the real safety net, and the
+ *  clock ticks many times a second — so 3 costs a fraction of a second of latency and excludes a
+ *  surface that is merely between two states. */
+declare const STABLE_OBSERVATIONS_BEFORE_SWAP = 3;
+/** Default `quiet-window` gate: a surface's own draws must hold still this long before it freezes. */
+declare const DEFAULT_QUIET_WINDOW_MS = 1000;
+/** Default watchdog cadence, for the gates that need one (see the module doc). */
+declare const DEFAULT_SURFACE_WATCHDOG_MS = 3000;
+/** Default encode pacing: surfaces per batch (see the module doc). */
+declare const DEFAULT_ENCODE_SLICE = 4;
+/** Default encode pacing: gap between batches, ms. */
+declare const DEFAULT_ENCODE_INTERVAL_MS = 120;
+/** Default cap on one unbroken run of encode deferrals, for EITHER reason (see the module doc). Long
+ *  enough that an ordinary burst of host activity is ridden out whole, short enough that a host whose
+ *  predicate is stuck ON degrades to "the fleet freezes slowly" rather than "the fleet never
+ *  freezes". */
+declare const DEFAULT_ENCODE_BUSY_MAX_DEFER_MS = 3000;
+/** Default `encode.perTask`: `0` reads as "the whole slice", i.e. a window's entire budget drains
+ *  back-to-back in one timer task — the behavior every existing consumer already has. A host that has
+ *  MEASURED its readbacks in the tens or hundreds of ms should pin `1`; see `pumpEncodes`. */
+declare const DEFAULT_ENCODE_PER_TASK = 0;
+/** Default gap between two encode TASKS inside one pacing window (only reachable when
+ *  `perTask < slice`). 16 ms ≈ one 60 Hz display frame, chosen so the host's own rAF gets to run
+ *  BETWEEN two readbacks — which is what makes a frame-derived `busy` predicate fresh again instead
+ *  of stale for the whole drain. */
+declare const DEFAULT_ENCODE_TASK_GAP_MS = 16;
+/** Default `encode.slowEncodeMs`: `0` = the adaptive backoff is OFF, so nothing changes for a host
+ *  that has not asked for it. */
+declare const DEFAULT_ENCODE_SLOW_MS = 0;
+/** Default hold after a readback measured at or over `encode.slowEncodeMs`. */
+declare const DEFAULT_ENCODE_SLOW_BACKOFF_MS = 1000;
+/** Default `encode.maxDim`: `0` = the source canvas is read back at its full backing-store size,
+ *  exactly as it always has been. */
+declare const DEFAULT_ENCODE_MAX_DIM = 0;
+/** Default `encode.parkedStillBytes`: `0` = parked stills are OFF and a revert revokes immediately,
+ *  which is what every consumer has today. The trade is retained pixel memory for skipped readbacks
+ *  (see the module doc's "PARKED STILLS"), so the budget is the host's to choose — 24 MB is the
+ *  measured shape of one fleet's worth of quiet-window stills, not a number this module may assume. */
+declare const DEFAULT_PARKED_STILL_BYTES = 0;
+/** Default `encode.stillCacheBytes`: `0` = KEYED retention is off, so an entry whose last holder
+ *  lets go is revoked exactly as it always has been. Same reasoning as `parkedStillBytes` — the
+ *  budget is memory this module cannot know a device has — with one difference that makes it worth
+ *  more per byte: a retained still is claimable by KEY, so its bytes serve every surface that ever
+ *  reaches that frame rather than the one surface that parked it. */
+declare const DEFAULT_STILL_CACHE_BYTES = 0;
+/** What a capture hook answers INSTEAD of a canvas to report the failure that otherwise reads as a
+ *  success: the capture completed and holds NO VISIBLE PIXELS for a frame the producer knows it drew
+ *  (see the module doc's BLANK CAPTURES). A plain `null` stays what it always was — "I could not
+ *  produce these pixels at all" — and the two are counted apart. */
+declare const STATIC_CAPTURE_BLANK = "blank";
+/** What `StaticImageSwapBinding.captureCanvas` resolves to: the frame as an ordinary 2D canvas,
+ *  `STATIC_CAPTURE_BLANK`, or null. */
+type StaticSurfaceCapture = HTMLCanvasElement | typeof STATIC_CAPTURE_BLANK | null;
+/** Whatever the injected `setTimeout` seam returns; only ever handed back to the injected
+ *  `clearTimeout`. Deliberately opaque so a host can inject any scheduler. */
+type StaticSurfaceTimerHandle = unknown;
+/** The default gate: the host names each painted frame with a content key, and the surface swaps
+ *  once that key has been observed unchanged `observations` times (default
+ *  `STABLE_OBSERVATIONS_BEFORE_SWAP`). */
+interface StaticSurfaceContentKeyGate {
+  kind: "content-key";
+  observations?: number;
+}
+/** The keyless gate: a surface becomes eligible `quietMs` (default `DEFAULT_QUIET_WINDOW_MS`) after
+ *  its LAST DRAW, and thaws the instant it draws again. See the module doc on why the clock is the
+ *  per-draw signal and never `reconcile()`, and on why this gate needs the watchdog. */
+interface StaticSurfaceQuietWindowGate {
+  kind: "quiet-window";
+  quietMs?: number;
+  /** The window for a surface whose LAST reported key was non-null (see the module doc's
+   *  KEYED-OR-QUIET). Default: `quietMs`, i.e. this option is inert unless a host asks for it — a
+   *  host that reports no keys, or that wants keyed surfaces held to the same window as keyless
+   *  ones, is unaffected by its existence.
+   *
+   *  `0` means "eligible the instant it paints", which is the setting for a host whose key is a
+   *  complete description of the frame: there is nothing to wait FOR, because a second paint under
+   *  the same key would not change a pixel and a paint under a different key reverts anyway. The
+   *  cost of pinning it wrongly is stated at the module doc: a stale `<img>` no proxy can catch. */
+  keyedQuietMs?: number;
+}
+type StaticSurfaceGate = StaticSurfaceContentKeyGate | StaticSurfaceQuietWindowGate;
+/** Batching for the (main-thread) encodes — see the module doc. */
+interface StaticSurfaceEncodePacing {
+  /** Encodes kicked per batch. Default `DEFAULT_ENCODE_SLICE`. */
+  slice?: number;
+  /** Gap between batches, ms. Default `DEFAULT_ENCODE_INTERVAL_MS`. */
+  intervalMs?: number;
+  /** `"smallest-first"` (default) orders a batch by backing-store area; `"dom"` keeps the order the
+   *  surfaces became eligible in. */
+  order?: "smallest-first" | "dom";
+  /** `true` defers even the head of a burst through the timer seam instead of encoding it inline on
+   *  the caller's stack (see the module doc's "ENCODE PACING" section). Default `false` — the head
+   *  stays inline, which is today's behavior and every existing consumer's default. */
+  deferHead?: boolean;
+  /** HOST BUSY SIGNAL: "is this a bad instant to spend ~30 ms on a GPU readback?". Consulted ONCE per
+   *  drain pass (never per queued surface), and a pass that it defers re-arms at `intervalMs` rather
+   *  than encoding — the head included, `deferHead` or not. The host owns this because only the host
+   *  can see its own frame loop; absent, nothing about the pacing changes. A predicate that THROWS
+   *  fails OPEN (the pass encodes): a host bug must not be able to stop the mechanism. */
+  busy?: () => boolean;
+  /** Cap on one unbroken run of deferrals, ms — ONE bound shared by `busy` and by the adaptive
+   *  backoff below, so neither of them (nor the two together) can stop the fleet. Default
+   *  `DEFAULT_ENCODE_BUSY_MAX_DEFER_MS`; `0` means NEVER DEFER, i.e. the whole deferral apparatus is
+   *  switched off — `busy` is not consulted and `slowEncodeMs` is not consulted (the A/B lever for a
+   *  host that wants both wired but disabled). Once the bound elapses one pass goes out against a
+   *  still-busy host and the bound restarts, so deferring can only ever slow the fleet down — see the
+   *  module doc. */
+  busyMaxDeferMs?: number;
+  /** Readbacks allowed in ONE task. Default: `slice` (today: the whole slice drains back-to-back).
+   *  `1` is the setting for a host whose surfaces are GPU-resident and big: `toBlob` on such a canvas
+   *  is a SYNCHRONOUS GPU→CPU readback, so N of them in one task is one unsplittable park of
+   *  N × readback — measured downstream at 1,163 ms for four ~4821×2156 surfaces on a phone whose GPU
+   *  was already saturated, against 6-13 ms each for the SAME surfaces once the load passed. `slice`
+   *  still bounds THROUGHPUT per `intervalMs`; this bounds the BLOCK. Setting it below `slice` costs
+   *  `taskGapMs` per extra task and buys back the ability to be interrupted. */
+  perTask?: number;
+  /** Gap between two encode tasks inside one window, ms. Default `DEFAULT_ENCODE_TASK_GAP_MS`.
+   *  Unreachable (and therefore inert) while `perTask >= slice`. */
+  taskGapMs?: number;
+  /** ADAPTIVE BACKOFF, the module's own evidence about readback cost — a readback whose SYNCHRONOUS
+   *  part took at least this long holds the next one for `slowBackoffMs`. On a CAPTURE-HOOK source
+   *  (`StaticImageSwapBinding.captureCanvas`) there is no synchronous part to measure, so what is
+   *  compared against this threshold is the capture's WALL time — the GPU readback's own latency,
+   *  which is precisely the condition this lever exists to back off from. Either way a surface over
+   *  the threshold books `staticImageSlowEncodes`. Default
+   *  `DEFAULT_ENCODE_SLOW_MS` (0 = off). This exists because a host's `busy` predicate is usually
+   *  derived from its frame loop, and a long readback SUPPRESSES the frames that signal is made of:
+   *  the jam manufactures a stale "idle" reading exactly when the system is most overloaded (the
+   *  module doc's stale-signal trap). The measured cost of the previous readback cannot be faked that
+   *  way. Bounded by `busyMaxDeferMs` like every other deferral. */
+  slowEncodeMs?: number;
+  /** How long a slow readback holds the next one, ms. Default `DEFAULT_ENCODE_SLOW_BACKOFF_MS`. */
+  slowBackoffMs?: number;
+  /** READBACK CLAMP: longest edge (backing-store px) the encode may read. Over it, the surface is
+   *  blitted into a scratch canvas at the clamped, ASPECT-PRESERVED size and that is what `toBlob`
+   *  reads — a GPU-side downscale, so a 4821×2156 surface reads back 5.5× fewer pixels. Default
+   *  `DEFAULT_ENCODE_MAX_DIM` (0 = no clamp).
+   *  FIDELITY: the stand-in is presented at the canvas's CSS box with `object-fit: fill`, so a clamp
+   *  is a resampling, not a re-layout — but it IS visible on a surface whose backing store was denser
+   *  than its CSS box. Soft output (a vignette, fog, a glow) survives it; sharp output does not. Ship
+   *  it behind a host A/B, never as a silent default.
+   *  KEY SHARING: `entry.key` names the FRAME, not the encode size, and two surfaces on one key may
+   *  already have different backing sizes — the first to reach the gate encodes and the other
+   *  stretches it. The clamp does not change that contract, only the pixel size of the shared
+   *  frame. */
+  maxDim?: number;
+  /** PARKED STILLS budget, bytes (see the module doc). A revert parks its encoded frame instead of
+   *  revoking it, so a re-freeze of the same, unpainted surface costs no readback at all; this is the
+   *  ceiling on the retained blob bytes that buys. Default `DEFAULT_PARKED_STILL_BYTES` (0 = off,
+   *  today's immediate revoke). The pool is MODULE-wide (key dedup already is), evicts
+   *  least-recently-parked first, and applies the budget of whichever policy last parked into it — a
+   *  document running several swappers should give them the same number. */
+  parkedStillBytes?: number;
+  /** RETAINED STILLS budget, bytes (see the module doc's "RETAINED STILLS"). An entry under a real
+   *  content key whose LAST holder lets go — by revert or by dispose — is kept, held by nobody, so
+   *  the next surface to reach that key attaches for zero readback (`claimStaticStill`) and so
+   *  `bakeStill` has somewhere to publish. Default `DEFAULT_STILL_CACHE_BYTES` (0 = off, i.e. the
+   *  revoke every consumer has today).
+   *  SHARES ONE POOL AND ONE EVICTION WALK with `parkedStillBytes`: the budget the pool is trimmed
+   *  to is the SUM of the two, and either kind may evict the other, least-recently-pooled first.
+   *  What stays separate is admission — this number alone decides whether a KEYED entry may be
+   *  retained — so the two mechanisms can still be switched on and off independently. */
+  stillCacheBytes?: number;
+  /** Exempt the FIRST encode of each key from the deferral apparatus (`busy`, `slowEncodeMs`), not
+   *  from the pacing (see the module doc's "PRIMING UNSEEN KEYS"). Default `false`.
+   *  The judgement it encodes is about SURFACE SIZE: deferral was tuned against ~4821×2156 readbacks
+   *  measured at ~290 ms on a loaded phone, and a fleet of ~320 px canvases collapsing to ~2 distinct
+   *  keys is three orders off that — there, holding the one encode a key will ever need buys no park
+   *  back and leaves the whole fleet in the composite for another window. A host with big surfaces
+   *  must leave this off. */
+  primeUnseenKeys?: boolean;
+}
+/**
+ * The host's policy for the surface image swap. `true` (or an absent option) is exactly
+ * `{ gate: { kind: "content-key" }, onInvalidate: "block" }` — the behavior that shipped first;
+ * `false` disables the mechanism entirely and the runtime takes the path it took before it existed.
+ */
+interface StaticSurfacePolicy {
+  /** How a surface earns its swap. Default `{ kind: "content-key" }`. */
+  gate?: StaticSurfaceGate;
+  /** What a post-swap invalidation (a content-key change, a failed encode/decode) does to the
+   *  surface. Default `"block"` — never offer it again. `"retry"` reverts, resets the gate, and lets
+   *  it re-earn (failed encodes are rescheduled on the encode cadence, forever). */
+  onInvalidate?: "block" | "retry";
+  /** Encode batching. */
+  encode?: StaticSurfaceEncodePacing;
+  /** HOST VETO, consulted inside the "should I swap this?" decision right beside the dormancy check.
+   *  Return false to keep a surface on its canvas — for a host running its own occlusion /
+   *  virtualizer pass over the same DOM, this is how it says "I already claimed this element",
+   *  which is the only way two mechanisms can avoid both owning one element's `display`. */
+  canFreezeSurface?: (node: HTMLElement, canvas: HTMLCanvasElement) => boolean;
+  /** Standing verification cadence over the swapped set, ms (see the module doc). 0 disables it.
+   *  Default: `DEFAULT_SURFACE_WATCHDOG_MS` for the `quiet-window` gate (which REQUIRES it), 0 for
+   *  `content-key` (whose invariant makes it unnecessary, and which therefore keeps costing zero
+   *  idle wakeups). */
+  watchdogMs?: number;
+  /** RESERVED FOR THE HOST RUNTIME — the code that owns the bindings, not the end consumer that
+   *  configures it. Called once after a swap is undone, for ANY cause, with the revert already
+   *  complete (entry released, `<img>` gone, canvas visibility restored), so a re-entrant
+   *  `revertStaticImage` from inside it finds nothing to revert and is a no-op.
+   *
+   *  WHY IT EXISTS. A revert normally uncovers a canvas that still holds the right frame — that is
+   *  the mechanism's safety net, and it needs no notification. `claimStaticStill` breaks that
+   *  assumption on purpose: a surface mounted straight from a cached still has NEVER painted, so
+   *  under its `<img>` is a canvas with no pixels (and, in the runtime this was written for, no
+   *  context and no backing store either). An AUTONOMOUS revert — the watchdog, a host
+   *  `invalidateStaticSurfaces`, a re-size — would therefore uncover a blank surface with nothing
+   *  scheduled to fix it. This is how that runtime hears about it in time to build the surface and
+   *  draw, in the same task, before anything composites.
+   *  A runtime that wraps a consumer's policy MUST run the consumer's handler too, if one was given;
+   *  this module calls exactly the one function it is handed.
+   *  A handler that throws is a host bug and is swallowed here: it must not be able to leave a
+   *  half-reverted surface behind. */
+  onRevert?: (binding: StaticImageSwapBinding) => void;
+  /** Injectable monotonic clock, ms. Default `performance.now()` (falling back to `Date.now()`). */
+  now?: () => number;
+  /** Injectable timer seam. Both must be supplied together; absent ⇒ the globals, and where there is
+   *  no timer host at all (SSR) every deferred path is simply inert. */
+  setTimeout?: (fn: () => void, ms: number) => StaticSurfaceTimerHandle;
+  clearTimeout?: (handle: StaticSurfaceTimerHandle) => void;
+}
+/** The public option shape: `true`/`false` keep their original meaning, an object supplies policy. */
+type StaticSurfaceOption = boolean | StaticSurfacePolicy;
+/** Why a live swap was undone. `staticImageRevertsByCause` splits the aggregate by these. */
+type StaticImageRevertCause = /** The content key moved (the `content-key` gate's churn case). */"key-change" /** The surface stopped producing frozen output at all (the host reported a null key). */ | "not-frozen" /** The surface drew again (the `quiet-window` gate's thaw). */ | "draw" /** A host `invalidateStaticSurfaces` call. */ | "host-invalidate" /** The watchdog found a surface that was no longer legitimately frozen. */ | "watchdog"
+/** A runtime-wide deliberate change: a re-size, a pixel-ratio pin, a mode flip, the kill switch,
+ *  or a geometry move of the canvas itself. */
+| "resize" /** A dormancy wake whose next repaint cannot be attributed (see `noteStaticSurfaceWake`). */ | "dormancy-wake" /** The `<img>` would not decode. */ | "decode-failure";
+/** The counters this module bumps on the host's live stats object (`WebglShaderRuntimeStats`
+ *  extends this). Build one with `createStaticImageSwapCounters()` so a later field addition does
+ *  not break every construction site. */
+interface StaticImageSwapCounters {
+  /** COUNTER. Surfaces whose `<img>` went live (canvas hidden). Monotonic; a surface that swaps,
+   *  reverts and swaps again counts twice. */
+  staticImageSwaps: number;
+  /** COUNTER. Live swaps undone, for ANY reason — the aggregate of `staticImageRevertsByCause`,
+   *  kept under its original name so existing dashboards keep working. Disposal does NOT count
+   *  (the surface is gone, not reverted). */
+  staticImageReverts: number;
+  /** COUNTER, per cause (see `StaticImageRevertCause`). Sums to `staticImageReverts`. */
+  staticImageRevertsByCause: Record<StaticImageRevertCause, number>;
+  /** COUNTER. Frames encoded — ONE per distinct content key, however many surfaces share it.
+   *  Counted when the blob is in hand. */
+  staticImageEncodes: number;
+  /** COUNTER. Encodes/decodes that failed or are unsupported (`toBlob` missing, a null blob, an
+   *  `<img>` that would not decode). Every one of them leaves the surface on its canvas. */
+  staticImageFailures: number;
+  /** COUNTER. Drain passes the host's `encode.busy` predicate sent away — one per PASS, whatever the
+   *  queue length. Zero unless a host supplies the predicate. NOTE, for anyone comparing across
+   *  versions: a host that pins `encode.perTask` below its `slice` makes MORE passes for an identical
+   *  workload, so this number rises with it. The diagnosis pair below is a ratio and is unaffected. */
+  staticImageBusyDeferrals: number;
+  /** COUNTER. Passes that encoded against a still-deferring signal because `busyMaxDeferMs` had
+   *  elapsed. The diagnosis pair: `staticImageBusyForcedEncodes` ≈ `staticImageBusyDeferrals` means
+   *  the host's predicate is stuck ON (every deferral ran the bound out), while forced ≪ deferrals is
+   *  the signal working as intended — bursts ridden out, quiet windows drained normally. */
+  staticImageBusyForcedEncodes: number;
+  /** COUNTER, ms. Summed SYNCHRONOUS cost of every readback (`toBlob`'s own call, any `maxDim` clamp
+   *  blit included) — the main-thread park this module is charged for, as a number rather than a
+   *  trace. */
+  staticImageEncodeMs: number;
+  /** HIGH-WATER, ms. The single worst readback. The regression probe for "N readbacks in one task":
+   *  under `encode.perTask: 1` this IS the longest task the mechanism can produce. */
+  staticImageEncodeMaxMs: number;
+  /** COUNTER. Readbacks measured at or over `encode.slowEncodeMs`, i.e. the ones that armed the
+   *  adaptive backoff. Zero unless a host asks for it. */
+  staticImageSlowEncodes: number;
+  /** COUNTER. Passes the ADAPTIVE BACKOFF sent away. Sibling of `staticImageBusyDeferrals`: the two
+   *  split the deferral total by who asked for it (the host's predicate, or this module's own
+   *  measurement of the previous readback). */
+  staticImageBackoffDeferrals: number;
+  /** COUNTER. Encodes that read a downscaled scratch instead of the source canvas (`encode.maxDim`). */
+  staticImageClampedEncodes: number;
+  /** COUNTER. Frames produced through a binding's `captureCanvas` hook — one per ENCODE (so one per
+   *  distinct content key, like `staticImageEncodes`), not one per surface. Zero on a runtime whose
+   *  surfaces are all directly readable canvases; on a WebGPU runtime it should track
+   *  `staticImageEncodes` exactly. */
+  staticImageCaptures: number;
+  /** COUNTER. Capture hooks that answered null, threw, or handed back a degenerate canvas. Each one
+   *  ALSO lands in `staticImageFailures` (it goes through the same `fail()`), so the aggregate keeps
+   *  its meaning; this is the split that says the failure was the READBACK rather than the codec. */
+  staticImageCaptureFailures: number;
+  /** COUNTER. Captures REFUSED because they held no visible pixels for a frame the producer knew it
+   *  had drawn (`STATIC_CAPTURE_BLANK`, see the module doc's BLANK CAPTURES). A SUBSET of
+   *  `staticImageCaptureFailures` — a capture that produced nothing is a capture failure — split out
+   *  because it is the one failure that would otherwise have looked like a success: without it, a
+   *  device that cannot produce still pixels reads as `staticImagesLive N/N` over N invisible
+   *  surfaces.
+   *
+   *  NON-ZERO MEANS ONE OF TWO THINGS, and they are told apart by whether the affected surfaces ever
+   *  freeze again: a capture path that produces nothing on this device/launch mode (every capture
+   *  blank, nothing swaps, and the surfaces stay on their canvases — the correct outcome), or a
+   *  producer claiming coverage for a frame that really is invisible, which costs that surface its
+   *  freeze and nothing else. Each blank is TERMINAL for its surface under either `onInvalidate`.
+   *
+   *  ZERO IS NOT A CLEAN BILL OF HEALTH FOR A 2D-BACKED FLEET. Only a CAPTURE HOOK can book this;
+   *  a surface read directly through `toBlob` has no equivalent check, on purpose and on evidence
+   *  (the module doc's WHY THE DIRECT PATH IS NOT GUARDED). */
+  staticImageBlankCaptures: number;
+  /** COUNTER, ms. Summed WALL time of every capture hook. Deliberately NOT part of
+   *  `staticImageEncodeMs`: that number means synchronous main-thread park, and a GPU `mapAsync`
+   *  readback does not park the main thread (see the module doc's CAPTURE-HOOK section). */
+  staticImageCaptureMs: number;
+  /** HIGH-WATER, ms. The single slowest capture — the probe for a GPU that has stopped handing
+   *  pixels over promptly, and the number `encode.slowEncodeMs` is compared against on this path. */
+  staticImageCaptureMaxMs: number;
+  /** COUNTER. Freezes served from a PARKED still — a re-attach that cost no readback at all because
+   *  the canvas had not been painted or re-allocated since the entry was encoded (see the module
+   *  doc). Zero unless a host sets `encode.parkedStillBytes`. */
+  staticImageReuseHits: number;
+  /** COUNTER. `claimStaticStill` calls that found an attachable entry for the key — one with a URL
+   *  in hand, live or retained. THE measurement of the second-appearance shortcut: a hit is a
+   *  surface that skipped the gate, the paint and the encode entirely. */
+  staticStillCacheHits: number;
+  /** COUNTER. `claimStaticStill` calls that found nothing attachable, so the caller must render the
+   *  surface itself — no entry, a failed one, or an encode still IN FLIGHT (which has no URL yet;
+   *  the caller cannot wait, so it renders, and the ordinary gate will swap it when it settles). A
+   *  steady stream of these against a stable key population means the stills are not surviving —
+   *  check `staticStillRetainedEntries` and `encode.stillCacheBytes` before blaming the keys. */
+  staticStillCacheMisses: number;
+  /** COUNTER. Claimed stills whose `<img>` actually went live (decoded and mounted). Sits below
+   *  `staticStillCacheHits` by exactly the claims that were undone before their decode finished — a
+   *  revert, a dispose, or a decode failure — which is the only way to tell "the key was there" from
+   *  "the pixels reached the screen". */
+  staticStillMounts: number;
+  /** COUNTER. `bakeStill` calls that really enqueued an encode (a bake for a known key, a solo key,
+   *  or an unreadable canvas is a no-op and books nothing). One per key, by construction. */
+  staticStillBakes: number;
+  /** GAUGE — entries sitting in the module-wide still pool RIGHT NOW, parked and retained together
+   *  (see the module doc's "RETAINED STILLS"). Read through `staticStillPoolStats()`; like
+   *  `staticImageUrlsLive` it is document-wide rather than per runtime, and a host refreshes it on
+   *  each `stats()` read. */
+  staticStillRetainedEntries: number;
+  /** GAUGE — bytes those entries pin (each blob's own `size`, as recorded at publish). The number to
+   *  compare against `parkedStillBytes + stillCacheBytes`: at the budget, the pool is evicting. */
+  staticStillRetainedBytes: number;
+  /** GAUGE — how many OBJECT URLS are alive right now, MODULE-wide (across every runtime in the
+   *  document), refreshed on each `stats()` read. This is the leak probe: it must come back to 0
+   *  after the last runtime is disposed. NOT a swap count — one URL can back many surfaces, and under
+   *  `encode.parkedStillBytes` a URL held by NO surface still counts, because its bytes are still
+   *  pinned. Dispose revokes those too, so the probe is unaffected. */
+  staticImageUrlsLive: number;
+  /** GAUGE — how many SURFACES are swapped right now (`<img>` up, canvas hidden) against THIS
+   *  counters object, i.e. per runtime. Rises on swap, falls on revert AND on dispose, so it comes
+   *  back to 0 at teardown. This is the "is the mechanism actually engaged?" measurement (`72/72`);
+   *  `staticImageUrlsLive` cannot answer that, because one URL can back many surfaces. */
+  staticImagesLive: number;
+}
+/** A zeroed counters object (see `StaticImageSwapCounters`). */
+declare function createStaticImageSwapCounters(): StaticImageSwapCounters;
+/** Per-surface swap state. Present only while the mechanism is enabled — `null` is the kill switch,
+ *  and the host's render path then takes exactly the code it took before this module existed. */
+interface StaticImageState {
+  /** The content key of the frame the canvas currently holds (null until the first cacheable render,
+   *  and typically null throughout for a keyless `quiet-window` surface). */
+  key: string | null;
+  /** Consecutive unchanged observations of `key` (the `content-key` gate). */
+  stable: number;
+  /** The stand-in element, once one exists (created at swap time, dropped on revert). */
+  img: HTMLImageElement | null;
+  /** The refcounted per-key object-URL entry this surface holds, or null. Non-null covers BOTH "the
+   *  encode/decode is in flight" and "the `<img>` is live" — see `shown`. */
+  entry: StaticImageEntry | null;
+  /** The entry this surface's LAST freeze left parked (`encode.parkedStillBytes`), held by nobody and
+   *  claimable only by this surface. Mutually exclusive with `entry`: a surface holds its still or
+   *  parks it, never both. */
+  parked: StaticImageEntry | null;
+  /** The reuse fingerprint `parked` was stamped with — the paint count and backing-store size the
+   *  entry was ENCODED at. `reclaimParkedStill` re-attaches only while the canvas still reports all
+   *  three unchanged, which is the whole correctness argument for handing back old pixels. */
+  parkedDrawSeq: number;
+  parkedW: number;
+  parkedH: number;
+  /** The `<img>` is mounted and standing in for the canvas. */
+  shown: boolean;
+  /** The entry this surface currently holds was taken by `claimStaticStill` rather than earned
+   *  through the gate — i.e. this canvas has never painted the frame the `<img>` is showing, and may
+   *  never have painted at all. Cleared when the entry is let go. Read only to split
+   *  `staticStillMounts` out of the ordinary swap count; the mechanics below treat a claimed surface
+   *  exactly like any other, which is deliberate — its stand-in reverts, re-syncs and is refcounted
+   *  by the same code. */
+  claimed: boolean;
+  /** Disqualified for the life of the binding (only reachable under `onInvalidate: "block"`). */
+  blocked: boolean;
+  /** The swapper this surface belongs to: its policy, its encode queue, its timers. Every free
+   *  function in this module reads the policy from here, so one document can run several runtimes
+   *  under different policies. */
+  swapper: SwapperContext;
+  /** The counters object this surface's TIMER-driven paths (sweep, watchdog, retry, dispose) bump.
+   *  Seeded when the swapper attaches the binding and refreshed by every call that carries one, so
+   *  a deferred revert lands on the same object the synchronous ones did. */
+  counters: StaticImageSwapCounters | null;
+  /** `now()` of the last reported paint into this canvas — the `quiet-window` gate's clock. */
+  lastDrawAt: number;
+  /** Monotonic count of reported paints; the watchdog compares it against `drawSeqAtFreeze`. */
+  drawSeq: number;
+  drawSeqAtFreeze: number;
+  /** Backing-store size at freeze time: a `width`/`height` write REALLOCATES (and clears) a canvas,
+   *  which the watchdog reads as an unexplained repaint. */
+  frozenW: number;
+  frozenH: number;
+  /** The canvas's inline style at freeze time. The stand-in copies the box ONCE, so a later
+   *  placement write would leave it at the old box — the watchdog re-syncs on a mismatch. */
+  boxCss: string;
+  /** Earliest `now()` at which a failed encode/decode may be retried (`onInvalidate: "retry"`). */
+  retryAfter: number;
+  /** THIS module hid the canvas (so it, and only it, may un-hide it). */
+  hidCanvas: boolean;
+  /** The canvas's `display` as the HOST left it, captured the moment this module first hid it and
+   *  restored verbatim when it un-hides. */
+  hostDisplay: string;
+}
+/** The subset of a host runtime's node binding this module touches. Structural on purpose: it keeps
+ *  the swap independently testable and keeps the host runtimes free of a back-import. */
+interface StaticImageSwapBinding {
+  /** The host's node element — passed to `canFreezeSurface`, never otherwise read or written. */
+  node: HTMLElement;
+  canvas: HTMLCanvasElement;
+  /** Set whenever the canvas may not match `state.key` yet (a pending re-render, a realloc that
+   *  cleared it). The gate refuses to encode from a dirty binding. */
+  dirty: boolean;
+  /** Parked by the host: observes nothing, and hides BOTH surfaces. */
+  dormant: boolean;
+  /** ASYNC ENCODE SOURCE, for a surface whose own canvas cannot be read back — a WebGPU one, whose
+   *  every canvas-read path is blank headless and pathological on Android (see the module doc's
+   *  CAPTURE-HOOK SOURCES). Returns a fresh 2D canvas holding the frame the surface is CURRENTLY
+   *  showing, at its backing-store size, or null when it cannot be produced; this module encodes
+   *  that canvas and then releases it. `STATIC_CAPTURE_BLANK` is the third answer: the capture
+   *  completed and holds NOTHING VISIBLE, for a frame the producer knows it drew (see the module
+   *  doc's BLANK CAPTURES). ABSENT ⇒ `canvas` is read directly, which is what every 2D-backed
+   *  surface does and is exactly the path that shipped first. */
+  captureCanvas?: () => Promise<StaticSurfaceCapture>;
+  staticImage: StaticImageState | null;
+}
+/** One encoded frame, shared by every surface on that content key. */
+interface StaticImageEntry {
+  key: string;
+  /** Surfaces holding this entry (swapped or waiting for the encode). At 0 the URL is revoked. */
+  refs: number;
+  url: string | null;
+  /** The encode failed / is unsupported and no one may retry this key. Only ever set under
+   *  `onInvalidate: "block"` — a `retry` policy drops the entry instead, so the key stays open. */
+  failed: boolean;
+  /** Encoded size in bytes, captured from the blob at publish (0 until then). The still pool budgets
+   *  on this: what a pooled entry costs is its retained pixels, not its pixel count. */
+  bytes: number;
+  /** Surfaces waiting for the in-flight encode. */
+  waiters: Set<StaticImageSwapBinding>;
+  /** BORN HELD BY NOBODY: this entry was created by `bakeStill` for a key with no waiting surface,
+   *  so `refs: 0` is its normal state and not the "everyone let go" that the encode tail drops an
+   *  entry for. The three places that read `refs <= 0` as abandonment — the queue drain, the capture
+   *  tail and `publish` — consult this to tell the two apart. A published bake goes straight into
+   *  the retained pool, where the flag stops mattering: from then on it behaves like any other
+   *  unheld entry. */
+  bake: boolean;
+}
+interface ResolvedPolicy {
+  quietWindow: boolean;
+  observations: number;
+  quietMs: number;
+  /** The quiet window for a surface whose last reported key was non-null (`keyedQuietMs`, defaulted
+   *  to `quietMs` here so every read site is one lookup and the inert case costs nothing). */
+  keyedQuietMs: number;
+  retry: boolean;
+  slice: number;
+  intervalMs: number;
+  smallestFirst: boolean;
+  deferHead: boolean;
+  busy: (() => boolean) | null;
+  busyMaxDeferMs: number;
+  perTask: number;
+  taskGapMs: number;
+  slowEncodeMs: number;
+  slowBackoffMs: number;
+  maxDim: number;
+  parkedStillBytes: number;
+  stillCacheBytes: number;
+  /** What the shared pool is trimmed to: the two budgets added, because the two kinds of unheld
+   *  still are the same bytes (see the module doc). Precomputed so the eviction walk reads one
+   *  number. */
+  poolBytes: number;
+  primeUnseenKeys: boolean;
+  watchdogMs: number;
+  canFreeze: ((node: HTMLElement, canvas: HTMLCanvasElement) => boolean) | null;
+  onRevert: ((binding: StaticImageSwapBinding) => void) | null;
+  now: () => number;
+  setT: ((fn: () => void, ms: number) => StaticSurfaceTimerHandle) | null;
+  clearT: (handle: StaticSurfaceTimerHandle) => void;
+}
+interface EncodeJob {
+  entry: StaticImageEntry;
+  canvas: HTMLCanvasElement;
+  /** The binding's async encode source, or null for the ordinary "read the canvas" path. Captured
+   *  at ENQUEUE so the job stays self-contained: the queue outlives the call that made the surface
+   *  eligible, and the pacing must not have to reach back into a binding to drain. */
+  capture: (() => Promise<StaticSurfaceCapture>) | null;
+  area: number;
+  counters: StaticImageSwapCounters;
+  /** `bakeStill`'s completion hook, or undefined for an ordinary surface-driven encode (whose
+   *  completion IS its `<img>` going up). Called exactly once, wherever the job ends. */
+  settle?: (published: boolean) => void;
+}
+/** One policy + its bookkeeping. Shared by every surface the swapper attached. */
+interface SwapperContext {
+  policy: ResolvedPolicy;
+  counters: StaticImageSwapCounters | null;
+  bindings: Set<StaticImageSwapBinding>;
+  queue: EncodeJob[];
+  /** Start of the current encode WINDOW, and how many encodes it has already kicked (see
+   *  `pumpEncodes`). */
+  sliceAt: number;
+  sliceCount: number;
+  /** Readbacks the CURRENT task has already spent (`encode.perTask`). Reset only where a task
+   *  boundary is actually observable — inside a timer callback — because the module is handed the
+   *  thread many times per task: one `runSweep` calls `maybeSwap` for every eligible surface, and
+   *  each of those reaches `pumpEncodes` on the SAME stack. A per-call counter would therefore bound
+   *  nothing at all on the path that produced the measured 1,163 ms park. */
+  taskKicks: number;
+  /** `now()` the CURRENT unbroken run of deferrals started, or `NOT_DEFERRING`. The bound is measured
+   *  from here and restarts on every forced pass, so it caps a RUN rather than the queue's total wait
+   *  — and it is ONE run whichever reason is deferring (see `encodeDeferred`). */
+  busyDeferSince: number;
+  /** `now()` until which the adaptive slow-encode backoff holds encodes (0 = not backing off). */
+  backoffUntil: number;
+  /** The scratch canvas `encode.maxDim` downscales into, allocated on the first clamped encode and
+   *  released at dispose. ONE per swapper: `toBlob` snapshots its source synchronously in Blink (the
+   *  guarantee gsw's own perf harness already depends on — `scenarios/static-surfaces.ts`), so reuse
+   *  cannot race a blob still being compressed. */
+  scratch: HTMLCanvasElement | null;
+  drainTimer: StaticSurfaceTimerHandle | null;
+  sweepTimer: StaticSurfaceTimerHandle | null;
+  /** Absolute `now()` the armed sweep fires at (so an arm never postpones an earlier one). */
+  sweepAt: number;
+  lastWatchdogAt: number;
+  disposed: boolean;
+}
+/** The host-facing handle: everything that needs to enumerate the swapper's surfaces. Per-surface
+ *  signalling stays in the free functions below, which read the policy off the surface's state. */
+//#endregion
+//#region src/runtime-options.d.ts
+/** Browser effect hosting controls, separate from HTML model projection. */
+interface GodotHtmlRuntimeOptions extends Pick<GodotHtmlRenderOptions, "enableWebglShaders" | "enableParticles"> {
+  externalRuntimes?: boolean;
+  resolveShaderSource?: (path?: string, uid?: string) => Promise<string | undefined> | string | undefined;
+  particleMaxInstances?: number;
+  particleFps?: number;
+  particleRectCache?: boolean;
+  particleObserverSizing?: boolean;
+  particleDormant?: boolean;
+  particleTravelExtents?: boolean;
+  staticParticles?: boolean;
+  staticParticleOneShotExpiry?: boolean;
+  staticParticlePixelRatio?: number;
+  parkStaticParticleBlend?: boolean;
+  staticParticleImages?: StaticSurfaceOption;
+  staticParticleFreezeAtMount?: boolean;
+  shaderFps?: number;
+  effectsLoopPacing?: EffectsLoopPacing;
+  effectsRenderer?: "auto" | "webgl" | "webgpu";
+  effectsProfiling?: boolean;
+  renderScale?: number;
+  staticShaders?: boolean;
+  staticShaderTime?: number;
+  staticShaderPixelRatio?: number;
+  staticShaderImages?: StaticSurfaceOption;
+  maxTextureDimension?: number;
+  enableScreenTextureCapture?: boolean;
+  maxScreenCaptureDim?: number;
+  onUnsupported?: UnsupportedRenderReporter;
+  onBindingRendered?: (node: HTMLElement, canvas: HTMLCanvasElement, info: GodotEffectRenderInfo) => void;
+}
+/** Options accepted by a host that both emits a model and mounts its effects. */
+type GodotHtmlMountOptions = GodotHtmlRenderOptions & GodotHtmlRuntimeOptions;
+//#endregion
+//#region src/webgl/shared-gl.d.ts
+interface GpuInfo {
+  /** The unmasked GL renderer string, or "" when masked/unknown/unavailable. */
+  renderer: string;
+  /** True only when `renderer` POSITIVELY matches a software rasterizer — never on "" (unknown). */
+  software: boolean;
+  /** True when WebGL is unavailable at all (no context). */
+  unavailable: boolean;
+}
+declare function describeGpu(): GpuInfo;
+declare function effectivePixelRatio(renderScale?: number): number;
+declare const MAX_PINNED_BACKING_DIM = 2048;
+/** Backing-store size (px) for a `cssW`×`cssH` surface at `ratio`, plus the ratio ACTUALLY applied —
+ *  which differs from `ratio` only when `maxDim` bit, and is what a caller that draws geometry in
+ *  CSS px × ratio (the particle runtime) must scale by so its sprites still land inside the canvas.
+ *
+ *  With `maxDim` the result is scaled down ASPECT-PRESERVINGLY (the `downscaleForUpload` idiom) so
+ *  its longest edge fits. Per-axis clamping is not an option: the shader runtime's `uvFit` derives
+ *  contain/cover from the canvas aspect, so a squashed backing store would re-fit the texture
+ *  wrongly. Without `maxDim` (or under it) this is exactly the `Math.max(1, Math.round(css * ratio))`
+ *  both runtimes have always done, and `ratio` comes back untouched. */
+declare function backingStoreSize(cssW: number, cssH: number, ratio: number, maxDim?: number): {
+  w: number;
+  h: number;
+  ratio: number;
+};
+/** The self-layer attribute that carries a surface's PER-BINDING backing-density multiplier — the
+ *  factor by which the device pixels this surface really covers exceed its own CSS box.
+ *
+ *  Both fx runtimes size a canvas from `clientWidth × (devicePixelRatio × renderScale)`, and
+ *  `clientWidth` is blind to ancestor CSS transforms: a node under a `transform: scale(1.41)`
+ *  ancestor lays out at its untransformed width, so its backing store is sized for 1/1.41 of the
+ *  device pixels it is magnified onto and the surface is visibly soft. Nothing the runtime can read
+ *  off its own element tells it that — the transform belongs to an ancestor the runtime does not
+ *  own, and finding it would be a `getBoundingClientRect()` walk per surface per frame, i.e. exactly
+ *  the forced layout both runtimes are built around avoiding.
+ *
+ *  So the HOST states it. It already composed that transform to write it; this attribute is that
+ *  number, handed down. It is a MULTIPLIER on the density term, not a replacement for it: the
+ *  device ratio, `renderScale` and any frozen-mode pin all still apply, and this rides on top.
+ *
+ *  IT IS AN AXIS SCALE, NOT A BOUNDING-BOX RATIO, and a host that confuses the two will over-allocate
+ *  every rotated surface it owns. `getBoundingClientRect()` returns the axis-aligned bounding box of a
+ *  transformed element, so a square rotated θ measures `|cos θ| + |sin θ|` wider than it is — √2 at
+ *  45° — while covering exactly as many device pixels as before. Rotation is rigid. The number this
+ *  attribute wants is the transform's column norm (or the mean of the two under a non-uniform scale).
+ *
+ *  Named `data-godot-shader-*` and read by the PARTICLE runtime as well, deliberately — one name
+ *  for one question ("how magnified is this surface?") that both fx families ask identically, so a
+ *  host stamps it the same way whichever runtime picks the node up. */
+declare const SURFACE_PIXEL_RATIO_ATTR = "data-godot-shader-pixel-ratio";
+/** Ceiling on the attribute above. The multiplier is the one density input that arrives as a STRING
+ *  from outside the runtime — `renderScale` is clamped to ≤ 1 and the static pin is bounded by
+ *  `MAX_PINNED_BACKING_DIM` — so a host mid-animation, or a host with a bug, could otherwise turn
+ *  one attribute write into a quadratic backing-store allocation on a surface the runtime has no
+ *  other reason to distrust. 4 is 16× the area, past any magnification a UI plausibly applies to a
+ *  live effect, and a surface asking for more is far likelier to be wrong than under-resolved. */
+declare const MAX_SURFACE_PIXEL_RATIO = 4;
+/** Parse `SURFACE_PIXEL_RATIO_ATTR` into a density MULTIPLIER.
+ *
+ *  Absent, empty, unparseable, non-finite or non-positive ⇒ exactly `1`, i.e. the density term is
+ *  the product it has always been and the surface is sized byte-for-byte as it was before this
+ *  attribute existed. That is the whole off-switch: a host that never writes the attribute cannot
+ *  tell this feature is here.
+ *
+ *  Values BELOW 1 are honoured (a surface minified by an ancestor really does cover fewer device
+ *  pixels than its box). Above `MAX_SURFACE_PIXEL_RATIO` they are capped, not rejected — a too-large
+ *  value is still evidence the surface is magnified, so clamping keeps most of the fix while
+ *  refusing the allocation. */
+declare function parseSurfacePixelRatio(attr: string | null | undefined): number;
+//#endregion
+//#region src/webgpu/device.d.ts
+type WebgpuFallbackReason = "no-navigator-gpu" | "no-adapter" | "fallback-adapter" | "acquire-timeout" | "device-lost" | "context-refused" | "pipeline-error";
+//#endregion
+//#region src/particles/runtime.d.ts
+/** OPT-IN per-frame cost attribution for ONE particle runtime (`effectsProfiling`, see `../types`),
+ *  read from `stats().profile`. NULL when the option is off — see `ParticleRuntimeStats.profile`.
+ *
+ *  WHY IT EXISTS. A live tick's wall clock alone says nothing about what to DO: "9 ms/frame" is the
+ *  same number whether the CPU integrator is chewing through 2000 particles × 4 sub-steps, the
+ *  instance buffer is being rebuilt per frame, or the GL→2D blit is fill-bound at
+ *  devicePixelRatio 3. Those have opposite fixes (`particleFps`/`amount`/`staticParticles` vs
+ *  `renderScale`), so the tick is split into the four buckets below and each carries its own WORK
+ *  counter — a millisecond total is only interpretable next to the work that produced it.
+ *
+ *  Counters are monotonic and never reset (the `ParticleRuntimeStats` contract): a benchmark
+ *  snapshots the object, runs its window, and diffs. Times are `performance.now()` deltas in ms,
+ *  summed — wall clock on the main thread, so an interrupted frame charges its interruption to
+ *  whichever bucket was open. */
+interface ParticleProfile {
+  /** LIVE ticks that simulated + drew at least one binding. The frozen (`staticParticles`) path
+   *  books NONE: it draws once and parks the loop, so a frozen runtime reports `ticks: 0` and every
+   *  other field 0 — which is the right report for a mode whose whole point is that it has no
+   *  per-frame cost. A deferred tick (the FPS cap re-arming without work) books none either. */
+  ticks: number;
+  /** Bindings simulated + drawn, summed across those ticks. `bindings / ticks` is the live system
+   *  count the frame really paid for — suspended, parked and unmounted bindings are skipped by the
+   *  loop and never counted. */
+  bindings: number;
+  /** Fixed sub-steps `simulateParticles` executed. THE sim work unit, and deliberately not the tick
+   *  count: the sim runs at `fixed_fps` (30 by default) regardless of display rate, so a 60Hz device
+   *  runs ~0.5 steps per tick per binding and a stalled frame runs several. `simMs / simSteps` is
+   *  therefore the only stable cost-per-unit, and a `simSteps` far from `bindings` is the proof that
+   *  the sim rate is decoupled from the display rate. */
+  simSteps: number;
+  /** Instances pushed into the GL instance buffer ≈ live particles actually drawn (a dead or
+   *  fully-transparent particle is skipped by the build loop). The denominator for both `buildMs`
+   *  and `glMs`, and the number to compare against `particleMaxInstances`. */
+  instances: number;
+  /** CPU simulation: `simulateParticles` (integrate + emit + curve sampling). The bucket the
+   *  mid-range-phone suspicion points at. */
+  simMs: number;
+  /** Instance-buffer BUILD: the per-particle push loop in `drawBinding` that turns simulation state
+   *  into the interleaved float array. Separate from `simMs` because it is a different fix — it
+   *  scales with LIVE particles, not with sub-steps. */
+  buildMs: number;
+  /** GL SUBMIT: `drawParticles` — uniform writes, the buffer upload and the instanced draw call.
+   *  SUBMIT ONLY: the GPU executes asynchronously, so this is main-thread issue cost, never GPU
+   *  time. A GPU-bound frame shows up as back-pressure in `blitMs` (the readback-shaped
+   *  `drawImage`), not here. */
+  glMs: number;
+  /** GL→2D BLIT: the binding canvas's `clearRect` plus the `drawImage` that copies the shared GL
+   *  canvas onto it. Pure fill cost, so it scales with BACKING-STORE AREA (`renderScale`,
+   *  `devicePixelRatio`, the sprite `pad`) and not with particle count — which is exactly the
+   *  distinction a "particles are slow" report cannot make without this split. */
+  blitMs: number;
+}
+/** Live, monotonically-increasing counters for ONE particle runtime (see `ParticleRuntime.stats`).
+ *  Same contract as the shader runtime's `WebglShaderRuntimeStats`: plain `++` writes, never reset,
+ *  the SAME object returned on every `stats()` call (snapshot to diff). */
+interface ParticleRuntimeStats extends StaticImageSwapCounters {
+  /** Actual instanced GL draws of a particle-system frame (`drawBinding` reaching `drawParticles`). */
+  draws: number;
+  /** Frozen-mode static-frame cache hits: the warm AND the instanced draw were both skipped and a
+   *  cached canvas blitted instead (see `./static-frame-cache`). The shader runtime's `cacheHits`
+   *  sibling. A fleet of N identical frozen systems should settle at 1 `draws` + (N-1) `cacheHits`. */
+  cacheHits: number;
+  /** `syncCanvasSize` calls that sized a binding at the PINNED static ratio
+   *  (`staticParticlePixelRatio`) instead of `devicePixelRatio × renderScale` — the shader runtime's
+   *  `pinnedCanvasSyncs` sibling, and the same purpose: a device probe reads it to confirm the pin
+   *  is really in force (0 = option unset, or frozen mode never entered). */
+  pinnedCanvasSyncs: number;
+  /** Self-layer box reads: `selfLayer.clientWidth`/`clientHeight`, i.e. the layout this runtime
+   *  forces. Booked by the create-time measure pass and by any `syncCanvasSize` that had neither a
+   *  ResizeObserver `contentRect` nor a cached box. With the cache on (`particleRectCache`, the
+   *  default) it settles at exactly one per binding CREATED and zero for everything after — fleet
+   *  re-sizes, texture-load re-pads and observer deliveries are all reflow-free — so a device probe
+   *  can confirm that live. It counts READS, not flushes: the create-time reads are batched into one
+   *  contiguous run, so N new bindings book N reads and cost ONE forced layout flush.
+   *
+   *  With `particleObserverSizing` also on (the default) even that per-create read is gone and this
+   *  settles at **0**: a new binding's first box arrives from the shared ResizeObserver, off the main
+   *  path. Any read left standing is therefore a real signal — a wake whose observation never landed,
+   *  or the mount backstop firing on an engine that does not deliver 0x0 initial observations. */
+  boxReads: number;
+  /** COUNTER. Bindings PARKED (canvas hidden) because their subtree went suspended — a create that
+   *  was born parked included. Monotonic: a binding that parks, wakes and parks again counts twice.
+   *  0 means the park never engaged (nothing suspended, or `particleDormant: false`). */
+  dormantParks: number;
+  /** COUNTER. Parked bindings woken again (the resume half, so a probe can tell "parked and stayed
+   *  parked" from "flapped"). */
+  dormantWakes: number;
+  /** COUNTER. Bindings the expiry sweep DISPOSED for real after ~`DORMANT_DISPOSE_SECONDS` parked
+   *  (canvas removed from the DOM, GL buffer released) rather than holding them forever. */
+  dormantDisposes: number;
+  /** GAUGE — bindings parked RIGHT NOW, sampled on each `stats()` read (the `staticImagesLive`
+   *  contract exactly, and re-derived from the binding set rather than trusted incrementally). This
+   *  is the "is the park actually engaged?" measurement a device probe reads — `28/33` — which the
+   *  monotonic counters above cannot answer. */
+  dormantLive: number;
+  /** Per-frame cost attribution (see `ParticleProfile`), or NULL when `effectsProfiling` is off —
+   *  which is the default, and the no-op handle always. NULL rather than a zeroed object ON PURPOSE:
+   *  a bench that read `simMs: 0` out of an un-instrumented runtime would report "the simulation is
+   *  free" when the truth is "nobody measured". The same object every `stats()` call, mutated in
+   *  place by the live tick. */
+  profile: ParticleProfile | null;
+  /** GAUGE — which renderer this runtime's bindings are drawing through RIGHT NOW, re-derived on
+   *  each `stats()` read (a runtime can change backend mid-life, in one direction: a WebGPU device
+   *  that is lost is rebuilt on WebGL).
+   *
+   *  `"pending"` is a real state, not a transient to be waited out politely: with
+   *  `effectsRenderer: "auto"`/`"webgpu"` on a browser that HAS `navigator.gpu`, the device arrives
+   *  from a promise, and until it does the bindings exist, are sized and are mounted but have no
+   *  surface and draw nothing. `"none"` is the no-op handle (no WebGL2, or particles disabled). */
+  renderer: "pending" | "webgpu" | "webgl" | "none";
+  /** COUNTER. Times this runtime adopted WebGL after being asked for `"auto"`/`"webgpu"` — the
+   *  SYNCHRONOUS "this browser has no navigator.gpu" decline included, which is the common case and
+   *  the reason a plain WebGL page reports 1 here rather than 0. Stays 0 for `effectsRenderer:
+   *  "webgl"` (nothing was ever asked for) and for a runtime that adopted WebGPU and kept it. */
+  webgpuFallbacks: number;
+  /** The FIRST reason this runtime declined WebGPU (later ones cannot un-explain it), or null while
+   *  it never has. THE diagnostic for a silent fallback: `renderer: "webgl"` under
+   *  `effectsRenderer: "webgpu"` says something went wrong, and only this says what. */
+  webgpuFallbackReason: WebgpuFallbackReason | null;
+  /** COUNTER — `queue.submit` calls this runtime's WebGPU backend has made, sampled on read. ONE per
+   *  tick that drew anything, whatever the binding count: that batching is the measured win (S7), so
+   *  a probe that finds it climbing with N systems has found the win being given back. 0 on WebGL,
+   *  where the question is meaningless. */
+  webgpuSubmits: number;
+  /** GAUGE — `device.lost` resolutions seen by the page-wide device (see `../webgpu/device`). A lost
+   *  device stops producing frames, so a non-zero value here next to `renderer: "webgl"` is the
+   *  device-loss rebuild having happened. */
+  webgpuDeviceLosses: number;
+  /** GAUGE — `uncapturederror` events on the page-wide device. Non-zero means a frame was silently
+   *  WRONG: WebGPU reports most command-level mistakes this way and nothing else says so. */
+  webgpuErrors: number;
+  /** GAUGE — BAKE DONORS this runtime is holding right now (see `donateStill`): bindings whose node
+   *  is gone but whose surface is kept alive, out of the DOM, only long enough to encode the frame
+   *  their successors will claim. Sampled on each `stats()` read. A number pinned at the bound means
+   *  bakes are not draining — check `staticStillDonorBakes` against `staticStillDonorsDropped`. */
+  staticStillDonors: number;
+  /** COUNTER. Donor bakes that PUBLISHED, i.e. banked a frame nothing had encoded yet. Each one is a
+   *  key the next binding to reach it can claim for free. */
+  staticStillDonorBakes: number;
+  /** COUNTER. Donors released WITHOUT publishing — evicted by the donor bound, or dropped at runtime
+   *  teardown. A donor is speculative work by construction, so these are not failures; a run where
+   *  they dominate `staticStillDonorBakes` means the bound is too small for the scene's churn, or
+   *  that retention (`encode.stillCacheBytes`) is off and every bake is refused. */
+  staticStillDonorsDropped: number;
+}
+/** A persistent particle runtime for a mounted scene root (see `createParticleRuntime`). */
+interface ParticleRuntime {
+  /** Diff the current `[data-godot-particle-runtime]` nodes against the live bindings:
+   *  unchanged specs keep their running simulation, changed/new specs re-init that node only,
+   *  gone nodes are disposed. */
+  reconcile(): void;
+  /** Live retune the backing-store resolution (devicePixelRatio × clamped `scale`) without a
+   *  dispose+recreate — running simulations keep going, only the canvas density changes. While a pin
+   *  is in force (see `setStaticParticlePixelRatio`) AND the runtime is frozen this re-sizes nothing:
+   *  the frozen canvases are deliberately held still. The new scale applies to live bindings as soon
+   *  as frozen mode is left. */
+  setRenderScale(scale: number): void;
+  /** Live set/clear the pinned FROZEN backing-store ratio (see `staticParticlePixelRatio`). Pass
+   *  `undefined` (or a non-positive value) to un-pin. Only frozen bindings are affected. */
+  setStaticParticlePixelRatio(ratio: number | undefined): void;
+  /** Live retune the particle FPS cap (0 = uncapped). */
+  setFps(fps: number): void;
+  /** Live toggle frozen (single-shot) mode, mirroring `WebglShaderRuntime.setStaticShaders`: warm each system
+   *  to a representative mid-flight state, draw ONCE, then park the loop (true); or resume live simulation (false).
+   *  The low-cost fallback that shows a frozen spray of particles instead of a per-frame CPU sim + GL draw. */
+  setStaticParticles(value: boolean): void;
+  /** Live toggle of the frozen-surface image swap (see the `staticParticleImages` option and
+   *  `../surface-image-swap`), mirroring `WebglShaderRuntime.setStaticShaderImages`. Turning it OFF
+   *  reverts every live swap immediately and revokes its object URLs — the kill switch, safe to
+   *  throw at any time. Turning it ON arms the runtime's CONFIGURED policy (a boolean here never
+   *  replaces it) and every binding re-earns its window; a runtime left at the DEFAULT (`false`,
+   *  since this option is opt-in) has no configured policy to arm, so ON gives it the same
+   *  quiet-window policy `staticParticleImages: true` means — otherwise this switch could never
+   *  turn the mechanism on for the consumers it exists for. */
+  setStaticParticleImages(value: boolean): void;
+  /** HOST-DRIVEN revert of the surface image swap, WITHOUT blocking, mirroring the shader runtime's:
+   *  with no argument every swapped surface is handed back to its canvas; with a node list, only the
+   *  bindings at (or under) those elements. Each affected surface restarts its gate and re-earns the
+   *  swap on its own. This is how a host that knows something the runtime cannot see — it is about
+   *  to re-parent a subtree, it just re-themed, its own occlusion pass changed its mind —
+   *  un-shadows a stale stand-in immediately instead of waiting for a watchdog window. */
+  invalidateStaticSurfaces(nodes?: Iterable<HTMLElement>): void;
+  /** The runtime's live counters (see `ParticleRuntimeStats`). Returns the SAME live object every
+   *  call — read-only by convention; snapshot (spread) it to diff. All-zero on the no-op handle.
+   *  `.profile` carries the opt-in per-frame cost attribution (`effectsProfiling`) and is NULL
+   *  whenever it was not measured, the no-op handle included. */
+  stats(): ParticleRuntimeStats;
+  /**
+   * TEST / DIAGNOSTIC HOOK: this node's binding re-rendered into an offscreen texture and read back
+   * as tightly-packed RGBA (PREMULTIPLIED, top-down, at the canvas's BACKING-STORE size), or null
+   * when there is nothing to read — no binding at (or under) `node`, no surface yet, a zero-sized
+   * canvas, or a runtime rendering on WebGL.
+   *
+   * WEBGL RETURNS NULL ON PURPOSE, and it is not a gap: that canvas holds readable 2D pixels, so a
+   * caller who wants them uses `getImageData` on it. This exists because a WebGPU canvas has no such
+   * path — `drawImage`/`toDataURL` from one are blank under headless Chrome and pathological on
+   * Android (docs/perf-harness.md S7) — so the frame has to be produced a SECOND time, into a
+   * texture that `copyTextureToBuffer` can reach (`../webgpu/readback`). It renders the binding's
+   * CURRENT state, which for a frozen/static binding is exactly the frame on screen.
+   *
+   * This is the WebGL↔WebGPU image-parity harness's capture path, and the seam the readback-based
+   * surface image swap encodes from — `attachSurfaceSwap` gives a WebGPU binding a `captureCanvas`
+   * hook built out of exactly this production (`../surface-image-swap`).
+   */
+  captureNodePixels?(node: HTMLElement): Promise<Uint8Array | null>;
+  /** Tear down every binding and stop the loop. */
+  dispose(): void;
+}
+/**
+ * Create a persistent particle runtime over a mounted scene root. The caller keeps this handle
+ * and calls `reconcile()` on each re-render. Bindings
+ * are keyed by their outer node element; a binding whose `data-godot-particle-specs` is
+ * unchanged keeps its running simulation (so ambient emitters and in-flight one-shot bursts are
+ * NOT reset by an unrelated re-render), while a changed spec re-inits only that node — the seam
+ * a host uses to re-trigger a one-shot burst (bump a value in the spec). A no-op handle when
+ * WebGL2/particles are unavailable.
+ */
+declare function createParticleRuntime(root: HTMLElement, options: GodotHtmlRuntimeOptions): ParticleRuntime;
+//#endregion
+//#region src/particles/spec.d.ts
+/** HTML attribute transport: portable parameters plus DOM placement and resource URLs. */
+interface ParticleSpecConfig extends ParticleRenderConfig {
+  originX: number;
+  originY: number;
+  boxOffsetX: number;
+  boxOffsetY: number;
+  textureUrl: string | null;
+  maskUrl?: string | null;
+}
+declare function normalizeParticleSpecConfig(raw: Partial<ParticleSpecConfig> | null | undefined): ParticleSpecConfig;
+/** Decode the DOM attribute without putting its transport contract in the simulator. */
+declare function parseParticleSpecConfig(json: string | null | undefined): ParticleSpecConfig | null;
+//#endregion
+//#region src/particles/render-backend.d.ts
+/** The structural subset of a texture entry the runtime and the draw carry around: enough to size a
+ *  sprite (`width`/`height`), to know whether the real pixels have arrived (`loaded`, the frozen
+ *  frame's cache gate) and to be told when they do (`listeners`, see `onTextureLoaded`). Deliberately
+ *  NOT `TextureEntry`: the GPU resource itself is the backend's business, and a non-WebGL entry
+ *  carries no `WebGLTexture`. */
+interface ParticleTextureHandle {
+  width: number;
+  height: number;
+  loaded: boolean;
+  listeners: Set<() => void>;
+}
+//#endregion
+//#region src/particles/extents.d.ts
+declare function spriteExtentPad(cfg: ParticleSpecConfig, texture: ParticleTextureHandle | null): number;
+declare function emissionExtentPad(cfg: ParticleSpecConfig): number;
+//#endregion
+export { UnsupportedRenderReporter as $, DEFAULT_QUIET_WINDOW_MS as A, rewritePxLengths as At, StaticSurfaceEncodePacing as B, DEFAULT_ENCODE_MAX_DIM as C, GodotContentScaleSize as Ct, DEFAULT_ENCODE_SLOW_MS as D, contentScaleStageStyle as Dt, DEFAULT_ENCODE_SLOW_BACKOFF_MS as E, contentScaleScript as Et, STATIC_SURFACE_IMAGE_ATTR as F, StaticSurfaceTimerHandle as G, StaticSurfaceOption as H, StaticImageRevertCause as I, EffectsLoopPacing as J, createStaticImageSwapCounters as K, StaticImageSwapCounters as L, DEFAULT_SURFACE_WATCHDOG_MS as M, STABLE_OBSERVATIONS_BEFORE_SWAP as N, DEFAULT_ENCODE_TASK_GAP_MS as O, observeContentScale as Ot, STATIC_CAPTURE_BLANK as P, UnsupportedRenderKind as Q, StaticSurfaceCapture as R, DEFAULT_ENCODE_INTERVAL_MS as S, GodotContentScaleAspect as St, DEFAULT_ENCODE_SLICE as T, ResolvedContentScale as Tt, StaticSurfacePolicy as U, StaticSurfaceGate as V, StaticSurfaceQuietWindowGate as W, createEffectsLoopPacer as X, PARK_SLOP_S as Y, UnsupportedRenderInfo as Z, effectivePixelRatio as _, TEXT_SCALE_VAR as _t, parseParticleSpecConfig as a, GodotHtmlModel as at, GodotHtmlRuntimeOptions as b, textScaleLength as bt, ParticleRuntimeStats as c, GodotHtmlRenderOptions as ct, GpuInfo as d, GodotShaderLoadingFallback as dt, reportUnsupportedRender as et, MAX_PINNED_BACKING_DIM as f, GodotTextAutoFitDirective as ft, describeGpu as g, ResolvedTextScale as gt, backingStoreSize as h, GodotTextScaleOption as ht, normalizeParticleSpecConfig as i, GodotHtmlFontFace as it, DEFAULT_STILL_CACHE_BYTES as j, scaleStyleRecord as jt, DEFAULT_PARKED_STILL_BYTES as k, resolveContentScale as kt, createParticleRuntime as l, GodotHtmlTintFilter as lt, SURFACE_PIXEL_RATIO_ATTR as m, GodotTextScale as mt, spriteExtentPad as n, GodotEffectRenderInfo as nt, ParticleProfile as o, GodotHtmlNode as ot, MAX_SURFACE_PIXEL_RATIO as p, GodotTextAutoFitNominalMetrics as pt, EffectsLoopPacer as q, ParticleSpecConfig as r, GodotHtmlContainerLayout as rt, ParticleRuntime as s, GodotHtmlPositioning as st, emissionExtentPad as t, GodotBbcodeTagDescriptor as tt, WebgpuFallbackReason as u, GodotResolvedResource as ut, parseSurfacePixelRatio as v, resolveTextScale as vt, DEFAULT_ENCODE_PER_TASK as w, GodotContentScaleTechnique as wt, DEFAULT_ENCODE_BUSY_MAX_DEFER_MS as x, GodotContentScale as xt, GodotHtmlMountOptions as y, setGodotTextScale as yt, StaticSurfaceContentKeyGate as z };
+//# sourceMappingURL=extents-R8RIim2S.d.ts.map