@smoove/core 0.3.0 → 0.3.2

package/dist/engine/marker.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Timeline markers: lazily-resolving, immutable handles onto a scene's
+ * placement inside a marker source (`Series`, `TransitionSeries`, or a
+ * standalone `Sequence`). A marker stores no frame number — every read
+ * resolves against the source's *current* placement, so retiming a scene
+ * moves everything anchored to it.
+ *
+ * @module
+ */
+/** Resolved placement of one scene: window open/close plus the settled point. */
+export type ScenePlacement = {
+    /** Frame the scene's sequence window opens. */
+    from: number;
+    /** Frame the window closes (`from + durationInFrames`). */
+    end: number;
+    /**
+     * `from` + incoming overlap — the frame the scene is fully revealed. For
+     * `TransitionSeries` the overlap is the incoming transition's duration; for
+     * `Series` it is `max(0, −offset)`; for a standalone `Sequence` it is `0`
+     * (so `settled === from`).
+     */
+    settled: number;
+};
+/**
+ * Implemented by anything that hands out markers. `name` is `undefined` for
+ * single-scene sources (a standalone `Sequence`).
+ *
+ * @internal
+ */
+export type MarkerSource = {
+    _kmResolveMarker(name: string | undefined): ScenePlacement;
+};
+export type MarkerKind = "start" | "end" | "settled";
+/**
+ * One anchorable point of a marked scene (`start`, `end`, or `settled`),
+ * optionally shifted by an integer frame delta. Immutable: `add()` returns a
+ * new point. Accepted anywhere a {@link FrameAnchor} is.
+ */
+export declare class MarkerPoint {
+    private readonly _source;
+    private readonly _name;
+    readonly kind: MarkerKind;
+    readonly delta: number;
+    /** @internal — obtain points via `Marker#start`/`end`/`settled`. */
+    constructor(_source: MarkerSource, _name: string | undefined, kind: MarkerKind, delta: number);
+    /** A new point shifted by `n` frames (integer; deltas accumulate). */
+    add(n: number): MarkerPoint;
+    /**
+     * Resolve to a frame number **now**. Prefer passing the point itself to
+     * `from:`/`until:` — an eagerly resolved number freezes and desyncs when
+     * the timeline is retimed.
+     */
+    resolve(): number;
+}
+/**
+ * Handle onto a marked scene. Exposes the three anchorable points; using the
+ * bare `Marker` as a {@link FrameAnchor} means its `.start`.
+ */
+export declare class Marker {
+    private readonly _source;
+    private readonly _name?;
+    /** @internal — obtain via `series.marker(name)` / `sequence.marker()`. */
+    constructor(_source: MarkerSource, _name?: string | undefined);
+    /** The scene's window-open frame (under a transition: the transition begins). */
+    get start(): MarkerPoint;
+    /** The scene's window-close frame. */
+    get end(): MarkerPoint;
+    /** The frame the scene is fully revealed (start + incoming overlap). */
+    get settled(): MarkerPoint;
+    /** Sugar for `this.start.resolve()`. */
+    resolve(): number;
+}
+/** A timeline position: an absolute frame, a `Marker` (its `.start`), or a `MarkerPoint`. */
+export type FrameAnchor = number | Marker | MarkerPoint;
+/** Resolve a {@link FrameAnchor} to a frame number. @internal */
+export declare function resolveFrameAnchor(anchor: FrameAnchor): number;
+//# sourceMappingURL=marker.d.ts.map

package/dist/engine/marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker.d.ts","sourceRoot":"","sources":["../../src/engine/marker.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,iFAAiF;AACjF,MAAM,MAAM,cAAc,GAAG;IAC3B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,CAAC;CAC5D,CAAC;AAuBF,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,KAAK,GAAG,SAAS,CAAC;AAErD;;;;GAIG;AACH,qBAAa,WAAW;IAGpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,QAAQ,CAAC,IAAI,EAAE,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM;IALxB,oEAAoE;gBAEjD,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,MAAM,GAAG,SAAS,EACjC,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,MAAM;IAGxB,sEAAsE;IACtE,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,WAAW;IAO3B;;;;OAIG;IACH,OAAO,IAAI,MAAM;CAqBlB;AAED;;;GAGG;AACH,qBAAa,MAAM;IAGf,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IAHzB,0EAA0E;gBAEvD,OAAO,EAAE,YAAY,EACrB,KAAK,CAAC,EAAE,MAAM,YAAA;IAGjC,iFAAiF;IACjF,IAAI,KAAK,IAAI,WAAW,CAEvB;IAED,sCAAsC;IACtC,IAAI,GAAG,IAAI,WAAW,CAErB;IAED,wEAAwE;IACxE,IAAI,OAAO,IAAI,WAAW,CAEzB;IAED,wCAAwC;IACxC,OAAO,IAAI,MAAM;CAGlB;AAED,6FAA6F;AAC7F,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,CAAC;AAExD,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAE9D"}

package/dist/engine/marker.js

@@ -0,0 +1,107 @@
+/**
+ * Timeline markers: lazily-resolving, immutable handles onto a scene's
+ * placement inside a marker source (`Series`, `TransitionSeries`, or a
+ * standalone `Sequence`). A marker stores no frame number — every read
+ * resolves against the source's *current* placement, so retiming a scene
+ * moves everything anchored to it.
+ *
+ * @module
+ */
+// Re-entrancy guard: resolving a marker may resolve the source's `from`,
+// which may itself be a marker. A genuine loop revisits the same
+// (source, name) pair — throw instead of recursing forever.
+const resolutionStack = [];
+function resolvePlacement(source, name) {
+    for (const entry of resolutionStack) {
+        if (entry.source === source && entry.name === name) {
+            throw new Error(`marker: circular anchoring while resolving "${name ?? "(sequence)"}" — its timeline position depends on itself`);
+        }
+    }
+    resolutionStack.push({ source, name });
+    try {
+        return source._kmResolveMarker(name);
+    }
+    finally {
+        resolutionStack.pop();
+    }
+}
+/**
+ * One anchorable point of a marked scene (`start`, `end`, or `settled`),
+ * optionally shifted by an integer frame delta. Immutable: `add()` returns a
+ * new point. Accepted anywhere a {@link FrameAnchor} is.
+ */
+export class MarkerPoint {
+    _source;
+    _name;
+    kind;
+    delta;
+    /** @internal — obtain points via `Marker#start`/`end`/`settled`. */
+    constructor(_source, _name, kind, delta) {
+        this._source = _source;
+        this._name = _name;
+        this.kind = kind;
+        this.delta = delta;
+    }
+    /** A new point shifted by `n` frames (integer; deltas accumulate). */
+    add(n) {
+        if (!Number.isInteger(n)) {
+            throw new Error(`marker: add() delta must be an integer (got ${n})`);
+        }
+        return new MarkerPoint(this._source, this._name, this.kind, this.delta + n);
+    }
+    /**
+     * Resolve to a frame number **now**. Prefer passing the point itself to
+     * `from:`/`until:` — an eagerly resolved number freezes and desyncs when
+     * the timeline is retimed.
+     */
+    resolve() {
+        const placement = resolvePlacement(this._source, this._name);
+        const base = this.kind === "start"
+            ? placement.from
+            : this.kind === "end"
+                ? placement.end
+                : placement.settled;
+        if (!Number.isFinite(base)) {
+            throw new Error(`marker: cannot resolve "${this.kind}"${this._name ? ` of "${this._name}"` : ""} — the source sequence has no explicit duration and isn't attached to a composition`);
+        }
+        const frame = base + this.delta;
+        if (frame < 0) {
+            throw new Error(`marker: "${this._name ?? "(sequence)"}" ${this.kind}${this.delta ? ` ${this.delta > 0 ? "+" : ""}${this.delta}` : ""} resolves to ${frame}, before frame 0`);
+        }
+        return frame;
+    }
+}
+/**
+ * Handle onto a marked scene. Exposes the three anchorable points; using the
+ * bare `Marker` as a {@link FrameAnchor} means its `.start`.
+ */
+export class Marker {
+    _source;
+    _name;
+    /** @internal — obtain via `series.marker(name)` / `sequence.marker()`. */
+    constructor(_source, _name) {
+        this._source = _source;
+        this._name = _name;
+    }
+    /** The scene's window-open frame (under a transition: the transition begins). */
+    get start() {
+        return new MarkerPoint(this._source, this._name, "start", 0);
+    }
+    /** The scene's window-close frame. */
+    get end() {
+        return new MarkerPoint(this._source, this._name, "end", 0);
+    }
+    /** The frame the scene is fully revealed (start + incoming overlap). */
+    get settled() {
+        return new MarkerPoint(this._source, this._name, "settled", 0);
+    }
+    /** Sugar for `this.start.resolve()`. */
+    resolve() {
+        return this.start.resolve();
+    }
+}
+/** Resolve a {@link FrameAnchor} to a frame number. @internal */
+export function resolveFrameAnchor(anchor) {
+    return typeof anchor === "number" ? anchor : anchor.resolve();
+}
+//# sourceMappingURL=marker.js.map

package/dist/engine/marker.js.map

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

package/dist/engine/sequence.d.ts

@@ -1,13 +1,25 @@
 import Konva from "konva";
+import { type FrameAnchor, Marker, type MarkerSource, type ScenePlacement } from "./marker.js";
 export type SequenceOptions = Konva.LayerConfig & {
-    /** Composition frame this sequence starts on. Defaults to `0`. */
-    from?: number;
+    /**
+     * Composition frame this sequence starts on: an absolute frame, or a
+     * `Marker`/`MarkerPoint` resolved live (retiming the marked scene moves
+     * this sequence with it). Defaults to `0`.
+     */
+    from?: FrameAnchor;
     /**
      * How many frames the sequence spans. When omitted it defaults to the host
      * composition's `durationInFrames` — i.e. a layer spanning the whole comp.
      * Resolved live once added (see {@link Sequence.durationInFrames}).
+     * Mutually exclusive with {@link until}.
      */
     durationInFrames?: number;
+    /**
+     * End anchor: the span becomes `resolve(until) − resolve(from)`, kept live
+     * so retiming either end moves the window. Mutually exclusive with
+     * {@link durationInFrames}.
+     */
+    until?: FrameAnchor;
 };
 export type Updater = (localFrame: number) => void;
 /**
@@ -19,24 +31,40 @@ export type Updater = (localFrame: number) => void;
 export type SequenceProvider = {
     sequences(): Sequence[];
 };
-export declare class Sequence extends Konva.Layer {
-    readonly from: number;
-    /** Explicit span, or `undefined` to default to the host comp's duration. */
+export declare class Sequence extends Konva.Layer implements MarkerSource {
+    private readonly _from;
+    /** Explicit span, or `undefined` to default to `until`/the host comp's duration. */
     private readonly _durationInFrames?;
+    private readonly _until?;
     private readonly _updaters;
     private _active;
     private _media;
     private _lastLocal;
     constructor(opts?: SequenceOptions);
     /**
-     * Frames this sequence spans. When constructed without an explicit
-     * `durationInFrames`, this resolves **live** to the host composition's
-     * `durationInFrames` — a layer that spans the whole comp. Before the sequence
-     * is added to a composition (no reachable stage) it reports `Infinity`,
-     * meaning "unbounded"; `_apply` is only ever driven by the comp, so by then
-     * the real duration is reachable.
+     * Composition frame this sequence starts on. Marker-valued `from` resolves
+     * on every read (live, like {@link durationInFrames}), so retiming the
+     * marked scene moves this sequence automatically.
+     */
+    get from(): number;
+    /**
+     * Frames this sequence spans. With `until`, resolves live as
+     * `resolve(until) − resolve(from)`. When constructed without an explicit
+     * span, this resolves **live** to the host composition's
+     * `durationInFrames` — a layer that spans the whole comp. Before the
+     * sequence is added to a composition (no reachable stage) it reports
+     * `Infinity`, meaning "unbounded"; `_apply` is only ever driven by the
+     * comp, so by then the real duration is reachable.
      */
     get durationInFrames(): number;
+    /**
+     * A {@link Marker} onto this sequence's own placement — no name, a
+     * sequence *is* a single scene. Anchor other sequences to it:
+     * `new Sequence({ from: intro.marker().end })`.
+     */
+    marker(): Marker;
+    /** @internal marker-source hook. A plain sequence has no incoming overlap. */
+    _kmResolveMarker(): ScenePlacement;
     register(updater: Updater): () => void;
     /**
      * Internal — called by Composition on each frame change.
@@ -49,6 +77,21 @@ export declare class Sequence extends Konva.Layer {
      * nothing, or a same-frame re-entry), avoiding a wasted updater + layout + draw.
      */
     _apply(frame: number, force?: boolean): void;
+    /**
+     * Internal — the frame pass shared by {@link _apply} and `measure()`:
+     * updaters, ticks, then flex layout of every direct-child layout root. No
+     * visibility change, no draw, no `_lastLocal` bookkeeping — callers own
+     * that. With `tickMedia: false` (the measure path) media-only nodes
+     * (`MEDIA_MARK` without `TICK_MARK`) are skipped: media state never affects
+     * layout, and ticking a video at a foreign frame would trigger spurious
+     * seeks.
+     */
+    _kmRunFrame(local: number, tickMedia: boolean): void;
+    /**
+     * Internal — the live local frame while active, else `null`. `measure()`
+     * uses this to restore an active sequence after a foreign-frame pass.
+     */
+    _kmLiveLocal(): number | null;
     /**
      * Internal — force this sequence hidden and inactive, regardless of frame
      * range. Used by `Composition` while it buffers assets so the stage stays

package/dist/engine/sequence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sequence.d.ts","sourceRoot":"","sources":["../../src/engine/sequence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAK1B,MAAM,MAAM,eAAe,GAAG,KAAK,CAAC,WAAW,GAAG;IAChD,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAAE,SAAS,IAAI,QAAQ,EAAE,CAAA;CAAE,CAAC;AAQ3D,qBAAa,QAAS,SAAQ,KAAK,CAAC,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAmB;IAIjC,OAAO,CAAC,UAAU,CAAM;gBAEZ,IAAI,GAAE,eAAoB;IAkBtC;;;;;;;OAOG;IACH,IAAI,gBAAgB,IAAI,MAAM,CAK7B;IAED,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,IAAI;IAOtC;;;;;;;;;OASG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,UAAQ,GAAG,IAAI;IAsC1C;;;;;OAKG;IACH,OAAO,IAAI,IAAI;CAOhB"}
+{"version":3,"file":"sequence.d.ts","sourceRoot":"","sources":["../../src/engine/sequence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B,OAAO,EACL,KAAK,WAAW,EAChB,MAAM,EACN,KAAK,YAAY,EAEjB,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,eAAe,GAAG,KAAK,CAAC,WAAW,GAAG;IAChD;;;;OAIG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAAE,SAAS,IAAI,QAAQ,EAAE,CAAA;CAAE,CAAC;AAQ3D,qBAAa,QAAS,SAAQ,KAAK,CAAC,KAAM,YAAW,YAAY;IAC/D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,oFAAoF;IACpF,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAmB;IAIjC,OAAO,CAAC,UAAU,CAAM;gBAEZ,IAAI,GAAE,eAAoB;IAyBtC;;;;OAIG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;;;OAQG;IACH,IAAI,gBAAgB,IAAI,MAAM,CAc7B;IAED;;;;OAIG;IACH,MAAM,IAAI,MAAM;IAIhB,8EAA8E;IAC9E,gBAAgB,IAAI,cAAc;IAKlC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,IAAI;IAOtC;;;;;;;;;OASG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,UAAQ,GAAG,IAAI;IA+B1C;;;;;;;;OAQG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI;IAuBpD;;;OAGG;IACH,YAAY,IAAI,MAAM,GAAG,IAAI;IAI7B;;;;;OAKG;IACH,OAAO,IAAI,IAAI;CAOhB"}

package/dist/engine/sequence.js

@@ -2,10 +2,12 @@ import Konva from "konva";
 import { isKMLayoutRoot } from "../layout/contract.js";
 import { MEDIA_MARK, TICK_MARK } from "../markers.js";
 import { getComposition } from "./composition.js";
+import { Marker, resolveFrameAnchor, } from "./marker.js";
 export class Sequence extends Konva.Layer {
-    from;
-    /** Explicit span, or `undefined` to default to the host comp's duration. */
+    _from;
+    /** Explicit span, or `undefined` to default to `until`/the host comp's duration. */
     _durationInFrames;
+    _until;
     _updaters = new Set();
     _active = false;
     _media = [];
@@ -14,35 +16,73 @@ export class Sequence extends Konva.Layer {
     // a sentinel that never equals a real local frame, so the first apply always runs.
     _lastLocal = -1;
     constructor(opts = {}) {
-        const { from = 0, durationInFrames, ...layerOpts } = opts;
-        if (!Number.isInteger(from) || from < 0) {
+        const { from = 0, durationInFrames, until, ...layerOpts } = opts;
+        if (typeof from === "number" && (!Number.isInteger(from) || from < 0)) {
             throw new Error("Sequence: from must be a non-negative integer");
         }
+        if (durationInFrames !== undefined && until !== undefined) {
+            throw new Error("Sequence: durationInFrames and until are mutually exclusive — provide one");
+        }
         // durationInFrames is optional: when omitted it resolves to the host comp's
         // duration (see the getter). Only validate an explicitly provided value.
         if (durationInFrames !== undefined &&
             (!Number.isInteger(durationInFrames) || durationInFrames <= 0)) {
             throw new Error("Sequence: durationInFrames must be a positive integer");
         }
+        if (typeof until === "number" && (!Number.isInteger(until) || until <= 0)) {
+            throw new Error("Sequence: until must be a positive integer frame");
+        }
         super({ ...layerOpts, visible: false });
-        this.from = from;
+        this._from = from;
         this._durationInFrames = durationInFrames;
+        this._until = until;
+    }
+    /**
+     * Composition frame this sequence starts on. Marker-valued `from` resolves
+     * on every read (live, like {@link durationInFrames}), so retiming the
+     * marked scene moves this sequence automatically.
+     */
+    get from() {
+        return resolveFrameAnchor(this._from);
     }
     /**
-     * Frames this sequence spans. When constructed without an explicit
-     * `durationInFrames`, this resolves **live** to the host composition's
-     * `durationInFrames` — a layer that spans the whole comp. Before the sequence
-     * is added to a composition (no reachable stage) it reports `Infinity`,
-     * meaning "unbounded"; `_apply` is only ever driven by the comp, so by then
-     * the real duration is reachable.
+     * Frames this sequence spans. With `until`, resolves live as
+     * `resolve(until) − resolve(from)`. When constructed without an explicit
+     * span, this resolves **live** to the host composition's
+     * `durationInFrames` — a layer that spans the whole comp. Before the
+     * sequence is added to a composition (no reachable stage) it reports
+     * `Infinity`, meaning "unbounded"; `_apply` is only ever driven by the
+     * comp, so by then the real duration is reachable.
      */
     get durationInFrames() {
+        if (this._until !== undefined) {
+            const from = this.from;
+            const until = resolveFrameAnchor(this._until);
+            const d = until - from;
+            if (d <= 0) {
+                throw new Error(`Sequence: until (${until}) must be after from (${from})`);
+            }
+            return d;
+        }
         if (this._durationInFrames !== undefined)
             return this._durationInFrames;
         const stage = this.getStage();
         const comp = stage && getComposition(stage);
         return comp ? comp.durationInFrames.get() : Number.POSITIVE_INFINITY;
     }
+    /**
+     * A {@link Marker} onto this sequence's own placement — no name, a
+     * sequence *is* a single scene. Anchor other sequences to it:
+     * `new Sequence({ from: intro.marker().end })`.
+     */
+    marker() {
+        return new Marker(this);
+    }
+    /** @internal marker-source hook. A plain sequence has no incoming overlap. */
+    _kmResolveMarker() {
+        const from = this.from;
+        return { from, end: from + this.durationInFrames, settled: from };
+    }
     register(updater) {
         this._updaters.add(updater);
         return () => {
@@ -75,17 +115,7 @@ export class Sequence extends Konva.Layer {
             if (!becameActive && !force && local === this._lastLocal)
                 return;
             this._lastLocal = local;
-            for (const u of this._updaters)
-                u(local);
-            // Tick BEFORE layout: a ticked node may change its measured size (e.g. a
-            // Text typewriter revealing another line), and the flex pass must see the
-            // up-to-date size this frame rather than lagging one behind.
-            for (const v of this._media)
-                v._kmTick?.(local);
-            for (const c of this.getChildren()) {
-                if (isKMLayoutRoot(c))
-                    c._kmComputeLayout();
-            }
+            this._kmRunFrame(local, true);
             // Draw synchronously the frame in which a sequence becomes visible — this
             // ensures fresh pixels are on the canvas before the browser paints the
             // newly-displayed layer (avoids a one-frame flash of stale content).
@@ -102,6 +132,44 @@ export class Sequence extends Konva.Layer {
                 v._kmDeactivate?.();
         }
     }
+    /**
+     * Internal — the frame pass shared by {@link _apply} and `measure()`:
+     * updaters, ticks, then flex layout of every direct-child layout root. No
+     * visibility change, no draw, no `_lastLocal` bookkeeping — callers own
+     * that. With `tickMedia: false` (the measure path) media-only nodes
+     * (`MEDIA_MARK` without `TICK_MARK`) are skipped: media state never affects
+     * layout, and ticking a video at a foreign frame would trigger spurious
+     * seeks.
+     */
+    _kmRunFrame(local, tickMedia) {
+        // While inactive there is no cached tickable list (that cache is built on
+        // activation), so collect on demand.
+        const tickables = this._active
+            ? this._media
+            : this.find((n) => n.getAttr(MEDIA_MARK) === true || n.getAttr(TICK_MARK) === true);
+        for (const u of this._updaters)
+            u(local);
+        // Tick BEFORE layout: a ticked node may change its measured size (e.g. a
+        // Text typewriter revealing another line), and the flex pass must see the
+        // up-to-date size this frame rather than lagging one behind.
+        for (const v of tickables) {
+            if (!tickMedia && v.getAttr(MEDIA_MARK) === true && v.getAttr(TICK_MARK) !== true) {
+                continue;
+            }
+            v._kmTick?.(local);
+        }
+        for (const c of this.getChildren()) {
+            if (isKMLayoutRoot(c))
+                c._kmComputeLayout();
+        }
+    }
+    /**
+     * Internal — the live local frame while active, else `null`. `measure()`
+     * uses this to restore an active sequence after a foreign-frame pass.
+     */
+    _kmLiveLocal() {
+        return this._active ? this._lastLocal : null;
+    }
     /**
      * Internal — force this sequence hidden and inactive, regardless of frame
      * range. Used by `Composition` while it buffers assets so the stage stays

package/dist/engine/sequence.js.map

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

package/dist/engine/series.d.ts

@@ -1,7 +1,11 @@
+import { type FrameAnchor, Marker, type MarkerSource, type ScenePlacement } from "./marker.js";
 import { Sequence, type SequenceProvider } from "./sequence.js";
 export type SeriesOptions = {
-    /** Frame the series starts at. Default `0`. */
-    from?: number;
+    /**
+     * Frame the series starts at: an absolute frame or a `Marker`/`MarkerPoint`
+     * (e.g. another series' marker), resolved live. Default `0`.
+     */
+    from?: FrameAnchor;
 };
 export type SeriesSceneOptions = {
     durationInFrames: number;
@@ -10,6 +14,8 @@ export type SeriesSceneOptions = {
      * overlaps the previous scene; positive leaves a gap. Default `0` (back-to-back).
      */
     offset?: number;
+    /** Optional scene name for `series.marker(name)`. Unique per series. */
+    name?: string;
 };
 /**
  * Sequential sequencer: collects ordered scenes and auto-computes each
@@ -25,12 +31,22 @@ export type SeriesSceneOptions = {
  * series.durationInFrames; // total span accounting for offsets
  * ```
  */
-export declare class Series implements SequenceProvider {
-    readonly from: number;
+export declare class Series implements SequenceProvider, MarkerSource {
+    private readonly _from;
     private readonly _scenes;
     constructor(opts?: SeriesOptions);
+    /** Frame the series starts at. Marker-valued `from` resolves on every read. */
+    get from(): number;
     /** Append a scene. The `build` callback populates the created `Sequence`. */
     add(opts: SeriesSceneOptions, build: (seq: Sequence) => void): this;
+    /**
+     * A lazily-resolving {@link Marker} onto the named scene. Resolution runs
+     * this series' placement at read time, so retiming any earlier scene moves
+     * the marker — and everything anchored to it — automatically.
+     */
+    marker(name: string): Marker;
+    /** @internal marker-source hook. `settled` = start + `max(0, −offset)`. */
+    _kmResolveMarker(name: string | undefined): ScenePlacement;
     private _place;
     /** Build one `Sequence` per scene, with `from` resolved from the offsets. */
     sequences(): Sequence[];

package/dist/engine/series.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"series.d.ts","sourceRoot":"","sources":["../../src/engine/series.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEhE,MAAM,MAAM,aAAa,GAAG;IAC1B,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAOF;;;;;;;;;;;;;GAaG;AACH,qBAAa,MAAO,YAAW,gBAAgB;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;gBAE9B,IAAI,GAAE,aAAkB;IAQpC,6EAA6E;IAC7E,GAAG,CAAC,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI;IAKnE,OAAO,CAAC,MAAM;IAQd,6EAA6E;IAC7E,SAAS,IAAI,QAAQ,EAAE;IAUvB,sEAAsE;IACtE,IAAI,gBAAgB,IAAI,MAAM,CAM7B;CACF"}
+{"version":3,"file":"series.d.ts","sourceRoot":"","sources":["../../src/engine/series.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,MAAM,EACN,KAAK,YAAY,EAEjB,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,QAAQ,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEhE,MAAM,MAAM,aAAa,GAAG;IAC1B;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAOF;;;;;;;;;;;;;GAaG;AACH,qBAAa,MAAO,YAAW,gBAAgB,EAAE,YAAY;IAC3D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;gBAE9B,IAAI,GAAE,aAAkB;IAQpC,+EAA+E;IAC/E,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,6EAA6E;IAC7E,GAAG,CAAC,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI;IAQnE;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAO5B,2EAA2E;IAC3E,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc;IAqB1D,OAAO,CAAC,MAAM;IAQd,6EAA6E;IAC7E,SAAS,IAAI,QAAQ,EAAE;IAUvB,sEAAsE;IACtE,IAAI,gBAAgB,IAAI,MAAM,CAM7B;CACF"}

package/dist/engine/series.js

@@ -1,3 +1,4 @@
+import { Marker, resolveFrameAnchor, } from "./marker.js";
 import { computeOffsets } from "./offsets.js";
 import { Sequence } from "./sequence.js";
 /**
@@ -15,20 +16,58 @@ import { Sequence } from "./sequence.js";
  * ```
  */
 export class Series {
-    from;
+    _from;
     _scenes = [];
     constructor(opts = {}) {
         const from = opts.from ?? 0;
-        if (!Number.isInteger(from) || from < 0) {
+        if (typeof from === "number" && (!Number.isInteger(from) || from < 0)) {
             throw new Error("Series: from must be a non-negative integer");
         }
-        this.from = from;
+        this._from = from;
+    }
+    /** Frame the series starts at. Marker-valued `from` resolves on every read. */
+    get from() {
+        return resolveFrameAnchor(this._from);
     }
     /** Append a scene. The `build` callback populates the created `Sequence`. */
     add(opts, build) {
+        if (opts.name !== undefined && this._scenes.some((s) => s.opts.name === opts.name)) {
+            throw new Error(`Series: duplicate scene name "${opts.name}"`);
+        }
         this._scenes.push({ opts, build });
         return this;
     }
+    /**
+     * A lazily-resolving {@link Marker} onto the named scene. Resolution runs
+     * this series' placement at read time, so retiming any earlier scene moves
+     * the marker — and everything anchored to it — automatically.
+     */
+    marker(name) {
+        if (typeof name !== "string" || name.length === 0) {
+            throw new Error("Series: marker name must be a non-empty string");
+        }
+        return new Marker(this, name);
+    }
+    /** @internal marker-source hook. `settled` = start + `max(0, −offset)`. */
+    _kmResolveMarker(name) {
+        const i = this._scenes.findIndex((s) => s.opts.name === name);
+        if (name === undefined || i < 0) {
+            const names = this._scenes
+                .map((s) => s.opts.name)
+                .filter((n) => n !== undefined);
+            throw new Error(`Series: no scene named "${name}" (named scenes: ${names.length > 0 ? names.join(", ") : "none"})`);
+        }
+        const placed = this._place();
+        const p = placed[i];
+        if (!p)
+            throw new Error(`Series: scene "${name}" has no placement`);
+        const offset = this._scenes[i]?.opts.offset ?? 0;
+        return {
+            from: p.from,
+            end: p.from + p.durationInFrames,
+            settled: p.from + Math.max(0, -offset),
+        };
+    }
     _place() {
         const scenes = this._scenes.map((s) => ({
             durationInFrames: s.opts.durationInFrames,

package/dist/engine/series.js.map

@@ -1 +1 @@
-{"version":3,"file":"series.js","sourceRoot":"","sources":["../../src/engine/series.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAsC,MAAM,cAAc,CAAC;AAClF,OAAO,EAAE,QAAQ,EAAyB,MAAM,eAAe,CAAC;AAqBhE;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,MAAM;IACR,IAAI,CAAS;IACL,OAAO,GAAe,EAAE,CAAC;IAE1C,YAAY,OAAsB,EAAE;QAClC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;QAC5B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,6EAA6E;IAC7E,GAAG,CAAC,IAAwB,EAAE,KAA8B;QAC1D,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,MAAM;QACZ,MAAM,MAAM,GAAkB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACrD,gBAAgB,EAAE,CAAC,CAAC,IAAI,CAAC,gBAAgB;YACzC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM;SACtB,CAAC,CAAC,CAAC;QACJ,OAAO,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;IAClD,CAAC;IAED,6EAA6E;IAC7E,SAAS;QACP,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAC7B,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YACzB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YAC5B,MAAM,GAAG,GAAG,IAAI,QAAQ,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,gBAAgB,EAAE,CAAC,CAAC,gBAAgB,EAAE,CAAC,CAAC;YACjF,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;YAChB,OAAO,GAAG,CAAC;QACb,CAAC,CAAC,CAAC;IACL,CAAC;IAED,sEAAsE;IACtE,IAAI,gBAAgB;QAClB,MAAM,MAAM,GAAkB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACrD,gBAAgB,EAAE,CAAC,CAAC,IAAI,CAAC,gBAAgB;YACzC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM;SACtB,CAAC,CAAC,CAAC;QACJ,OAAO,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,gBAAgB,CAAC;IAC5D,CAAC;CACF"}
+{"version":3,"file":"series.js","sourceRoot":"","sources":["../../src/engine/series.ts"],"names":[],"mappings":"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"}