supervision 0.2.0-next.0 → 0.2.0-next.2

package/dist/types/media-frame-clock.d.ts

@@ -0,0 +1,16 @@
+/** Exact presentation timing in seconds for zero-based indexed media frames. */
+export interface MediaFrameClock {
+    readonly frameCount: number;
+    readonly firstTimestamp: number;
+    /** Exclusive end of the final frame on the media timeline, in seconds. */
+    readonly endTimestamp: number;
+    /** Playable span in seconds: endTimestamp minus firstTimestamp. */
+    readonly duration: number;
+    /** Start time of a frame in presentation order. Invalid indices throw. */
+    timeAt(frameIndex: number): number;
+    /** Duration of one frame, including variable-rate and final frames. */
+    durationAt(frameIndex: number): number;
+    /** Frame covering a finite media time, clamped at the source's ends. */
+    indexAtOrBefore(mediaTime: number): number;
+}
+//# sourceMappingURL=media-frame-clock.d.ts.map

package/dist/types/media-frame-clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-frame-clock.d.ts","sourceRoot":"","sources":["../../src/types/media-frame-clock.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0EAA0E;IAC1E,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,uEAAuE;IACvE,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;IACvC,wEAAwE;IACxE,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;CAC5C"}

package/dist/types/media-frame-navigation.d.ts

@@ -0,0 +1,28 @@
+/** Exact frame identity and timing after navigation has landed. */
+export interface MediaFrameLanding {
+    readonly index: number;
+    readonly mediaTime: number;
+    readonly duration: number;
+}
+export type MediaFrameScrubSettlement = {
+    readonly status: "landed";
+    readonly frame: MediaFrameLanding;
+} | {
+    readonly status: "superseded";
+};
+export interface MediaFrameScrub {
+    readonly target: MediaFrameLanding;
+    readonly settled: Promise<MediaFrameScrubSettlement>;
+}
+/** Optional exact-frame navigation for media sources with an indexed clock. */
+export interface MediaFrameNavigation {
+    /** Move to a frame and resolve after that exact frame is presented. */
+    moveToFrame(index: number): Promise<MediaFrameLanding>;
+    /** Move to the frame covering a media time and resolve after it is presented. */
+    moveToTime(seconds: number): Promise<MediaFrameLanding>;
+    /** Start a frame scrub and observe whether it lands or is superseded. */
+    scrubToFrame(index: number): MediaFrameScrub;
+    /** Start a time scrub and observe whether it lands or is superseded. */
+    scrubToTime(seconds: number): MediaFrameScrub;
+}
+//# sourceMappingURL=media-frame-navigation.d.ts.map

package/dist/types/media-frame-navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-frame-navigation.d.ts","sourceRoot":"","sources":["../../src/types/media-frame-navigation.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,yBAAyB,GACjC;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,GAChE;IAAE,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;CAAE,CAAC;AAEtC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,yBAAyB,CAAC,CAAC;CACtD;AAED,+EAA+E;AAC/E,MAAM,WAAW,oBAAoB;IACnC,uEAAuE;IACvE,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACvD,iFAAiF;IACjF,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACxD,yEAAyE;IACzE,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAAC;IAC7C,wEAAwE;IACxE,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAAC;CAC/C"}

package/dist/types/media-renderer-display.d.ts

@@ -0,0 +1,12 @@
+/** Display geometry used to size a media source's presentation output. */
+export interface MediaRendererDisplay {
+    /** Width of the presentation box in CSS pixels. */
+    boxWidth: number;
+    /** Height of the presentation box in CSS pixels. */
+    boxHeight: number;
+    /** Pixel ratio of the display containing the presentation box. */
+    devicePixelRatio: number;
+    /** Optional ceiling on the display pixel ratio. */
+    maxDevicePixelRatio?: number;
+}
+//# sourceMappingURL=media-renderer-display.d.ts.map

package/dist/types/media-renderer-display.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-renderer-display.d.ts","sourceRoot":"","sources":["../../src/types/media-renderer-display.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,gBAAgB,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B"}

package/dist/types/media-renderer.d.ts

@@ -1,9 +1,12 @@
+import type { MediaRendererDisplay } from "#types/media-renderer-display";
 import type { DetectionBufferOptions, DetectionFrameSource, MediaFrameDiagnostics, MediaRendererDiagnosticsOptions, MediaRendererFit, MediaRendererPresentation, MediaRendererState, MediaRendererStateController, MediaSourceState } from "supervision-js-core";
 import type { PreparedAnnotationWindowSnapshot } from "#renderers/prepared-annotation-window";
 import type { DetectionFrame } from "supervision-js-core";
 import type { DetectionPickResult, DetectionSelectionOptions, MediaInteractionOptions } from "supervision-js-core";
 import type { DecodedMediaSource } from "#media/media-source";
 import type { RenderPreparationOptions } from "#types/render-preparation";
+import type { MediaFrameClock } from "#types/media-frame-clock";
+import type { MediaFrameNavigation } from "#types/media-frame-navigation";
 import type { AnnotationEditingEngine, PreviewOverlayData } from "supervision-js-core";
 import type { MaskBrushPreviewOptions } from "../editing";
 export { MediaRendererFit, MediaRendererPlaybackState, MediaSourceStatus, } from "supervision-js-core";
@@ -124,6 +127,16 @@ export interface DetectionLabelBounds {
  * preparation and detection buffering yourself.
  */
 export interface MediaRenderer extends MediaRendererStateController {
+    /** Exact frame timing when the source provides an index; null otherwise. */
+    readonly frameClock?: MediaFrameClock | null;
+    /** Indexed moves and observable scrub landings for push-based indexed sources. */
+    readonly frameNavigation?: MediaFrameNavigation | null;
+    /**
+     * Resize engine-backed display-box output without reopening the source.
+     * Resolves after the resized frame is presented; supersession rejects with AbortError.
+     * Available only on sources that support live output sizing.
+     */
+    setDisplay?(display: MediaRendererDisplay): Promise<void>;
     play(): Promise<void>;
     pause(): void;
     /**

package/dist/types/media-renderer.d.ts.map

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

package/dist/types/media-session.d.ts

@@ -1,9 +1,12 @@
+import type { MediaRendererDisplay } from "#types/media-renderer-display";
 import type { ColdDetectionFrameStore, ColdDetectionFrameStoreWriteSummary, DetectionBufferOptions, DetectionFrameLiveOptions, DetectionFrameRetentionOptions, DetectionFrameSelectionOptions, DetectionPlaybackGateOptions, DetectionFrameSource, MediaSessionLifecycleState, MediaSessionMode, MediaSessionStateListener as CoreMediaSessionStateListener, MediaSessionStateUnsubscribe, WritableDetectionFrameSource } from "supervision-js-core";
 import type { DetectionFrame } from "supervision-js-core";
 import type { MediaInteractionOptions } from "supervision-js-core";
 import type { MediaNormalizationInputMetadata, MediaNormalizationProgress, MediaNormalizationOptions, NormalizedMedia, ProgressiveNormalizedMedia } from "#types/media-normalization";
 import type { DetectionTimelineOrigin, MediaFrameCapture, MediaFrameCaptureOptions, MediaFrameDiagnostics, MediaRenderer, MediaRendererFit, MediaRendererPresentation, MediaRendererQuality, MediaRendererOptions, MediaRendererSource, MediaRendererState, MediaSourceState } from "#types/media-renderer";
 import type { RenderPreparationDiagnostics } from "#types/render-preparation";
+import type { MediaFrameClock } from "#types/media-frame-clock";
+import type { MediaFrameNavigation } from "#types/media-frame-navigation";
 export { MediaSessionActivityKind, MediaSessionActivityStatus, MediaSessionMode, MediaSessionStatus, } from "supervision-js-core";
 export type { MediaSessionActivity, MediaSessionStateUnsubscribe, } from "supervision-js-core";
 /**
@@ -124,14 +127,12 @@ export interface MediaSessionDetectionOptions {
      * session treats detection coverage as part of media readiness and reports
      * buffering while it waits. Merges over `buffer.playbackGate`.
      *
-     * The sustained wait is the renderer holding a decoded sample back, so it
-     * lasts the length of playback only when the renderer pulls samples: a URL, a
-     * `Blob`, or any `media` source without a presented-frame channel. A source
-     * that presents its own frames drives the playhead itself, which is what
-     * `createVideoEngineMediaRendererSource` returns and therefore what most
-     * video sessions actually run on. There the gate holds the start of playback
-     * and nothing after it, so a preview opens covered and a producer already
-     * running keeps its own pace.
+     * The wait lasts for the length of playback on both kinds of media source. A
+     * source the renderer pulls samples from is held between decoding and drawing
+     * a frame. A source that presents its own frames drives the playhead itself,
+     * which is what `createWebVideoEngineMediaRendererSource` returns and therefore
+     * what most video sessions run on. There the renderer stops the producer at a
+     * frame its detections do not cover and starts it again when they arrive.
      */
     readonly playbackGate?: DetectionPlaybackGateOptions;
     /**
@@ -205,8 +206,9 @@ export interface MediaSessionOptions {
     readonly detections?: MediaSessionDetectionOptions;
     /**
      * Buffered playback: hold the picture until the frame it is about to show has
-     * both its detections and its prepared annotation artifacts, so a preview
-     * opens annotated rather than opening bare and filling in.
+     * both its detections and its prepared annotation artifacts. Opening still
+     * presents an initial media frame so the session can accept future appends;
+     * these gates hold subsequent playback, not session creation.
      *
      * On by default. `false` starts playback at once and draws annotations as
      * they land, which suits a host that cares about cadence more than overlays.
@@ -218,12 +220,12 @@ export interface MediaSessionOptions {
      * since a source that is complete before playback starts has nothing to wait
      * for. `true` turns it on for any session.
      *
-     * What it holds depends on who owns the playhead. A source the renderer pulls
-     * decoded samples from is held frame by frame, for as long as playback runs.
-     * A source that presents its own frames, which is what
-     * `createVideoEngineMediaRendererSource` returns, is held at the start of
-     * playback only: the session reports buffering until the frame it will resume
-     * on is covered, and once the producer is running it paces itself.
+     * Both kinds of source are held frame by frame for as long as playback runs.
+     * A source the renderer pulls decoded samples from waits between decoding and
+     * drawing. A source that presents its own frames, which is what
+     * `createWebVideoEngineMediaRendererSource` returns, is stopped when detection
+     * coverage or prepared artifacts are missing and started again when the wait
+     * settles.
      */
     readonly playbackGate?: boolean;
     /**
@@ -277,12 +279,7 @@ export interface MediaSessionMediaState {
     readonly inputMetadata: MediaNormalizationInputMetadata | null;
     readonly normalizedMedia: NormalizedMedia | ProgressiveNormalizedMedia | null;
     readonly objectUrl: string | null;
-    /**
-     * Null until the session has prepared its media.
-     *
-     * Optional so a host holding a state it built before this field existed still
-     * satisfies the type.
-     */
+    /** Null until the session has prepared its media. */
     readonly preparation?: MediaSessionMediaPreparation | null;
 }
 export interface MediaSessionNormalizationState {
@@ -302,6 +299,12 @@ export interface MediaSessionDetectionWriteOptions {
  * Public controller for one renderer-owned media item.
  */
 export interface MediaSession {
+    /** Exact frame timing when the media source provides an index; null otherwise. */
+    readonly frameClock?: MediaFrameClock | null;
+    /** Indexed moves and observable scrub landings for push-based indexed sources. */
+    readonly frameNavigation?: MediaFrameNavigation | null;
+    /** Resize an engine-backed display-box source and await its presented output. */
+    setDisplay?(display: MediaRendererDisplay): Promise<void>;
     /**
      * Detection source used by the renderer. Present when the session was created
      * with static frames, a source, or an appendable source.
@@ -310,21 +313,22 @@ export interface MediaSession {
     readonly media: MediaSessionMediaState;
     readonly renderer: MediaRenderer;
     /**
-     * Append semantic detection frames to a session-owned appendable source.
+     * Append semantic detection frames to the selected writable source, supplied
+     * by the caller or created through `detections.appendable`.
      */
     appendDetectionFrames(frames: readonly DetectionFrame[], options?: MediaSessionDetectionWriteOptions): Promise<ColdDetectionFrameStoreWriteSummary>;
     /**
      * Optionally append the newest live detection frame.
      *
-     * Optional so controllers written against the previous shape stay
-     * assignable. `createMediaSession` always provides it; see
-     * {@link LiveMediaSession}.
+     * Live ingestion is an added capability, so a controller that does not do it
+     * still satisfies this interface. `createMediaSession` always provides it;
+     * see {@link LiveMediaSession}.
      */
     appendLiveDetectionFrame?(frame: DetectionFrame, options?: MediaSessionDetectionWriteOptions): Promise<ColdDetectionFrameStoreWriteSummary>;
     /**
      * Optionally close the appendable source's final coverage.
      *
-     * Optional for the same backward-compatibility reason as
+     * Optional for the same reason as
      * {@link MediaSession.appendLiveDetectionFrame}.
      */
     finalizeDetectionCoverage?(endTime?: number, options?: MediaSessionDetectionWriteOptions): Promise<ColdDetectionFrameStoreWriteSummary | null>;
@@ -359,14 +363,13 @@ export interface MediaSession {
 /**
  * Media session that also exposes live detection ingestion.
  *
- * `createMediaSession` returns this shape. Controllers that only satisfy the
- * historical {@link MediaSession} contract stay assignable to it, so live
- * ingestion is an added capability rather than a required one.
+ * `createMediaSession` returns this shape. The members it requires are
+ * optional on {@link MediaSession}, so live ingestion is an added capability
+ * rather than a required one.
  */
 export interface LiveMediaSession extends MediaSession {
     /**
-     * Append the newest live detection frame to a session-owned appendable
-     * source.
+     * Append the newest live detection frame to the selected writable source.
      *
      * The frame stays active until the next live frame supersedes it, which is
      * closed at the new frame's `mediaTime`. Use this for streams whose producer

package/dist/types/media-session.d.ts.map

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

package/dist/types/render-preparation.d.ts

@@ -133,37 +133,89 @@ export interface RenderPreparationMaskFrameOptions {
  * On, playback waits until the prepared window leads the playhead, so masks and
  * polygons arrive with their frame rather than after it.
  *
- * The renderer can only hold a frame it is about to draw itself, so this gate
- * reaches only a media source it pulls decoded samples from. A source that
- * presents its own frames owns the playhead and paces itself, and there this
- * gate holds the start of playback and nothing after it: the wait runs once,
- * before the producer is told to play, and the renderer reports `Buffering`
- * while it does. Once the producer is running, unprepared layers stay absent
- * until preparation catches up.
+ * A source the renderer pulls samples from is held between the sample it
+ * decoded and the draw. A source that presents its own frames owns the
+ * playhead, so it is held by stopping the producer and starting it again,
+ * before playback begins and at any frame after it whose artifacts are
+ * missing. The renderer reports `Buffering` for as long as either wait lasts.
+ *
+ * `maxWaitSeconds` bounds every one of those waits, so preparation that has
+ * stopped producing costs one wait and the frames after it are drawn without
+ * their artifacts.
  */
 export interface RenderPreparationPlaybackGateOptions {
     /**
      * Pause playback while required artifacts are unprepared. A session turns
-     * this on by default, so a preview opens with its annotations rather than
-     * opening bare; `playbackGate: false` on the session turns it off. A renderer
-     * created directly leaves it off.
+     * this on by default for playback. Its initial opening frame may appear
+     * before annotations arrive. `playbackGate: false` on the session turns it
+     * off. A renderer created directly leaves it off.
      */
     readonly enabled?: boolean;
     /**
-     * Prepared lead that is enough not to start a wait at all. Defaults to
-     * `requiredAheadSeconds` and is capped by it: playback stalls only below this
-     * lead, and a stall then clears only once the lead reaches
-     * `requiredAheadSeconds`. Setting it lower buys hysteresis, so a lead
-     * hovering at the requirement does not stutter.
+     * How long an enabled gate holds the picture for artifacts that are not
+     * prepared, before it gives up and lets the frames through without them.
+     * Defaults to two seconds, and bounds every wait the gate makes: the one
+     * before playback begins, the one that stops a running producer at a frame,
+     * and the per-sample one of a renderer that pulls its own samples. `Infinity`
+     * holds indefinitely, and `0` never holds for artifacts at all.
+     *
+     * Preparation falls behind for as long as the machine is losing, and that
+     * looks no different to the gate from a cook still on its way. A gate that
+     * gave up holds off until preparation finishes another frame, so a machine
+     * that is merely slow keeps stopping the picture and catching up, and one
+     * that has stopped producing costs one wait rather than one a frame.
+     */
+    readonly maxWaitSeconds?: number;
+    /**
+     * How long the prepared lead may fall to before playback stops, in seconds
+     * of the viewer's own time. Defaults to 0.1s. A rate multiplies it, because
+     * one wall second of runway is eight seconds of timeline at 8x, and a
+     * `requiredAheadSeconds` too small to fund the margin holds it below the lead
+     * that ends a stop rather than letting the two meet.
+     */
+    readonly stopBelowWallSeconds?: number;
+    /**
+     * How much lead a stop banks on top of `stopBelowWallSeconds` before
+     * playback resumes, in seconds of the viewer's own time. Defaults to 0.2s,
+     * so a stop lasts about as long as it takes to cook that margin and no
+     * longer. This is what sets the length of a stop; `requiredAheadSeconds`
+     * only caps it.
      */
-    readonly minimumAheadSeconds?: number;
+    readonly resumeMarginWallSeconds?: number;
     /**
-     * Prepared lead a wait in progress must reach before an enabled gate lets
-     * playback continue. Defaults to none, which asks only that the frame about
-     * to be presented is no longer pending.
+     * Ceiling on the lead the two thresholds above may ask for, in seconds of
+     * timeline. Defaults to none, which asks only that the frame about to be
+     * presented is no longer pending.
+     *
+     * This is unrelated to the detection playback gate's field of the same name,
+     * which is a minimum coverage lead.
+     *
+     * It buys no cooked frames: how far ahead preparation cooks and how much of
+     * that it keeps are the prepared window's own prefetch and cache spans, sized
+     * by the session rather than by this. The gate reads them only as a second
+     * ceiling, so a span too small to hold the lead lowers it further. All this can
+     * do is shorten a stop, by holding the resume lead below what the wall clock
+     * asked for. With the default thresholds that lead is 0.3s of timeline per
+     * unit of rate, so a ceiling only starts to bite once the rate lifts the lead
+     * above it: the 1s a session sets first does so near 3.3x.
      */
     readonly requiredAheadSeconds?: number;
 }
+/**
+ * The two lead thresholds a gate is applying right now, in seconds of
+ * timeline, which is the only unit a prepared window can compare a lead
+ * against. The wall-clock options above describe how long a viewer is left
+ * looking at a still picture; turning those into timeline needs the playback
+ * rate, so the renderer resolves them per call and the window stays blind to
+ * the rate.
+ */
+export interface ResolvedRenderPreparationGateThresholds {
+    readonly enabled?: boolean;
+    /** Lead at or above which a stop that is running ends. */
+    readonly resumeAtSeconds: number;
+    /** Lead below which playback stops. */
+    readonly stopBelowSeconds: number;
+}
 /**
  * Diagnostics for the currently selected artifact frame.
  */
@@ -242,17 +294,15 @@ export interface RenderPreparationOptions {
      * Hold playback until prepared artifacts cover the frame about to be
      * presented.
      *
-     * **This option reaches two different distances depending on the source.** A
-     * source the renderer pulls samples from is held at every frame. A source that
-     * presents its own frames is held only at the start of playback, because
-     * stopping the producer mid-run needs an answer about coverage that render
-     * preparation cannot give without waiting for it, so frames after the start
-     * arrive whether their artifacts are ready or not. `playbackGateReach` on the
-     * renderer's state reports the furthest any of its gates reaches.
+     * Both kinds of source are held at every frame: one between its decoded
+     * sample and the draw, the other by stopping the producer that owns the
+     * playhead and starting it again. `maxWaitSeconds` is what makes stopping a
+     * running producer safe, and `playbackGateReach` on the renderer's state
+     * reports the furthest any of its gates reaches.
      *
      * A renderer created directly leaves this off. `createMediaSession()` turns it
-     * on, so a session opens with its annotations rather than opening bare; pass
-     * `playbackGate: false` to the session to opt out. See
+     * on for playback; the initial opening frame does not wait for future
+     * annotations. Pass `playbackGate: false` to the session to opt out. See
      * {@link RenderPreparationPlaybackGateOptions}.
      */
     readonly playbackGate?: RenderPreparationPlaybackGateOptions;

package/dist/types/render-preparation.d.ts.map

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