cursedbelt-core 2.14.1 → 2.15.0

package/dist/core/media/playbackEdits.d.ts

@@ -0,0 +1,96 @@
+/**
+ * SAVED PLAYBACK EDITS — skips, and the framing a video plays with, saved beside it and applied
+ * while it plays. Not one byte of the stored file changes.
+ *
+ * The owner, 2026-11-07: *"allow marking center points on the video player at different times so
+ * I can play the video zoomed in … It should not actually alter the stored video. It should be
+ * able to be toggled off"*, then *"Can we add a trim capability with this feature, where it
+ * remembers jump points to go to and skips the points in between. Then later I can have it do the
+ * real trim if I want to."*
+ *
+ * ── One model, read by the editor, the server and the trim drain ──────────────────────────
+ * The server refuses what {@link normalizePlayback} refuses and stores what it returns, the
+ * editor saves through the same function, and the real trim's copy inherits its original's edits
+ * through {@link remapPlayback}. Three readers of one shape is why the shape lives here, beside
+ * the cut model, and not in any one of them.
+ *
+ * 🔴 **Skips ARE trim marks.** A skip is a {@link VideoCut}: the same `[start, end)` span the trim
+ * editor marks and binary-server removes, normalized by the same {@link normalizeCuts}. There is
+ * no second cut model, so "Make trimmed file…" sends exactly what is already playing.
+ *
+ * ── Framing: two lanes on one list of keys ─────────────────────────────────────────────────
+ * A key may set a center, a zoom, or both. Each LANE (center, zoom) is read only from the keys
+ * that set it, so a zoom key never moves the center and a center key never changes the zoom.
+ * `toNext` says how a key reaches the next key of the same lane: `hold` keeps its value until
+ * then, `glide` moves over the span — center linearly, zoom geometrically (a 1×→4× glide passes
+ * 2× halfway, which is what the eye reads as even). Before a lane's first key its first value
+ * holds; after its last key its last value holds.
+ */
+import { type VideoCut } from './videoCuts.js';
+export type FramingMode = 'hold' | 'glide';
+/** A point of the SOURCE frame, 0–1 from its top-left (as `videoRegion`'s `Region`). */
+export interface FramingPoint {
+    x: number;
+    y: number;
+}
+export interface FramingKey {
+    /** Seconds into the source. */
+    t: number;
+    center?: FramingPoint;
+    /** Magnification, 1 = the whole frame. */
+    zoom?: number;
+    toNext: FramingMode;
+}
+export interface FramingTrack {
+    /** Whole-video zoom, used when no key sets the zoom lane. 1 = none. */
+    baseZoom: number;
+    keys: FramingKey[];
+}
+export interface PlaybackEdits {
+    framing?: FramingTrack;
+    /** Spans playback jumps over — the trim editor's marks. */
+    skips?: VideoCut[];
+}
+/** The most a saved zoom may magnify — cursedbelt's `MAX_ZOOM` (its spec holds the two equal). */
+export declare const PLAYBACK_MAX_ZOOM = 20;
+export declare const MAX_FRAMING_KEYS = 500;
+export declare const MAX_SKIPS = 200;
+/** Nothing saved — the row is deleted and the item carries no `playback`. */
+export declare const isEmptyPlayback: (p: PlaybackEdits | null | undefined) => boolean;
+/**
+ * The ONE gate every writer passes: the server before it stores, the editor before it saves.
+ * Out-of-range values are CLAMPED (a center dragged a pixel past the edge is still the edge),
+ * keys past the end are dropped, and only what cannot be meant is refused: not an object, too
+ * many keys or skips, or skips that remove the whole video.
+ *
+ * `duration` null means the length is not known: framing still saves, skips are refused —
+ * a span cannot be placed in a video of unknown length.
+ */
+export declare function normalizePlayback(raw: unknown, duration: number | null): {
+    playback: PlaybackEdits;
+} | {
+    error: string;
+};
+/**
+ * Where playback must be instead of `t`: the end of the skip `t` is inside, or `null` when `t`
+ * plays. Half-open, as every cut: `start` jumps, `end` plays. `skips` must be normalized
+ * (sorted, merged), which is what {@link normalizePlayback} stores.
+ */
+export declare function skipTarget(skips: readonly VideoCut[] | undefined, t: number): number | null;
+/** How long the video plays with its skips — the length a tile shows beside its scissors. */
+export declare function playedSeconds(playback: PlaybackEdits | null | undefined, duration: number): number;
+/** The center lane's value at `t`, or `null` when no key sets a center. */
+export declare function centerAt(track: FramingTrack | null | undefined, t: number): FramingPoint | null;
+/** The zoom lane's value at `t` — `baseZoom` when no key sets a zoom. */
+export declare function zoomAt(track: FramingTrack | null | undefined, t: number): number;
+/**
+ * The original's edits, moved onto the trimmed copy. `removed` is what the file was CUT BY — the
+ * edit row's stored cuts, never the video's current skips, which may have changed since.
+ *
+ *  · A time after a removed span moves back by the removed time before it.
+ *  · A skip loses the parts the cut removed; the rest moves back. A skip the cut removed is gone.
+ *  · A framing key inside a removed span is dropped, and at each cut boundary a key carrying the
+ *    values in effect at the span's END is inserted, so the copy resumes framed exactly as the
+ *    original did after the same cut (no jump the original did not have).
+ */
+export declare function remapPlayback(playback: PlaybackEdits | null | undefined, removed: readonly VideoCut[], duration: number): PlaybackEdits;

package/dist/core/media/playbackEdits.js

@@ -0,0 +1,236 @@
+/**
+ * SAVED PLAYBACK EDITS — skips, and the framing a video plays with, saved beside it and applied
+ * while it plays. Not one byte of the stored file changes.
+ *
+ * The owner, 2026-11-07: *"allow marking center points on the video player at different times so
+ * I can play the video zoomed in … It should not actually alter the stored video. It should be
+ * able to be toggled off"*, then *"Can we add a trim capability with this feature, where it
+ * remembers jump points to go to and skips the points in between. Then later I can have it do the
+ * real trim if I want to."*
+ *
+ * ── One model, read by the editor, the server and the trim drain ──────────────────────────
+ * The server refuses what {@link normalizePlayback} refuses and stores what it returns, the
+ * editor saves through the same function, and the real trim's copy inherits its original's edits
+ * through {@link remapPlayback}. Three readers of one shape is why the shape lives here, beside
+ * the cut model, and not in any one of them.
+ *
+ * 🔴 **Skips ARE trim marks.** A skip is a {@link VideoCut}: the same `[start, end)` span the trim
+ * editor marks and binary-server removes, normalized by the same {@link normalizeCuts}. There is
+ * no second cut model, so "Make trimmed file…" sends exactly what is already playing.
+ *
+ * ── Framing: two lanes on one list of keys ─────────────────────────────────────────────────
+ * A key may set a center, a zoom, or both. Each LANE (center, zoom) is read only from the keys
+ * that set it, so a zoom key never moves the center and a center key never changes the zoom.
+ * `toNext` says how a key reaches the next key of the same lane: `hold` keeps its value until
+ * then, `glide` moves over the span — center linearly, zoom geometrically (a 1×→4× glide passes
+ * 2× halfway, which is what the eye reads as even). Before a lane's first key its first value
+ * holds; after its last key its last value holds.
+ */
+import { MIN_CUT_SECONDS, normalizeCuts, keptSegments, cutSeconds } from './videoCuts.js';
+/** The most a saved zoom may magnify — cursedbelt's `MAX_ZOOM` (its spec holds the two equal). */
+export const PLAYBACK_MAX_ZOOM = 20;
+export const MAX_FRAMING_KEYS = 500;
+export const MAX_SKIPS = 200;
+/** Two keys closer than this are one moment — the later write wins. */
+const SAME_MOMENT = 1e-3;
+const finite = (v) => typeof v === 'number' && Number.isFinite(v);
+const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** Nothing saved — the row is deleted and the item carries no `playback`. */
+export const isEmptyPlayback = (p) => !p || ((!p.framing || (p.framing.baseZoom === 1 && p.framing.keys.length === 0)) && (!p.skips || p.skips.length === 0));
+function cleanKey(raw, duration) {
+    if (!isObject(raw) || !finite(raw.t) || raw.t < 0)
+        return null;
+    if (duration !== null && raw.t > duration)
+        return null;
+    const key = { t: raw.t, toNext: raw.toNext === 'glide' ? 'glide' : 'hold' };
+    if (isObject(raw.center) && finite(raw.center.x) && finite(raw.center.y))
+        key.center = { x: clamp(raw.center.x, 0, 1), y: clamp(raw.center.y, 0, 1) };
+    if (finite(raw.zoom))
+        key.zoom = clamp(raw.zoom, 1, PLAYBACK_MAX_ZOOM);
+    return key.center || key.zoom !== undefined ? key : null;
+}
+/** Sorted by time; keys at one moment merge, the later in the list winning each lane. */
+function tidyKeys(keys) {
+    const sorted = keys.map((k, i) => ({ k, i })).sort((a, b) => a.k.t - b.k.t || a.i - b.i);
+    const out = [];
+    for (const { k } of sorted) {
+        const last = out[out.length - 1];
+        if (last && k.t - last.t < SAME_MOMENT) {
+            const merged = { ...last, toNext: k.toNext };
+            if (k.center)
+                merged.center = k.center;
+            if (k.zoom !== undefined)
+                merged.zoom = k.zoom;
+            out[out.length - 1] = merged;
+        }
+        else
+            out.push({ ...k });
+    }
+    return out;
+}
+/**
+ * The ONE gate every writer passes: the server before it stores, the editor before it saves.
+ * Out-of-range values are CLAMPED (a center dragged a pixel past the edge is still the edge),
+ * keys past the end are dropped, and only what cannot be meant is refused: not an object, too
+ * many keys or skips, or skips that remove the whole video.
+ *
+ * `duration` null means the length is not known: framing still saves, skips are refused —
+ * a span cannot be placed in a video of unknown length.
+ */
+export function normalizePlayback(raw, duration) {
+    if (!isObject(raw))
+        return { error: 'Expected an object of playback edits.' };
+    const known = finite(duration) && duration > 0 ? duration : null;
+    const playback = {};
+    if (raw.framing !== undefined && raw.framing !== null) {
+        if (!isObject(raw.framing))
+            return { error: 'framing must be an object.' };
+        const keysRaw = raw.framing.keys ?? [];
+        if (!Array.isArray(keysRaw))
+            return { error: 'framing.keys must be a list.' };
+        if (keysRaw.length > MAX_FRAMING_KEYS)
+            return { error: `At most ${MAX_FRAMING_KEYS} framing keys.` };
+        const keys = tidyKeys(keysRaw.map((k) => cleanKey(k, known)).filter((k) => k !== null));
+        const baseZoom = finite(raw.framing.baseZoom) ? clamp(raw.framing.baseZoom, 1, PLAYBACK_MAX_ZOOM) : 1;
+        if (baseZoom !== 1 || keys.length > 0)
+            playback.framing = { baseZoom, keys };
+    }
+    if (raw.skips !== undefined && raw.skips !== null) {
+        if (!Array.isArray(raw.skips))
+            return { error: 'skips must be a list.' };
+        if (raw.skips.length > MAX_SKIPS)
+            return { error: `At most ${MAX_SKIPS} skips.` };
+        if (raw.skips.length > 0) {
+            if (known === null)
+                return { error: "This video's length is not known yet, so a skip cannot be placed in it." };
+            const spans = raw.skips.filter(isObject).map((s) => ({ start: Number(s.start), end: Number(s.end) }));
+            const skips = normalizeCuts(spans, known);
+            if (skips.length > 0 && keptSegments(skips, known).length === 0)
+                return { error: 'Those skips cover the whole video. Leave at least one section to play.' };
+            if (skips.length > 0)
+                playback.skips = skips;
+        }
+    }
+    return { playback };
+}
+/**
+ * Where playback must be instead of `t`: the end of the skip `t` is inside, or `null` when `t`
+ * plays. Half-open, as every cut: `start` jumps, `end` plays. `skips` must be normalized
+ * (sorted, merged), which is what {@link normalizePlayback} stores.
+ */
+export function skipTarget(skips, t) {
+    if (!skips || !finite(t))
+        return null;
+    for (const s of skips) {
+        if (t < s.start)
+            return null;
+        if (t < s.end)
+            return s.end;
+    }
+    return null;
+}
+/** How long the video plays with its skips — the length a tile shows beside its scissors. */
+export function playedSeconds(playback, duration) {
+    if (!finite(duration) || duration <= 0)
+        return 0;
+    return Math.max(0, duration - cutSeconds(playback?.skips ?? [], duration));
+}
+// ── The lanes ─────────────────────────────────────────────────────────────────────────────
+/** The center lane's value at `t`, or `null` when no key sets a center. */
+export function centerAt(track, t) {
+    const keys = (track?.keys ?? []).filter((k) => !!k.center);
+    return laneAt(keys, t, (k) => k.center, (a, b, f) => ({ x: a.x + (b.x - a.x) * f, y: a.y + (b.y - a.y) * f }));
+}
+/** The zoom lane's value at `t` — `baseZoom` when no key sets a zoom. */
+export function zoomAt(track, t) {
+    if (!track)
+        return 1;
+    const keys = track.keys.filter((k) => k.zoom !== undefined);
+    return laneAt(keys, t, (k) => k.zoom, (a, b, f) => Math.exp(Math.log(a) + (Math.log(b) - Math.log(a)) * f)) ?? track.baseZoom;
+}
+function laneAt(keys, t, value, mix) {
+    const first = keys[0];
+    if (!first)
+        return null;
+    if (!(t > first.t))
+        return value(first);
+    for (let i = 0; i < keys.length; i++) {
+        const key = keys[i];
+        const next = keys[i + 1];
+        if (!next)
+            return value(key);
+        if (t < next.t) {
+            if (key.toNext === 'hold' || next.t <= key.t)
+                return value(key);
+            return mix(value(key), value(next), (t - key.t) / (next.t - key.t));
+        }
+    }
+    return value(keys[keys.length - 1]);
+}
+// ── After a real trim ─────────────────────────────────────────────────────────────────────
+/**
+ * The original's edits, moved onto the trimmed copy. `removed` is what the file was CUT BY — the
+ * edit row's stored cuts, never the video's current skips, which may have changed since.
+ *
+ *  · A time after a removed span moves back by the removed time before it.
+ *  · A skip loses the parts the cut removed; the rest moves back. A skip the cut removed is gone.
+ *  · A framing key inside a removed span is dropped, and at each cut boundary a key carrying the
+ *    values in effect at the span's END is inserted, so the copy resumes framed exactly as the
+ *    original did after the same cut (no jump the original did not have).
+ */
+export function remapPlayback(playback, removed, duration) {
+    if (!playback)
+        return {};
+    const cuts = normalizeCuts(removed, duration);
+    const keptTotal = duration - cutSeconds(cuts, duration);
+    const inside = (t) => cuts.some((c) => t >= c.start && t < c.end);
+    const mapTime = (t) => {
+        let shift = 0;
+        for (const c of cuts)
+            if (c.end <= t)
+                shift += c.end - c.start;
+        return t - shift;
+    };
+    const out = {};
+    if (playback.skips?.length) {
+        const parts = [];
+        for (const skip of playback.skips) {
+            let from = skip.start;
+            for (const c of cuts) {
+                if (c.end <= from || c.start >= skip.end)
+                    continue;
+                if (c.start > from)
+                    parts.push({ start: mapTime(from), end: mapTime(c.start) });
+                from = Math.max(from, c.end);
+            }
+            if (skip.end - from >= MIN_CUT_SECONDS)
+                parts.push({ start: mapTime(from), end: mapTime(skip.end) });
+        }
+        const skips = normalizeCuts(parts, keptTotal);
+        if (skips.length)
+            out.skips = skips;
+    }
+    const framing = playback.framing;
+    if (framing && (framing.keys.length || framing.baseZoom !== 1)) {
+        const keys = framing.keys.filter((k) => !inside(k.t)).map((k) => ({ ...k, t: mapTime(k.t) }));
+        const hasCenter = framing.keys.some((k) => k.center);
+        const hasZoom = framing.keys.some((k) => k.zoom !== undefined);
+        for (const c of cuts) {
+            if (c.end >= duration || !(hasCenter || hasZoom))
+                continue;
+            const governing = [...framing.keys].reverse().find((k) => k.t <= c.end);
+            const key = { t: mapTime(c.end), toNext: governing?.toNext ?? 'hold' };
+            const center = centerAt(framing, c.end);
+            if (hasCenter && center)
+                key.center = center;
+            if (hasZoom)
+                key.zoom = zoomAt(framing, c.end);
+            keys.push(key);
+        }
+        const tidy = tidyKeys(keys).filter((k) => k.t <= keptTotal);
+        if (tidy.length || framing.baseZoom !== 1)
+            out.framing = { baseZoom: framing.baseZoom, keys: tidy };
+    }
+    return out;
+}

package/dist/core/media/videoCuts.d.ts

@@ -150,3 +150,9 @@ export declare function toggleSegment(plan: CutPlan, segment: VideoCut, duration
 export declare function planCuts(plan: CutPlan, duration: number): VideoCut[];
 /** Why this plan cannot be sent, or `null`. The same two refusals, asked of a plan. */
 export declare function planProblem(plan: CutPlan, duration: number): string | null;
+/**
+ * A plan that marks exactly `cuts` — how the editor reopens on a video's SAVED skips (forge task
+ * 2026-11-07-23:39). Each cut's bounds become splits and the pieces between them are marked removed,
+ * so `planCuts(planFromCuts(c, d), d)` is `normalizeCuts(c, d)`.
+ */
+export declare function planFromCuts(cuts: readonly VideoCut[], duration: number): CutPlan;

package/dist/core/media/videoCuts.js

@@ -282,3 +282,13 @@ export function planCuts(plan, duration) {
 export function planProblem(plan, duration) {
     return cutListProblem(planCuts(plan, duration), duration);
 }
+/**
+ * A plan that marks exactly `cuts` — how the editor reopens on a video's SAVED skips (forge task
+ * 2026-11-07-23:39). Each cut's bounds become splits and the pieces between them are marked removed,
+ * so `planCuts(planFromCuts(c, d), d)` is `normalizeCuts(c, d)`.
+ */
+export function planFromCuts(cuts, duration) {
+    const removed = normalizeCuts(cuts, duration);
+    const splits = removed.flatMap((cut) => [cut.start, cut.end]).filter((t) => t > 0 && t < duration);
+    return { splits: [...new Set(splits)], removed };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-core",
-	"version": "2.14.1",
+	"version": "2.15.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "Framework-agnostic core of the cursedbelt split — isomorphic domain logic. cwip below it, cursedbelt-server and cursedbelt (react) above it.",
@@ -17,7 +17,7 @@
 	},
 	"scripts": {
 		"clean": "rm -rf dist",
-		"typecheck": "tsc -p tsconfig.build.json --noEmit",
+		"typecheck": "tsc -p tsconfig.json --noEmit",
 		"test": "NODE_ENV=development bun test --timeout 60000 --parallel=4 src",
 		"build": "bun run clean && tsc -p tsconfig.build.json",
 		"paths": "bun run scripts/paths.ts",
@@ -241,6 +241,12 @@
 			"source": "./src/core/media/uploadLimits.ts",
 			"import": "./dist/core/media/uploadLimits.js"
 		},
+		"./media/playback-edits": {
+			"types": "./dist/core/media/playbackEdits.d.ts",
+			"bun": "./src/core/media/playbackEdits.ts",
+			"source": "./src/core/media/playbackEdits.ts",
+			"import": "./dist/core/media/playbackEdits.js"
+		},
 		"./media/video-cuts": {
 			"types": "./dist/core/media/videoCuts.d.ts",
 			"bun": "./src/core/media/videoCuts.ts",

package/src/core/media/playbackEdits.spec.ts

@@ -0,0 +1,162 @@
+/**
+ * Saved playback edits: the gate every writer passes, the two framing lanes, skips, and the
+ * remap a real trim's copy inherits.
+ */
+import { describe, expect, test } from 'bun:test';
+import {
+  centerAt,
+  type FramingTrack,
+  isEmptyPlayback,
+  MAX_FRAMING_KEYS,
+  normalizePlayback,
+  playedSeconds,
+  remapPlayback,
+  skipTarget,
+  zoomAt,
+} from './playbackEdits';
+
+const ok = (raw: unknown, duration: number | null = 100) => {
+  const r = normalizePlayback(raw, duration);
+  if ('error' in r) throw new Error(r.error);
+  return r.playback;
+};
+
+describe('normalizePlayback — the one gate', () => {
+  test('refuses what cannot be meant, with a sentence', () => {
+    expect(normalizePlayback(null, 100)).toEqual({ error: expect.any(String) });
+    expect(normalizePlayback([], 100)).toEqual({ error: expect.any(String) });
+    expect(normalizePlayback({ skips: 'x' }, 100)).toEqual({ error: expect.any(String) });
+    expect(normalizePlayback({ framing: { keys: Array.from({ length: MAX_FRAMING_KEYS + 1 }, (_, t) => ({ t, zoom: 2 })) } }, 1000)).toEqual({
+      error: expect.stringContaining('500'),
+    });
+    expect(normalizePlayback({ skips: [{ start: 0, end: 100 }] }, 100)).toEqual({ error: expect.stringContaining('whole video') });
+    expect(normalizePlayback({ skips: [{ start: 1, end: 2 }] }, null)).toEqual({ error: expect.stringContaining('not known') });
+  });
+
+  test('clamps, sorts, merges a moment, and drops keys past the end or setting nothing', () => {
+    const p = ok({
+      framing: {
+        baseZoom: 99,
+        keys: [
+          { t: 50, zoom: 0.2, toNext: 'glide' },
+          { t: 10, center: { x: -1, y: 2 } },
+          { t: 10.0001, zoom: 3 },
+          { t: 101, zoom: 2 },
+          { t: 20 },
+        ],
+      },
+    });
+    expect(p.framing).toEqual({
+      baseZoom: 20,
+      keys: [
+        { t: 10, center: { x: 0, y: 1 }, zoom: 3, toNext: 'hold' },
+        { t: 50, zoom: 1, toNext: 'glide' },
+      ],
+    });
+  });
+
+  test('skips go through the cut model: merged, sorted, inside the clip', () => {
+    expect(ok({ skips: [{ start: 30, end: 40 }, { start: 5, end: 10 }, { start: 35, end: 50 }, { start: 90, end: 200 }] }).skips).toEqual([
+      { start: 5, end: 10 },
+      { start: 30, end: 50 },
+      { start: 90, end: 100 },
+    ]);
+  });
+
+  test('nothing saved is empty — the row is deleted', () => {
+    const p = ok({ framing: { baseZoom: 1, keys: [] }, skips: [] });
+    expect(p).toEqual({});
+    expect(isEmptyPlayback(p)).toBe(true);
+    expect(isEmptyPlayback(ok({ skips: [{ start: 1, end: 2 }] }))).toBe(false);
+  });
+});
+
+describe('skips', () => {
+  const skips = [
+    { start: 10, end: 20 },
+    { start: 50, end: 60 },
+  ];
+  test('a time inside a skip goes to its end; start jumps, end plays', () => {
+    expect(skipTarget(skips, 9.99)).toBeNull();
+    expect(skipTarget(skips, 10)).toBe(20);
+    expect(skipTarget(skips, 15)).toBe(20);
+    expect(skipTarget(skips, 20)).toBeNull();
+    expect(skipTarget(skips, 55)).toBe(60);
+    expect(skipTarget(undefined, 15)).toBeNull();
+  });
+  test('the played length is the duration less the skips', () => {
+    expect(playedSeconds({ skips }, 100)).toBe(80);
+    expect(playedSeconds(null, 100)).toBe(100);
+  });
+});
+
+describe('the framing lanes', () => {
+  const track: FramingTrack = {
+    baseZoom: 1.5,
+    keys: [
+      { t: 10, center: { x: 0.2, y: 0.2 }, toNext: 'glide' },
+      { t: 20, zoom: 1, toNext: 'glide' },
+      { t: 30, center: { x: 0.6, y: 0.8 }, toNext: 'hold' },
+      { t: 40, zoom: 4, toNext: 'hold' },
+      { t: 50, center: { x: 0.9, y: 0.1 }, toNext: 'hold' },
+    ],
+  };
+  test('center glides linearly between ITS keys; a zoom key between them moves nothing', () => {
+    expect(centerAt(track, 20)).toEqual({ x: 0.4, y: 0.5 });
+    expect(centerAt(track, 25)?.x).toBeCloseTo(0.5);
+  });
+  test('hold keeps a value until the next key of the lane', () => {
+    expect(centerAt(track, 49.9)).toEqual({ x: 0.6, y: 0.8 });
+    expect(centerAt(track, 50)).toEqual({ x: 0.9, y: 0.1 });
+  });
+  test('zoom glides in log space: 1× → 4× is 2× halfway', () => {
+    expect(zoomAt(track, 30)).toBeCloseTo(2);
+    expect(zoomAt(track, 45)).toBe(4);
+  });
+  test('before the first key the first value holds; after the last, the last', () => {
+    expect(centerAt(track, 0)).toEqual({ x: 0.2, y: 0.2 });
+    expect(centerAt(track, 999)).toEqual({ x: 0.9, y: 0.1 });
+    expect(zoomAt(track, 0)).toBe(1);
+  });
+  test('no zoom key: the whole-video zoom; no track at all: none', () => {
+    expect(zoomAt({ baseZoom: 2.5, keys: [{ t: 3, center: { x: 0.5, y: 0.5 }, toNext: 'hold' }] }, 50)).toBe(2.5);
+    expect(zoomAt(null, 5)).toBe(1);
+    expect(centerAt({ baseZoom: 2, keys: [] }, 5)).toBeNull();
+  });
+});
+
+describe('remapPlayback — the trimmed copy inherits the edits', () => {
+  test('skips shift back by the removed time before them; a cut skip is gone; a straddling one is clipped', () => {
+    const p = { skips: [{ start: 10, end: 15 }, { start: 30, end: 40 }, { start: 70, end: 80 }] };
+    // remove [8, 16) (swallows the first skip) and [35, 50) (clips the second)
+    expect(remapPlayback(p, [{ start: 8, end: 16 }, { start: 35, end: 50 }], 100).skips).toEqual([
+      { start: 22, end: 27 },
+      { start: 47, end: 57 },
+    ]);
+  });
+  test('a key inside a removed span is dropped and the cut boundary gets the values in effect at its end', () => {
+    const framing: FramingTrack = {
+      baseZoom: 1,
+      keys: [
+        { t: 0, center: { x: 0, y: 0 }, zoom: 1, toNext: 'glide' },
+        { t: 20, center: { x: 1, y: 1 }, zoom: 4, toNext: 'hold' },
+        { t: 60, zoom: 2, toNext: 'hold' },
+      ],
+    };
+    const out = remapPlayback({ framing }, [{ start: 5, end: 15 }], 100).framing;
+    expect(out?.keys).toEqual([
+      { t: 0, center: { x: 0, y: 0 }, zoom: 1, toNext: 'glide' },
+      { t: 5, center: { x: 0.75, y: 0.75 }, zoom: zoomAt(framing, 15), toNext: 'glide' },
+      { t: 10, center: { x: 1, y: 1 }, zoom: 4, toNext: 'hold' },
+      { t: 50, zoom: 2, toNext: 'hold' },
+    ]);
+    // After the cut, the copy is framed as the original was after the same cut.
+    for (const t of [16, 30, 70]) {
+      expect(centerAt(out, t - 10)).toEqual(centerAt(framing, t) as { x: number; y: number });
+      expect(zoomAt(out, t - 10)).toBeCloseTo(zoomAt(framing, t));
+    }
+  });
+  test('nothing saved stays nothing', () => {
+    expect(remapPlayback(null, [{ start: 1, end: 2 }], 10)).toEqual({});
+  });
+});

package/src/core/media/playbackEdits.ts

@@ -0,0 +1,260 @@
+/**
+ * SAVED PLAYBACK EDITS — skips, and the framing a video plays with, saved beside it and applied
+ * while it plays. Not one byte of the stored file changes.
+ *
+ * The owner, 2026-11-07: *"allow marking center points on the video player at different times so
+ * I can play the video zoomed in … It should not actually alter the stored video. It should be
+ * able to be toggled off"*, then *"Can we add a trim capability with this feature, where it
+ * remembers jump points to go to and skips the points in between. Then later I can have it do the
+ * real trim if I want to."*
+ *
+ * ── One model, read by the editor, the server and the trim drain ──────────────────────────
+ * The server refuses what {@link normalizePlayback} refuses and stores what it returns, the
+ * editor saves through the same function, and the real trim's copy inherits its original's edits
+ * through {@link remapPlayback}. Three readers of one shape is why the shape lives here, beside
+ * the cut model, and not in any one of them.
+ *
+ * 🔴 **Skips ARE trim marks.** A skip is a {@link VideoCut}: the same `[start, end)` span the trim
+ * editor marks and binary-server removes, normalized by the same {@link normalizeCuts}. There is
+ * no second cut model, so "Make trimmed file…" sends exactly what is already playing.
+ *
+ * ── Framing: two lanes on one list of keys ─────────────────────────────────────────────────
+ * A key may set a center, a zoom, or both. Each LANE (center, zoom) is read only from the keys
+ * that set it, so a zoom key never moves the center and a center key never changes the zoom.
+ * `toNext` says how a key reaches the next key of the same lane: `hold` keeps its value until
+ * then, `glide` moves over the span — center linearly, zoom geometrically (a 1×→4× glide passes
+ * 2× halfway, which is what the eye reads as even). Before a lane's first key its first value
+ * holds; after its last key its last value holds.
+ */
+import { MIN_CUT_SECONDS, normalizeCuts, keptSegments, cutSeconds, type VideoCut } from './videoCuts.js';
+
+export type FramingMode = 'hold' | 'glide';
+
+/** A point of the SOURCE frame, 0–1 from its top-left (as `videoRegion`'s `Region`). */
+export interface FramingPoint {
+  x: number;
+  y: number;
+}
+
+export interface FramingKey {
+  /** Seconds into the source. */
+  t: number;
+  center?: FramingPoint;
+  /** Magnification, 1 = the whole frame. */
+  zoom?: number;
+  toNext: FramingMode;
+}
+
+export interface FramingTrack {
+  /** Whole-video zoom, used when no key sets the zoom lane. 1 = none. */
+  baseZoom: number;
+  keys: FramingKey[];
+}
+
+export interface PlaybackEdits {
+  framing?: FramingTrack;
+  /** Spans playback jumps over — the trim editor's marks. */
+  skips?: VideoCut[];
+}
+
+/** The most a saved zoom may magnify — cursedbelt's `MAX_ZOOM` (its spec holds the two equal). */
+export const PLAYBACK_MAX_ZOOM = 20;
+export const MAX_FRAMING_KEYS = 500;
+export const MAX_SKIPS = 200;
+/** Two keys closer than this are one moment — the later write wins. */
+const SAME_MOMENT = 1e-3;
+
+const finite = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+const clamp = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v));
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+/** Nothing saved — the row is deleted and the item carries no `playback`. */
+export const isEmptyPlayback = (p: PlaybackEdits | null | undefined): boolean =>
+  !p || ((!p.framing || (p.framing.baseZoom === 1 && p.framing.keys.length === 0)) && (!p.skips || p.skips.length === 0));
+
+function cleanKey(raw: unknown, duration: number | null): FramingKey | null {
+  if (!isObject(raw) || !finite(raw.t) || raw.t < 0) return null;
+  if (duration !== null && raw.t > duration) return null;
+  const key: FramingKey = { t: raw.t, toNext: raw.toNext === 'glide' ? 'glide' : 'hold' };
+  if (isObject(raw.center) && finite(raw.center.x) && finite(raw.center.y))
+    key.center = { x: clamp(raw.center.x, 0, 1), y: clamp(raw.center.y, 0, 1) };
+  if (finite(raw.zoom)) key.zoom = clamp(raw.zoom, 1, PLAYBACK_MAX_ZOOM);
+  return key.center || key.zoom !== undefined ? key : null;
+}
+
+/** Sorted by time; keys at one moment merge, the later in the list winning each lane. */
+function tidyKeys(keys: readonly FramingKey[]): FramingKey[] {
+  const sorted = keys.map((k, i) => ({ k, i })).sort((a, b) => a.k.t - b.k.t || a.i - b.i);
+  const out: FramingKey[] = [];
+  for (const { k } of sorted) {
+    const last = out[out.length - 1];
+    if (last && k.t - last.t < SAME_MOMENT) {
+      const merged: FramingKey = { ...last, toNext: k.toNext };
+      if (k.center) merged.center = k.center;
+      if (k.zoom !== undefined) merged.zoom = k.zoom;
+      out[out.length - 1] = merged;
+    } else out.push({ ...k });
+  }
+  return out;
+}
+
+/**
+ * The ONE gate every writer passes: the server before it stores, the editor before it saves.
+ * Out-of-range values are CLAMPED (a center dragged a pixel past the edge is still the edge),
+ * keys past the end are dropped, and only what cannot be meant is refused: not an object, too
+ * many keys or skips, or skips that remove the whole video.
+ *
+ * `duration` null means the length is not known: framing still saves, skips are refused —
+ * a span cannot be placed in a video of unknown length.
+ */
+export function normalizePlayback(
+  raw: unknown,
+  duration: number | null,
+): { playback: PlaybackEdits } | { error: string } {
+  if (!isObject(raw)) return { error: 'Expected an object of playback edits.' };
+  const known = finite(duration) && duration > 0 ? duration : null;
+  const playback: PlaybackEdits = {};
+
+  if (raw.framing !== undefined && raw.framing !== null) {
+    if (!isObject(raw.framing)) return { error: 'framing must be an object.' };
+    const keysRaw = raw.framing.keys ?? [];
+    if (!Array.isArray(keysRaw)) return { error: 'framing.keys must be a list.' };
+    if (keysRaw.length > MAX_FRAMING_KEYS) return { error: `At most ${MAX_FRAMING_KEYS} framing keys.` };
+    const keys = tidyKeys(keysRaw.map((k) => cleanKey(k, known)).filter((k): k is FramingKey => k !== null));
+    const baseZoom = finite(raw.framing.baseZoom) ? clamp(raw.framing.baseZoom, 1, PLAYBACK_MAX_ZOOM) : 1;
+    if (baseZoom !== 1 || keys.length > 0) playback.framing = { baseZoom, keys };
+  }
+
+  if (raw.skips !== undefined && raw.skips !== null) {
+    if (!Array.isArray(raw.skips)) return { error: 'skips must be a list.' };
+    if (raw.skips.length > MAX_SKIPS) return { error: `At most ${MAX_SKIPS} skips.` };
+    if (raw.skips.length > 0) {
+      if (known === null) return { error: "This video's length is not known yet, so a skip cannot be placed in it." };
+      const spans = raw.skips.filter(isObject).map((s) => ({ start: Number(s.start), end: Number(s.end) }));
+      const skips = normalizeCuts(spans, known);
+      if (skips.length > 0 && keptSegments(skips, known).length === 0)
+        return { error: 'Those skips cover the whole video. Leave at least one section to play.' };
+      if (skips.length > 0) playback.skips = skips;
+    }
+  }
+  return { playback };
+}
+
+/**
+ * Where playback must be instead of `t`: the end of the skip `t` is inside, or `null` when `t`
+ * plays. Half-open, as every cut: `start` jumps, `end` plays. `skips` must be normalized
+ * (sorted, merged), which is what {@link normalizePlayback} stores.
+ */
+export function skipTarget(skips: readonly VideoCut[] | undefined, t: number): number | null {
+  if (!skips || !finite(t)) return null;
+  for (const s of skips) {
+    if (t < s.start) return null;
+    if (t < s.end) return s.end;
+  }
+  return null;
+}
+
+/** How long the video plays with its skips — the length a tile shows beside its scissors. */
+export function playedSeconds(playback: PlaybackEdits | null | undefined, duration: number): number {
+  if (!finite(duration) || duration <= 0) return 0;
+  return Math.max(0, duration - cutSeconds(playback?.skips ?? [], duration));
+}
+
+// ── The lanes ─────────────────────────────────────────────────────────────────────────────
+
+/** The center lane's value at `t`, or `null` when no key sets a center. */
+export function centerAt(track: FramingTrack | null | undefined, t: number): FramingPoint | null {
+  const keys = (track?.keys ?? []).filter((k): k is FramingKey & { center: FramingPoint } => !!k.center);
+  return laneAt(keys, t, (k) => k.center, (a, b, f) => ({ x: a.x + (b.x - a.x) * f, y: a.y + (b.y - a.y) * f }));
+}
+
+/** The zoom lane's value at `t` — `baseZoom` when no key sets a zoom. */
+export function zoomAt(track: FramingTrack | null | undefined, t: number): number {
+  if (!track) return 1;
+  const keys = track.keys.filter((k): k is FramingKey & { zoom: number } => k.zoom !== undefined);
+  return laneAt(keys, t, (k) => k.zoom, (a, b, f) => Math.exp(Math.log(a) + (Math.log(b) - Math.log(a)) * f)) ?? track.baseZoom;
+}
+
+function laneAt<K extends FramingKey, V>(
+  keys: readonly K[],
+  t: number,
+  value: (k: K) => V,
+  mix: (a: V, b: V, f: number) => V,
+): V | null {
+  const first = keys[0];
+  if (!first) return null;
+  if (!(t > first.t)) return value(first);
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i] as K;
+    const next = keys[i + 1];
+    if (!next) return value(key);
+    if (t < next.t) {
+      if (key.toNext === 'hold' || next.t <= key.t) return value(key);
+      return mix(value(key), value(next), (t - key.t) / (next.t - key.t));
+    }
+  }
+  return value(keys[keys.length - 1] as K);
+}
+
+// ── After a real trim ─────────────────────────────────────────────────────────────────────
+
+/**
+ * The original's edits, moved onto the trimmed copy. `removed` is what the file was CUT BY — the
+ * edit row's stored cuts, never the video's current skips, which may have changed since.
+ *
+ *  · A time after a removed span moves back by the removed time before it.
+ *  · A skip loses the parts the cut removed; the rest moves back. A skip the cut removed is gone.
+ *  · A framing key inside a removed span is dropped, and at each cut boundary a key carrying the
+ *    values in effect at the span's END is inserted, so the copy resumes framed exactly as the
+ *    original did after the same cut (no jump the original did not have).
+ */
+export function remapPlayback(
+  playback: PlaybackEdits | null | undefined,
+  removed: readonly VideoCut[],
+  duration: number,
+): PlaybackEdits {
+  if (!playback) return {};
+  const cuts = normalizeCuts(removed, duration);
+  const keptTotal = duration - cutSeconds(cuts, duration);
+  const inside = (t: number) => cuts.some((c) => t >= c.start && t < c.end);
+  const mapTime = (t: number) => {
+    let shift = 0;
+    for (const c of cuts) if (c.end <= t) shift += c.end - c.start;
+    return t - shift;
+  };
+  const out: PlaybackEdits = {};
+
+  if (playback.skips?.length) {
+    const parts: VideoCut[] = [];
+    for (const skip of playback.skips) {
+      let from = skip.start;
+      for (const c of cuts) {
+        if (c.end <= from || c.start >= skip.end) continue;
+        if (c.start > from) parts.push({ start: mapTime(from), end: mapTime(c.start) });
+        from = Math.max(from, c.end);
+      }
+      if (skip.end - from >= MIN_CUT_SECONDS) parts.push({ start: mapTime(from), end: mapTime(skip.end) });
+    }
+    const skips = normalizeCuts(parts, keptTotal);
+    if (skips.length) out.skips = skips;
+  }
+
+  const framing = playback.framing;
+  if (framing && (framing.keys.length || framing.baseZoom !== 1)) {
+    const keys: FramingKey[] = framing.keys.filter((k) => !inside(k.t)).map((k) => ({ ...k, t: mapTime(k.t) }));
+    const hasCenter = framing.keys.some((k) => k.center);
+    const hasZoom = framing.keys.some((k) => k.zoom !== undefined);
+    for (const c of cuts) {
+      if (c.end >= duration || !(hasCenter || hasZoom)) continue;
+      const governing = [...framing.keys].reverse().find((k) => k.t <= c.end);
+      const key: FramingKey = { t: mapTime(c.end), toNext: governing?.toNext ?? 'hold' };
+      const center = centerAt(framing, c.end);
+      if (hasCenter && center) key.center = center;
+      if (hasZoom) key.zoom = zoomAt(framing, c.end);
+      keys.push(key);
+    }
+    const tidy = tidyKeys(keys).filter((k) => k.t <= keptTotal);
+    if (tidy.length || framing.baseZoom !== 1) out.framing = { baseZoom: framing.baseZoom, keys: tidy };
+  }
+  return out;
+}

package/src/core/media/videoCuts.spec.ts

@@ -14,6 +14,7 @@ import {
   MIN_CUT_SECONDS,
   normalizeCuts,
   planCuts,
+  planFromCuts,
   planProblem,
   planSegments,
   removeSplit,
@@ -325,3 +326,15 @@ describe('segment keys', () => {
     expect(after.some((segment) => segment.key === survivor?.key)).toBe(true);
   });
 });
+
+describe('planFromCuts — the editor reopens on saved skips', () => {
+  test('round-trips through planCuts, head and tail cuts included', () => {
+    const cuts = [
+      { start: 0, end: 3 },
+      { start: 20, end: 30 },
+      { start: 95, end: 100 },
+    ];
+    expect(planCuts(planFromCuts(cuts, 100), 100)).toEqual(cuts);
+    expect(planFromCuts([], 100)).toEqual({ splits: [], removed: [] });
+  });
+});

package/src/core/media/videoCuts.ts

@@ -353,3 +353,14 @@ export function planCuts(plan: CutPlan, duration: number): VideoCut[] {
 export function planProblem(plan: CutPlan, duration: number): string | null {
   return cutListProblem(planCuts(plan, duration), duration);
 }
+
+/**
+ * A plan that marks exactly `cuts` — how the editor reopens on a video's SAVED skips (forge task
+ * 2026-11-07-23:39). Each cut's bounds become splits and the pieces between them are marked removed,
+ * so `planCuts(planFromCuts(c, d), d)` is `normalizeCuts(c, d)`.
+ */
+export function planFromCuts(cuts: readonly VideoCut[], duration: number): CutPlan {
+  const removed = normalizeCuts(cuts, duration);
+  const splits = removed.flatMap((cut) => [cut.start, cut.end]).filter((t) => t > 0 && t < duration);
+  return { splits: [...new Set(splits)], removed };
+}

package/src/core/offline/shellWorker.spec.ts

@@ -5,6 +5,7 @@ import {
   isContentHashed,
   mayFallBackToShell,
   type RequestFacts,
+  type ShellRoute,
   resolveShellWorkerConfig,
   type ShellExtendableEvent,
   type ShellFetchEvent,
@@ -35,7 +36,7 @@ const facts = (pathname: string, over: Partial<RequestFacts> = {}): RequestFacts
 });
 
 describe('classifyRequest — roms parity', () => {
-  const table: Array<[string, RequestFacts, string]> = [
+  const table: Array<[string, RequestFacts, ShellRoute]> = [
     ['non-GET is passthrough', facts('/app.js', { method: 'POST' }), 'passthrough'],
     ['cross-origin is passthrough', facts('/app.js', { sameOrigin: false }), 'passthrough'],
     ['/api/ is api', facts('/api/saves'), 'api'],