aigpu 0.3.1

package/dist/frame-protocols.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Nominal protocols a `Frame` talks to, so `frame.ts` never imports a feature module.
+ *
+ * `frame(gpu, cb)` must not drag draw, effect, bundle, timer or visibility into a program that
+ * does not use them: a frame that only clears a surface pays for a command encoder, nothing else.
+ * Concrete classes therefore expose a symbol-keyed protocol object, and the frame resolves it
+ * through the `*Of()` accessors below.
+ *
+ * Rules for this file:
+ * - **Nominal, not duck typing.** The symbols are module-private to the package (never exported
+ *   from an entrypoint), so only code that imported this module can implement a protocol. A plain
+ *   object literal from user code can never be mistaken for a drawable or a telemetry owner.
+ * - **No registration by side effect.** Nothing self-registers at import time; the object carries
+ *   its own protocol, so tree shaking still sees an unused feature as unused.
+ * - **Types only.** This module has no runtime dependency of its own (the symbols aside), so
+ *   importing it from a feature costs nothing.
+ */
+import type { Device } from "@aigpu/core";
+import type { ClaimedGroupValidationResult } from "./claim-validation.ts";
+import type { DrawCallOptions } from "./draw.ts";
+import type { Target } from "./target.ts";
+/**
+ * Identity of the frame a protocol call belongs to. Owners key their per-frame bookkeeping on it
+ * and never inspect it, so the concrete `Frame` class stays private to `frame.ts`.
+ */
+export type FrameHandle = object;
+export declare const FRAME_DRAWABLE: unique symbol;
+export interface FrameDrawableProtocol {
+    /** Used by pass-level error messages (read-only depth rejections name the offending draw). */
+    readonly label: string;
+    encode(pass: GPURenderPassEncoder, target: Target, opts: DrawCallOptions, claimValidation?: (result: ClaimedGroupValidationResult) => void): void;
+    /** True when the drawable's depth state writes depth — rejected by a `depthReadOnly` pass. */
+    writesDepth(): boolean;
+    /** Names of the stencil ops that can write, empty when none — rejected by a `depthReadOnly` pass on a stencil format. */
+    stencilWritingOps(): readonly string[];
+}
+export interface FrameDrawable {
+    readonly [FRAME_DRAWABLE]: FrameDrawableProtocol;
+}
+export declare function frameDrawableOf(value: unknown): FrameDrawableProtocol | undefined;
+export declare const FRAME_BUNDLE: unique symbol;
+export interface FrameBundleProtocol {
+    readonly gpu: GPURenderBundle;
+    /** Throws `AIGPU-R3-BUNDLE-STALE` when the recorded signature no longer matches `target`. */
+    assertReplayable(target: Target): void;
+}
+export interface FrameBundleLike {
+    readonly [FRAME_BUNDLE]: FrameBundleProtocol;
+}
+export declare function frameBundleOf(value: unknown): FrameBundleProtocol | undefined;
+/**
+ * Per-frame lifecycle of anything a pass attached: query rings today, scene view generations later.
+ *
+ * Exactly one of `frameSubmitted` / `frameAbandoned` runs per frame the owner was attached to.
+ * The frame calls `finalizeFrame` only on owners that survived every pass, right before
+ * `encoder.finish()`, and `frameAbandoned` on the rest (failed pass, failed finish/submit, cancel)
+ * so the retain each owner took at attach time is always released exactly once.
+ */
+export interface FrameOwner {
+    /** Encodes the owner's end-of-frame work (resolve + staging copy) into the frame's still-open encoder. */
+    finalizeFrame(frame: FrameHandle, encoder: GPUCommandEncoder): void;
+    /** The frame reached the queue: start the readback of what this frame encoded. */
+    frameSubmitted(frame: FrameHandle): void;
+    /** The frame never reached the queue: drop this frame's pending state and release the retain. */
+    frameAbandoned(frame: FrameHandle): void;
+}
+export declare const FRAME_PASS_ATTACHMENT: unique symbol;
+export interface FramePassAttachContext {
+    /** Identity of the frame being encoded. */
+    readonly frame: FrameHandle;
+    /** The device the frame encodes against; attachments validate their own device against it. */
+    readonly device: Device;
+    /** The pass's resolved target, for attachments that require specific attachments (occlusion needs depth). */
+    readonly target: Target;
+}
+/** Occlusion query source of a pass: supplied by the attachment, consumed by `FramePass.occlusion()`. */
+export interface FrameOcclusionSource {
+    readonly querySet: GPUQuerySet;
+    /**
+     * Reserves the query index for `query` in this frame. Throws on an unknown/disposed handle.
+     * `frame` is optional because a pass can be encoded outside a frame (tests drive `FramePass`
+     * directly); the attachment then has no frame to bill the slot to.
+     */
+    beginQuery(query: object, frame?: FrameHandle): number;
+}
+/**
+ * What attaching contributed to the pass. `owner` is bookkeeping-only; the optional members
+ * decorate the render pass descriptor the frame is about to open.
+ */
+export interface FramePassAttachResult {
+    readonly owner: FrameOwner;
+    readonly timestampWrites?: GPURenderPassTimestampWrites;
+    readonly occlusion?: FrameOcclusionSource;
+}
+/**
+ * Implemented by the value a user hands to a `FramePassOptions` telemetry slot: `timer.span(name)`
+ * for `timer`, the instance itself for `visibility`.
+ *
+ * `attach` may throw (invalid handle, duplicate span, missing depth attachment): the frame treats a
+ * throw as a failed pass and rolls the owner's frame bookkeeping back, including any earlier pass
+ * of the same frame that the same owner contributed.
+ */
+export interface FramePassAttachment {
+    [FRAME_PASS_ATTACHMENT](ctx: FramePassAttachContext): FramePassAttachResult;
+}
+export declare function framePassAttachmentOf(value: unknown): FramePassAttachment | undefined;
+//# sourceMappingURL=frame-protocols.d.ts.map

package/dist/frame-protocols.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-protocols.d.ts","sourceRoot":"","sources":["../src/frame-protocols.ts"],"names":[],"mappings":"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"}

package/dist/frame-protocols.js

@@ -0,0 +1,20 @@
+// ---------------------------------------------------------------------------
+// Drawable: what `FramePass.draw()` encodes (draw.ts, effect.ts, later scene views).
+// ---------------------------------------------------------------------------
+export const FRAME_DRAWABLE = Symbol("aigpu.frame.drawable");
+export function frameDrawableOf(value) {
+    return value?.[FRAME_DRAWABLE];
+}
+// ---------------------------------------------------------------------------
+// Bundle: what `FramePass.bundles()` replays (bundle.ts).
+// ---------------------------------------------------------------------------
+export const FRAME_BUNDLE = Symbol("aigpu.frame.bundle");
+export function frameBundleOf(value) {
+    return value?.[FRAME_BUNDLE];
+}
+export const FRAME_PASS_ATTACHMENT = Symbol("aigpu.frame.passAttachment");
+export function framePassAttachmentOf(value) {
+    const attach = value?.[FRAME_PASS_ATTACHMENT];
+    return typeof attach === "function" ? value : undefined;
+}
+//# sourceMappingURL=frame-protocols.js.map

package/dist/frame-protocols.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-protocols.js","sourceRoot":"","sources":["../src/frame-protocols.ts"],"names":[],"mappings":"AA4BA,8EAA8E;AAC9E,qFAAqF;AACrF,8EAA8E;AAE9E,MAAM,CAAC,MAAM,cAAc,GAAkB,MAAM,CAAC,sBAAsB,CAAC,CAAC;AAgB5E,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAQ,KAAmD,EAAE,CAAC,cAAc,CAAC,CAAC;AAChF,CAAC;AAED,8EAA8E;AAC9E,0DAA0D;AAC1D,8EAA8E;AAE9E,MAAM,CAAC,MAAM,YAAY,GAAkB,MAAM,CAAC,oBAAoB,CAAC,CAAC;AAYxE,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAQ,KAAqD,EAAE,CAAC,YAAY,CAAC,CAAC;AAChF,CAAC;AAuBD,MAAM,CAAC,MAAM,qBAAqB,GAAkB,MAAM,CAAC,4BAA4B,CAAC,CAAC;AA4CzF,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,MAAM,MAAM,GAAI,KAAyD,EAAE,CAAC,qBAAqB,CAAC,CAAC;IACnG,OAAO,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAE,KAA6B,CAAC,CAAC,CAAC,SAAS,CAAC;AACnF,CAAC"}

package/dist/frame-state.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Per-frame clock, as a lazy kernel service.
+ *
+ * This is the small "frame state" the core deliberately does not carry as public fields:
+ * a program that never opens a frame never creates it. Registered through a token so the
+ * kernel keeps no static reference to it. The public face of this service is `clock(gpu)`.
+ */
+import { type Kernel } from "./kernel.ts";
+export interface FrameState {
+    /** Seconds since the first frame. */
+    time: number;
+    /** Seconds between the last two ticks. */
+    deltaTime: number;
+    frameCount: number;
+    /**
+     * Advances the clock by `dtSeconds` right now and claims this frame's tick: the next `tick()`
+     * counts the frame and runs the hooks, but does not move the clock again.
+     */
+    advanceBy(dtSeconds: number): void;
+    /**
+     * Counts one frame and runs the registered per-frame hooks, advancing the clock with wall-clock
+     * time unless `advanceBy()` already advanced it since the last tick. Throws `AIGPU-FRAME-REENTRANT`
+     * if re-entered.
+     */
+    tick(): void;
+    /** Runs right after the clock advances, before the frame callback (surface auto-resize lives here). */
+    onAdvance(hook: () => void): () => void;
+}
+export declare const frameStateToken: import("./kernel.ts").ServiceToken<FrameState>;
+/** Lazily creates the frame state of this kernel; repeated calls return the same instance. */
+export declare function frameState(kernel: Kernel): FrameState;
+//# sourceMappingURL=frame-state.d.ts.map

package/dist/frame-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-state.d.ts","sourceRoot":"","sources":["../src/frame-state.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAGxD,MAAM,WAAW,UAAU;IACzB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC;;;;OAIG;IACH,IAAI,IAAI,IAAI,CAAC;IACb,uGAAuG;IACvG,SAAS,CAAC,IAAI,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CACzC;AAED,eAAO,MAAM,eAAe,gDAA0C,CAAC;AAEvE,8FAA8F;AAC9F,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAErD"}

package/dist/frame-state.js

@@ -0,0 +1,62 @@
+/**
+ * Per-frame clock, as a lazy kernel service.
+ *
+ * This is the small "frame state" the core deliberately does not carry as public fields:
+ * a program that never opens a frame never creates it. Registered through a token so the
+ * kernel keeps no static reference to it. The public face of this service is `clock(gpu)`.
+ */
+import { serviceToken } from "./kernel.js";
+import { frameReentrantError } from "./errors.js";
+export const frameStateToken = serviceToken("frame-state");
+/** Lazily creates the frame state of this kernel; repeated calls return the same instance. */
+export function frameState(kernel) {
+    return kernel.service(frameStateToken, createFrameState);
+}
+function createFrameState() {
+    const hooks = new Set();
+    let lastTimeMs = nowMs();
+    let ticking = false;
+    // True while a manual advance() owns this frame's tick: one advance per frame, manual wins.
+    let manualPending = false;
+    const state = {
+        time: 0,
+        deltaTime: 0,
+        frameCount: 0,
+        advanceBy(dtSeconds) {
+            state.deltaTime = dtSeconds;
+            state.time += dtSeconds;
+            manualPending = true;
+        },
+        tick() {
+            if (ticking)
+                throw frameReentrantError();
+            ticking = true;
+            try {
+                const next = nowMs();
+                if (manualPending) {
+                    // The clock already moved this frame; only re-base the wall clock so the next
+                    // auto-advanced frame measures from this tick, not from the last automatic one.
+                    manualPending = false;
+                }
+                else {
+                    state.deltaTime = Math.max(0, (next - lastTimeMs) / 1000);
+                    state.time += state.deltaTime;
+                }
+                lastTimeMs = next;
+                state.frameCount += 1;
+                for (const hook of [...hooks])
+                    hook();
+            }
+            finally {
+                ticking = false;
+            }
+        },
+        onAdvance(hook) {
+            hooks.add(hook);
+            return () => { hooks.delete(hook); };
+        },
+    };
+    return state;
+}
+function nowMs() { return globalThis.performance?.now?.() ?? Date.now(); }
+//# sourceMappingURL=frame-state.js.map

package/dist/frame-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-state.js","sourceRoot":"","sources":["../src/frame-state.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,YAAY,EAAe,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAuBlD,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,CAAa,aAAa,CAAC,CAAC;AAEvE,8FAA8F;AAC9F,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,OAAO,MAAM,CAAC,OAAO,CAAC,eAAe,EAAE,gBAAgB,CAAC,CAAC;AAC3D,CAAC;AAED,SAAS,gBAAgB;IACvB,MAAM,KAAK,GAAG,IAAI,GAAG,EAAc,CAAC;IACpC,IAAI,UAAU,GAAG,KAAK,EAAE,CAAC;IACzB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,4FAA4F;IAC5F,IAAI,aAAa,GAAG,KAAK,CAAC;IAC1B,MAAM,KAAK,GAAe;QACxB,IAAI,EAAE,CAAC;QACP,SAAS,EAAE,CAAC;QACZ,UAAU,EAAE,CAAC;QACb,SAAS,CAAC,SAAiB;YACzB,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC;YAC5B,KAAK,CAAC,IAAI,IAAI,SAAS,CAAC;YACxB,aAAa,GAAG,IAAI,CAAC;QACvB,CAAC;QACD,IAAI;YACF,IAAI,OAAO;gBAAE,MAAM,mBAAmB,EAAE,CAAC;YACzC,OAAO,GAAG,IAAI,CAAC;YACf,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,KAAK,EAAE,CAAC;gBACrB,IAAI,aAAa,EAAE,CAAC;oBAClB,8EAA8E;oBAC9E,gFAAgF;oBAChF,aAAa,GAAG,KAAK,CAAC;gBACxB,CAAC;qBAAM,CAAC;oBACN,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,IAAI,GAAG,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC;oBAC1D,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC;gBAChC,CAAC;gBACD,UAAU,GAAG,IAAI,CAAC;gBAClB,KAAK,CAAC,UAAU,IAAI,CAAC,CAAC;gBACtB,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,KAAK,CAAC;oBAAE,IAAI,EAAE,CAAC;YACxC,CAAC;oBAAS,CAAC;gBACT,OAAO,GAAG,KAAK,CAAC;YAClB,CAAC;QACH,CAAC;QACD,SAAS,CAAC,IAAgB;YACxB,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAChB,OAAO,GAAG,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACvC,CAAC;KACF,CAAC;IACF,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,KAAK,KAAa,OAAO,UAAU,CAAC,WAAW,EAAE,GAAG,EAAE,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC"}

package/dist/frame.d.ts

@@ -0,0 +1,127 @@
+import type { Device } from "@aigpu/core";
+import { type ClaimedGroupValidationResult, type ValidationErrorSink } from "./claim-validation.ts";
+import type { Bundle } from "./bundle.ts";
+import type { Draw, DrawCallOptions } from "./draw.ts";
+import type { Effect } from "./effect.ts";
+import type { Target } from "./target.ts";
+import { type ClearColor } from "./target-utils.ts";
+import type { TimerSpan } from "./timer.ts";
+import type { Visibility, VisibilityQuery } from "./visibility.ts";
+import { type FrameOcclusionSource } from "./frame-protocols.ts";
+import { type Gpu } from "./kernel.ts";
+/**
+ * Opens a frame on `gpu`: advances the frame clock, runs `cb` against a fresh command encoder and
+ * submits it when the callback returns (or on the way out of a throw).
+ *
+ * Without a callback the frame is yours: encode passes at your own pace and finish it with
+ * `frame.submit()` or `frame.cancel()` — an unfinished frame holds every retain its passes took.
+ * Frames are not reentrant: opening one from inside another (or from a surface resize callback)
+ * throws `AIGPU-FRAME-REENTRANT`.
+ */
+export declare function frame(gpu: Gpu, cb?: (frame: Frame) => void): Frame;
+/**
+ * Runs `cb` once per animation frame until the returned handle is stopped.
+ *
+ * The loop belongs to the gpu's `scheduler` phase, so `gpu.dispose()` stops it before anything it
+ * could encode against is torn down; a loop that stops on its own drops that registration.
+ */
+export declare function frameLoop(gpu: Gpu, cb: FrameLoopCallback, opts?: FrameLoopOptions): FrameLoopHandle;
+export interface FramePassOptions {
+    readonly target: Target;
+    /** Omit or pass true to clear with `target.clearColor`; pass false to preserve color/depth; pass a color to clear this pass with it. */
+    readonly clear?: boolean | ClearColor;
+    /** Depth clear value used when the pass clears. Defaults to 1. Use 0 with depth: { compare: "greater" } for reversed-Z. */
+    readonly clearDepth?: number;
+    /** Stencil clear value used when the pass clears. Defaults to 0. Requires a depth format with a stencil aspect. */
+    readonly clearStencil?: number;
+    /** Opens the pass with a read-only depth attachment: depth can be tested against and sampled as a texture in the same pass, but not written. For combined depth-stencil formats the stencil aspect is read-only too. Defaults to false. */
+    readonly depthReadOnly?: boolean;
+    /** Viewport for every draw in this pass. Defaults to the full target. */
+    readonly viewport?: {
+        readonly x?: number;
+        readonly y?: number;
+        readonly width: number;
+        readonly height: number;
+        readonly minDepth?: number;
+        readonly maxDepth?: number;
+    };
+    /** Scissor rectangle [x, y, width, height] for every draw in this pass. Integers. Note: does not affect the clear — loadOp "clear" always clears the full attachment. */
+    readonly scissor?: readonly [number, number, number, number];
+    /** Times this pass on the GPU: pass `timer.span(name)` from a `timer(gpu)`. The pass duration lands in `timer.onResults` under `name`, in milliseconds. One span name per frame. */
+    readonly timer?: TimerSpan;
+    /** Enables occlusion queries in this pass: pass a `visibility(gpu)` instance, then wrap proxy draws in `pass.occlusion(handle, body)`. Requires a target with a depth attachment. */
+    readonly visibility?: Visibility;
+}
+export interface FrameLoopHandle {
+    stop(): void;
+}
+export interface FrameLoopOptions {
+    readonly fps?: number;
+}
+export type FrameLoopCallback = (frame: Frame) => void;
+export declare class Frame {
+    #private;
+    private readonly device;
+    private readonly defaultTarget?;
+    private readonly errorSink?;
+    private readonly trackSettled?;
+    private readonly releaseLifecycle?;
+    /**
+     * Resolves after submitted GPU work completes and raw claimed-bind-group
+     * validation has been delivered to `gpu.onError`.
+     *
+     * This is a completion/timing signal only; it never rejects and is not an error
+     * channel.
+     */
+    done: Promise<void>;
+    constructor(device: Device, defaultTarget?: Target | undefined, errorSink?: ValidationErrorSink | undefined, trackSettled?: ((promise: Promise<unknown>) => void) | undefined, releaseLifecycle?: (() => void) | undefined);
+    pass(target: Target, body: Effect | Draw | ((pass: FramePass) => void)): void;
+    pass(options: FramePassOptions, body: Effect | Draw | ((pass: FramePass) => void)): void;
+    submit(): void;
+    /**
+     * Discards the frame without submitting it: the command encoder is dropped (nothing this frame
+     * encoded ever runs) and every telemetry instance it attached releases the retain it took on its
+     * query ring, so a `timer(gpu)` / `visibility(gpu)` can be disposed for good without waiting for
+     * `gpu.dispose()`. This is the explicit way out of the leak a manual `frame(gpu)` would otherwise
+     * hold: a frame is never assumed abandoned, because an old frame can still be submitted.
+     *
+     * Idempotent, like `submit()`: cancelling twice is a no-op, and `submit()` after `cancel()` does
+     * nothing. Cancelling a frame that was already submitted throws `AIGPU-FRAME-SUBMITTED` — its work
+     * is on the queue and cannot be taken back, so silently accepting the call would hide a real
+     * lifecycle bug.
+     */
+    cancel(): void;
+}
+export declare class FramePass {
+    #private;
+    private readonly encoder;
+    readonly target: Target;
+    private readonly validations;
+    private readonly depthReadOnly;
+    private readonly occlusionSource?;
+    private readonly frame?;
+    private readonly assertFrameOpen?;
+    constructor(encoder: GPURenderPassEncoder, target: Target, validations: ClaimedGroupValidationResult[], depthReadOnly?: boolean, occlusionSource?: FrameOcclusionSource | undefined, frame?: Frame | undefined, assertFrameOpen?: ((where: string) => void) | undefined);
+    draw(drawable: Draw | Effect, opts?: DrawCallOptions): void;
+    /**
+     * Wraps one or more draws in begin/endOcclusionQuery. The body ALWAYS executes; condition your
+     * real draws on `q.hidden` outside.
+     */
+    occlusion(query: VisibilityQuery, body: Draw | Effect | (() => void)): void;
+    bundles(...bundles: readonly Bundle[]): void;
+}
+export declare class FrameRunner {
+    #private;
+    private readonly createFrame;
+    private readonly advance;
+    private readonly trackLoop?;
+    /**
+     * @param trackLoop Lifecycle hook for the owning gpu: called with each started loop handle and
+     * returns the untrack function the handle runs when it stops on its own, so `gpu.dispose()` can
+     * stop the loops still running without holding on to the ones already stopped.
+     */
+    constructor(createFrame: () => Frame, advance: () => void, trackLoop?: ((handle: FrameLoopHandle) => () => void) | undefined);
+    frame(cb?: (frame: Frame) => void): Frame;
+    loop(cb: FrameLoopCallback, opts?: FrameLoopOptions): FrameLoopHandle;
+}
+//# sourceMappingURL=frame.d.ts.map

package/dist/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../src/frame.ts"],"names":[],"mappings":"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"}