@lp-labs/subtitle-timing 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Libin Prasanth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,156 @@
-# Temporary Holding Version
+# @lp-labs/subtitle-timing
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shifts, scales, splits, clips and de-overlaps subtitle cues expressed as integer millisecond intervals. It does not parse or write SRT/VTT. Catalog identity 489; standalone package version 1.0.0.
+No runtime, peer, or sibling dependencies. Node >=18, ESM and CommonJS with declarations.
+
+## Install
+
+```sh
+npm install @lp-labs/subtitle-timing
+```
+
+## Quickstart (runnable JavaScript)
+
+```js
+import assert from 'node:assert/strict';
+import {
+  mergeIntervals,
+  resolveOverlaps,
+  scaleCues,
+  shiftCues,
+  splitCue,
+} from '@lp-labs/subtitle-timing';
+const cues = [
+  { id: 'a', startMs: 1000, endMs: 3000, text: 'Hello' },
+  { id: 'b', startMs: 2500, endMs: 4000, text: 'World' },
+];
+assert.deepEqual(
+  shiftCues(cues, -1000, { negative: 'error' }).map((c) => c.startMs),
+  [0, 1500],
+);
+assert.deepEqual(
+  scaleCues(cues, 2).map((c) => c.endMs),
+  [6000, 8000],
+);
+assert.deepEqual(
+  resolveOverlaps(cues, 'trim-previous').map((c) => [c.startMs, c.endMs]),
+  [
+    [1000, 2500],
+    [2500, 4000],
+  ],
+);
+assert.deepEqual(
+  splitCue(cues[0], [2000]).map((c) => c.id),
+  ['a#1', 'a#2'],
+);
+assert.deepEqual(mergeIntervals(cues), [{ startMs: 1000, endMs: 4000 }]);
+```
+
+## Configuration and errors
+
+A `Cue` is `{ id?: string, startMs, endMs, text }` with integer milliseconds, `startMs >= 0` and `endMs > startMs` (half-open intervals). All functions return new cue objects and never mutate input.
+
+- `shiftCues(cues, deltaMs, { negative })` and `scaleCues(cues, factor, { anchorMs, rounding, negative })` (time `t` becomes `anchor + (t - anchor) * factor`, rounded with `round` (default), `floor` or `ceil`). Negative-time policy for a cue that would start before 0: `error` (default, RangeError), `clip` (start moves to 0; cues that end at or before 0 are removed) or `drop` (any such cue is removed). A scaled cue that collapses to zero length is a RangeError.
+- `splitCue(cue, atMs, texts?)`: strictly increasing interior times; pieces keep the text unless one string per piece is given; ids become `id#1`, `id#2`...
+- `clipCues(cues, windowStartMs, windowEndMs, { rebase })`: intersect with a window, optionally subtracting the window start.
+- `sortCues`, `findOverlaps(cues, { maxPairs })` (positive-duration overlaps only, indices into the input, touching cues do not overlap), `mergeIntervals` (union; touching intervals merge) and `resolveOverlaps(cues, 'trim-previous' | 'push-next')`.
+- `maxCues` (default 100000) and `maxPairs` (default 100000) are budgets.
+
+Errors: `TypeError` for wrong container types, missing text/non-string ids or unknown policies; `RangeError` for non-integer or out-of-range times, results beyond safe integers, collapsed or invalid ranges and exceeded budgets.
+
+## Complete public declarations
+
+Every runtime export and public type is shown below. This is the complete emitted declaration surface.
+
+```ts
+export interface Cue {
+  id?: string;
+  startMs: number;
+  endMs: number;
+  text: string;
+}
+export type NegativePolicy = 'error' | 'clip' | 'drop';
+export type TimeRounding = 'round' | 'floor' | 'ceil';
+export type OverlapPolicy = 'trim-previous' | 'push-next';
+export interface ShiftOptions {
+  negative?: NegativePolicy;
+}
+export interface ScaleOptions extends ShiftOptions {
+  anchorMs?: number;
+  rounding?: TimeRounding;
+}
+export interface Interval {
+  startMs: number;
+  endMs: number;
+}
+export interface Overlap extends Interval {
+  first: number;
+  second: number;
+}
+export interface LimitOptions {
+  maxCues?: number;
+}
+export interface OverlapSearchOptions extends LimitOptions {
+  maxPairs?: number;
+}
+export interface ClipOptions extends LimitOptions {
+  rebase?: boolean;
+}
+export declare const DEFAULT_MAX_CUES = 100000;
+export declare const DEFAULT_MAX_PAIRS = 100000;
+export declare function shiftCues(
+  cues: readonly Cue[],
+  deltaMs: number,
+  options?: ShiftOptions,
+): Cue[];
+export declare function scaleCues(
+  cues: readonly Cue[],
+  factor: number,
+  options?: ScaleOptions,
+): Cue[];
+export declare function splitCue(
+  cue: Cue,
+  atMs: readonly number[],
+  texts?: readonly string[],
+): Cue[];
+export declare function clipCues(
+  cues: readonly Cue[],
+  windowStartMs: number,
+  windowEndMs: number,
+  options?: ClipOptions,
+): Cue[];
+export declare function sortCues(cues: readonly Cue[]): Cue[];
+export declare function findOverlaps(
+  cues: readonly Cue[],
+  options?: OverlapSearchOptions,
+): Overlap[];
+export declare function resolveOverlaps(cues: readonly Cue[], overlapPolicy: OverlapPolicy): Cue[];
+export declare function mergeIntervals(cues: readonly Cue[], options?: LimitOptions): Interval[];
+```
+
+## Performance, boundaries and limitations
+
+Only times are manipulated: there is no SRT/VTT/ASS parsing or serialisation, no text re-wrapping, reading-speed or frame-rate logic. Splitting never guesses where text should break. `resolveOverlaps` sorts by start, end then original order and compares each cue only with the most recently kept cue: `trim-previous` shortens that cue (removing it if nothing remains) and `push-next` delays the new cue to its end (removing it if nothing remains), so some text time can be lost by design. Rounding is applied independently to start and end. Overlap discovery is O(n log n + pairs); every other operation is O(n log n) at most. Times are limited to safe integers.
+
+## Development
+
+```sh
+npm ci --offline
+npm run build
+npm run typecheck
+npm test
+npm run format:check
+```
+
+The offline install requires the locked development dependencies already in the npm cache.
+Build emits separate ESM/CJS and declarations; type checks include bare-package .mts/.cts consumers with negative cases.
+Runtime tests import only the single-quoted standalone dist entry and also run against installed offline tarballs.
+No build artifacts or development dependencies are required at runtime.
+
+## Support
+
+If this library is useful to you, consider supporting its maintenance with a [donation via PayPal](https://www.paypal.me/LibinPrasanth).
+
+## Author
+
+Created by [Libin Prasanth](https://www.linkedin.com/in/libinprasanth/). Connect on LinkedIn for updates and discussion.

package/dist/cjs/index.d.ts

@@ -0,0 +1,57 @@
+export interface Cue {
+    id?: string;
+    /** Inclusive start in integer milliseconds (>= 0). */
+    startMs: number;
+    /** Exclusive end in integer milliseconds (> startMs). */
+    endMs: number;
+    text: string;
+}
+export type NegativePolicy = 'error' | 'clip' | 'drop';
+export type TimeRounding = 'round' | 'floor' | 'ceil';
+export type OverlapPolicy = 'trim-previous' | 'push-next';
+export interface ShiftOptions {
+    /** What to do when a shifted cue starts before 0. Default 'error'. */
+    negative?: NegativePolicy;
+}
+export interface ScaleOptions extends ShiftOptions {
+    /** Time that stays fixed while scaling. Default 0. */
+    anchorMs?: number;
+    rounding?: TimeRounding;
+}
+export interface Interval {
+    startMs: number;
+    endMs: number;
+}
+export interface Overlap extends Interval {
+    /** Indices into the supplied array, first < second. */
+    first: number;
+    second: number;
+}
+export interface LimitOptions {
+    maxCues?: number;
+}
+export interface OverlapSearchOptions extends LimitOptions {
+    maxPairs?: number;
+}
+export interface ClipOptions extends LimitOptions {
+    /** Subtract windowStartMs from kept cues. Default false. */
+    rebase?: boolean;
+}
+export declare const DEFAULT_MAX_CUES = 100000;
+export declare const DEFAULT_MAX_PAIRS = 100000;
+/** Adds deltaMs to every cue; the input array and cues are not modified. */
+export declare function shiftCues(cues: readonly Cue[], deltaMs: number, options?: ShiftOptions): Cue[];
+/** Maps t to anchor + (t - anchor) * factor, rounded; a cue that collapses to zero length is an error. */
+export declare function scaleCues(cues: readonly Cue[], factor: number, options?: ScaleOptions): Cue[];
+/** Splits at strictly increasing interior times. Pieces get ids `${id}#1`, `${id}#2`, ... when the cue has an id. */
+export declare function splitCue(cue: Cue, atMs: readonly number[], texts?: readonly string[]): Cue[];
+/** Intersects cues with [windowStartMs, windowEndMs); cues with no remaining duration are removed. */
+export declare function clipCues(cues: readonly Cue[], windowStartMs: number, windowEndMs: number, options?: ClipOptions): Cue[];
+/** Stable sort by start then end; returns new cue objects. */
+export declare function sortCues(cues: readonly Cue[]): Cue[];
+/** All pairs that share positive duration (touching cues do not overlap), ordered by (first, second). */
+export declare function findOverlaps(cues: readonly Cue[], options?: OverlapSearchOptions): Overlap[];
+/** Sorts by start and removes overlaps against the previously kept cue; empty results are dropped. */
+export declare function resolveOverlaps(cues: readonly Cue[], overlapPolicy: OverlapPolicy): Cue[];
+/** Union of cue time as sorted disjoint intervals; touching intervals are merged. */
+export declare function mergeIntervals(cues: readonly Cue[], options?: LimitOptions): Interval[];

package/dist/cjs/index.js

@@ -0,0 +1,229 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_PAIRS = exports.DEFAULT_MAX_CUES = void 0;
+exports.shiftCues = shiftCues;
+exports.scaleCues = scaleCues;
+exports.splitCue = splitCue;
+exports.clipCues = clipCues;
+exports.sortCues = sortCues;
+exports.findOverlaps = findOverlaps;
+exports.resolveOverlaps = resolveOverlaps;
+exports.mergeIntervals = mergeIntervals;
+exports.DEFAULT_MAX_CUES = 100_000;
+exports.DEFAULT_MAX_PAIRS = 100_000;
+function time(name, value, min) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < min) {
+        throw new RangeError(`${name} must be a safe integer >= ${min}`);
+    }
+    return value;
+}
+function limit(name, value, fallback) {
+    return value === undefined ? fallback : time(name, value, 0);
+}
+function readCues(cues, maxCues) {
+    if (!Array.isArray(cues))
+        throw new TypeError('cues must be an array');
+    if (cues.length > maxCues)
+        throw new RangeError('cue count exceeds maxCues');
+    for (const [i, cue] of cues.entries()) {
+        if (typeof cue !== 'object' || cue === null)
+            throw new TypeError(`cues[${i}] must be an object`);
+        const c = cue;
+        const start = time(`cues[${i}].startMs`, c.startMs, 0);
+        const end = time(`cues[${i}].endMs`, c.endMs, 0);
+        if (end <= start)
+            throw new RangeError(`cues[${i}] must end after it starts`);
+        if (typeof c.text !== 'string')
+            throw new TypeError(`cues[${i}].text must be a string`);
+        if (c.id !== undefined && typeof c.id !== 'string')
+            throw new TypeError(`cues[${i}].id must be a string`);
+    }
+    return cues;
+}
+function make(cue, startMs, endMs, id) {
+    const resultId = id ?? cue.id;
+    return resultId === undefined
+        ? { startMs, endMs, text: cue.text }
+        : { id: resultId, startMs, endMs, text: cue.text };
+}
+function policy(value) {
+    const chosen = value === undefined ? 'error' : value;
+    if (chosen !== 'error' && chosen !== 'clip' && chosen !== 'drop')
+        throw new TypeError('unknown negative policy');
+    return chosen;
+}
+function applyNegative(cue, start, end, negative) {
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end))
+        throw new RangeError('time is not a safe integer');
+    if (start >= 0)
+        return make(cue, start, end);
+    if (negative === 'error')
+        throw new RangeError('cue would start before 0');
+    if (negative === 'drop' || end <= 0)
+        return undefined;
+    return make(cue, 0, end);
+}
+/** Adds deltaMs to every cue; the input array and cues are not modified. */
+function shiftCues(cues, deltaMs, options = {}) {
+    const input = readCues(cues, exports.DEFAULT_MAX_CUES);
+    if (typeof deltaMs !== 'number' || !Number.isSafeInteger(deltaMs))
+        throw new RangeError('deltaMs must be a safe integer');
+    const negative = policy(options.negative);
+    const result = [];
+    for (const cue of input) {
+        const shifted = applyNegative(cue, cue.startMs + deltaMs, cue.endMs + deltaMs, negative);
+        if (shifted)
+            result.push(shifted);
+    }
+    return result;
+}
+/** Maps t to anchor + (t - anchor) * factor, rounded; a cue that collapses to zero length is an error. */
+function scaleCues(cues, factor, options = {}) {
+    const input = readCues(cues, exports.DEFAULT_MAX_CUES);
+    if (typeof factor !== 'number' || !Number.isFinite(factor) || factor <= 0) {
+        throw new RangeError('factor must be a positive finite number');
+    }
+    const anchor = options.anchorMs === undefined ? 0 : time('anchorMs', options.anchorMs, 0);
+    const rounding = options.rounding ?? 'round';
+    const round = rounding === 'round'
+        ? Math.round
+        : rounding === 'floor'
+            ? Math.floor
+            : rounding === 'ceil'
+                ? Math.ceil
+                : undefined;
+    if (!round)
+        throw new TypeError('unknown rounding');
+    const negative = policy(options.negative);
+    const map = (t) => round(anchor + (t - anchor) * factor);
+    const result = [];
+    for (const cue of input) {
+        const start = map(cue.startMs);
+        const end = map(cue.endMs);
+        if (end <= start && Number.isSafeInteger(start) && Number.isSafeInteger(end)) {
+            throw new RangeError('scaled cue has no positive duration');
+        }
+        const scaled = applyNegative(cue, start, end, negative);
+        if (scaled)
+            result.push(scaled);
+    }
+    return result;
+}
+/** Splits at strictly increasing interior times. Pieces get ids `${id}#1`, `${id}#2`, ... when the cue has an id. */
+function splitCue(cue, atMs, texts) {
+    const [checked] = readCues([cue], 1);
+    if (!Array.isArray(atMs) || atMs.length === 0)
+        throw new TypeError('atMs must be a non-empty array');
+    let previous = checked.startMs;
+    for (const [i, at] of atMs.entries()) {
+        time(`atMs[${i}]`, at, 0);
+        if (at <= previous || at >= checked.endMs)
+            throw new RangeError(`atMs[${i}] must be increasing and inside the cue`);
+        previous = at;
+    }
+    if (texts !== undefined) {
+        if (!Array.isArray(texts) ||
+            texts.length !== atMs.length + 1 ||
+            texts.some((t) => typeof t !== 'string')) {
+            throw new TypeError('texts must contain one string per piece');
+        }
+    }
+    const bounds = [checked.startMs, ...atMs, checked.endMs];
+    return bounds.slice(0, -1).map((start, i) => {
+        const piece = make(checked, start, bounds[i + 1], checked.id === undefined ? undefined : `${checked.id}#${i + 1}`);
+        return texts ? { ...piece, text: texts[i] } : piece;
+    });
+}
+/** Intersects cues with [windowStartMs, windowEndMs); cues with no remaining duration are removed. */
+function clipCues(cues, windowStartMs, windowEndMs, options = {}) {
+    const input = readCues(cues, limit('maxCues', options.maxCues, exports.DEFAULT_MAX_CUES));
+    const from = time('windowStartMs', windowStartMs, 0);
+    const to = time('windowEndMs', windowEndMs, 0);
+    if (to <= from)
+        throw new RangeError('window must have positive duration');
+    const offset = options.rebase === true ? from : 0;
+    const result = [];
+    for (const cue of input) {
+        const start = Math.max(cue.startMs, from);
+        const end = Math.min(cue.endMs, to);
+        if (end > start)
+            result.push(make(cue, start - offset, end - offset));
+    }
+    return result;
+}
+/** Stable sort by start then end; returns new cue objects. */
+function sortCues(cues) {
+    return readCues(cues, exports.DEFAULT_MAX_CUES)
+        .map((cue, index) => ({ cue, index }))
+        .sort((a, b) => a.cue.startMs - b.cue.startMs || a.cue.endMs - b.cue.endMs || a.index - b.index)
+        .map(({ cue }) => make(cue, cue.startMs, cue.endMs));
+}
+/** All pairs that share positive duration (touching cues do not overlap), ordered by (first, second). */
+function findOverlaps(cues, options = {}) {
+    const input = readCues(cues, limit('maxCues', options.maxCues, exports.DEFAULT_MAX_CUES));
+    const maxPairs = limit('maxPairs', options.maxPairs, exports.DEFAULT_MAX_PAIRS);
+    const order = input
+        .map((_, i) => i)
+        .sort((a, b) => input[a].startMs - input[b].startMs || a - b);
+    const active = [];
+    const found = [];
+    for (const index of order) {
+        const cue = input[index];
+        for (let k = active.length - 1; k >= 0; k--) {
+            if (input[active[k]].endMs <= cue.startMs)
+                active.splice(k, 1);
+        }
+        for (const other of active) {
+            if (found.length >= maxPairs)
+                throw new RangeError('overlap pairs exceed maxPairs');
+            const o = input[other];
+            found.push({
+                first: Math.min(index, other),
+                second: Math.max(index, other),
+                startMs: Math.max(o.startMs, cue.startMs),
+                endMs: Math.min(o.endMs, cue.endMs),
+            });
+        }
+        active.push(index);
+    }
+    return found.sort((a, b) => a.first - b.first || a.second - b.second);
+}
+/** Sorts by start and removes overlaps against the previously kept cue; empty results are dropped. */
+function resolveOverlaps(cues, overlapPolicy) {
+    if (overlapPolicy !== 'trim-previous' && overlapPolicy !== 'push-next')
+        throw new TypeError('unknown overlap policy');
+    const kept = [];
+    for (const cue of sortCues(cues)) {
+        const previous = kept[kept.length - 1];
+        if (previous && cue.startMs < previous.endMs) {
+            if (overlapPolicy === 'trim-previous') {
+                previous.endMs = cue.startMs;
+                if (previous.endMs <= previous.startMs)
+                    kept.pop();
+            }
+            else {
+                if (previous.endMs >= cue.endMs)
+                    continue;
+                cue.startMs = previous.endMs;
+            }
+        }
+        kept.push(cue);
+    }
+    return kept;
+}
+/** Union of cue time as sorted disjoint intervals; touching intervals are merged. */
+function mergeIntervals(cues, options = {}) {
+    const input = readCues(cues, limit('maxCues', options.maxCues, exports.DEFAULT_MAX_CUES));
+    const sorted = input
+        .map((c) => ({ startMs: c.startMs, endMs: c.endMs }))
+        .sort((a, b) => a.startMs - b.startMs);
+    const merged = [];
+    for (const interval of sorted) {
+        const last = merged[merged.length - 1];
+        if (last && interval.startMs <= last.endMs)
+            last.endMs = Math.max(last.endMs, interval.endMs);
+        else
+            merged.push(interval);
+    }
+    return merged;
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/index.d.ts

@@ -0,0 +1,57 @@
+export interface Cue {
+    id?: string;
+    /** Inclusive start in integer milliseconds (>= 0). */
+    startMs: number;
+    /** Exclusive end in integer milliseconds (> startMs). */
+    endMs: number;
+    text: string;
+}
+export type NegativePolicy = 'error' | 'clip' | 'drop';
+export type TimeRounding = 'round' | 'floor' | 'ceil';
+export type OverlapPolicy = 'trim-previous' | 'push-next';
+export interface ShiftOptions {
+    /** What to do when a shifted cue starts before 0. Default 'error'. */
+    negative?: NegativePolicy;
+}
+export interface ScaleOptions extends ShiftOptions {
+    /** Time that stays fixed while scaling. Default 0. */
+    anchorMs?: number;
+    rounding?: TimeRounding;
+}
+export interface Interval {
+    startMs: number;
+    endMs: number;
+}
+export interface Overlap extends Interval {
+    /** Indices into the supplied array, first < second. */
+    first: number;
+    second: number;
+}
+export interface LimitOptions {
+    maxCues?: number;
+}
+export interface OverlapSearchOptions extends LimitOptions {
+    maxPairs?: number;
+}
+export interface ClipOptions extends LimitOptions {
+    /** Subtract windowStartMs from kept cues. Default false. */
+    rebase?: boolean;
+}
+export declare const DEFAULT_MAX_CUES = 100000;
+export declare const DEFAULT_MAX_PAIRS = 100000;
+/** Adds deltaMs to every cue; the input array and cues are not modified. */
+export declare function shiftCues(cues: readonly Cue[], deltaMs: number, options?: ShiftOptions): Cue[];
+/** Maps t to anchor + (t - anchor) * factor, rounded; a cue that collapses to zero length is an error. */
+export declare function scaleCues(cues: readonly Cue[], factor: number, options?: ScaleOptions): Cue[];
+/** Splits at strictly increasing interior times. Pieces get ids `${id}#1`, `${id}#2`, ... when the cue has an id. */
+export declare function splitCue(cue: Cue, atMs: readonly number[], texts?: readonly string[]): Cue[];
+/** Intersects cues with [windowStartMs, windowEndMs); cues with no remaining duration are removed. */
+export declare function clipCues(cues: readonly Cue[], windowStartMs: number, windowEndMs: number, options?: ClipOptions): Cue[];
+/** Stable sort by start then end; returns new cue objects. */
+export declare function sortCues(cues: readonly Cue[]): Cue[];
+/** All pairs that share positive duration (touching cues do not overlap), ordered by (first, second). */
+export declare function findOverlaps(cues: readonly Cue[], options?: OverlapSearchOptions): Overlap[];
+/** Sorts by start and removes overlaps against the previously kept cue; empty results are dropped. */
+export declare function resolveOverlaps(cues: readonly Cue[], overlapPolicy: OverlapPolicy): Cue[];
+/** Union of cue time as sorted disjoint intervals; touching intervals are merged. */
+export declare function mergeIntervals(cues: readonly Cue[], options?: LimitOptions): Interval[];

package/dist/esm/index.js

@@ -0,0 +1,218 @@
+export const DEFAULT_MAX_CUES = 100_000;
+export const DEFAULT_MAX_PAIRS = 100_000;
+function time(name, value, min) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < min) {
+        throw new RangeError(`${name} must be a safe integer >= ${min}`);
+    }
+    return value;
+}
+function limit(name, value, fallback) {
+    return value === undefined ? fallback : time(name, value, 0);
+}
+function readCues(cues, maxCues) {
+    if (!Array.isArray(cues))
+        throw new TypeError('cues must be an array');
+    if (cues.length > maxCues)
+        throw new RangeError('cue count exceeds maxCues');
+    for (const [i, cue] of cues.entries()) {
+        if (typeof cue !== 'object' || cue === null)
+            throw new TypeError(`cues[${i}] must be an object`);
+        const c = cue;
+        const start = time(`cues[${i}].startMs`, c.startMs, 0);
+        const end = time(`cues[${i}].endMs`, c.endMs, 0);
+        if (end <= start)
+            throw new RangeError(`cues[${i}] must end after it starts`);
+        if (typeof c.text !== 'string')
+            throw new TypeError(`cues[${i}].text must be a string`);
+        if (c.id !== undefined && typeof c.id !== 'string')
+            throw new TypeError(`cues[${i}].id must be a string`);
+    }
+    return cues;
+}
+function make(cue, startMs, endMs, id) {
+    const resultId = id ?? cue.id;
+    return resultId === undefined
+        ? { startMs, endMs, text: cue.text }
+        : { id: resultId, startMs, endMs, text: cue.text };
+}
+function policy(value) {
+    const chosen = value === undefined ? 'error' : value;
+    if (chosen !== 'error' && chosen !== 'clip' && chosen !== 'drop')
+        throw new TypeError('unknown negative policy');
+    return chosen;
+}
+function applyNegative(cue, start, end, negative) {
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end))
+        throw new RangeError('time is not a safe integer');
+    if (start >= 0)
+        return make(cue, start, end);
+    if (negative === 'error')
+        throw new RangeError('cue would start before 0');
+    if (negative === 'drop' || end <= 0)
+        return undefined;
+    return make(cue, 0, end);
+}
+/** Adds deltaMs to every cue; the input array and cues are not modified. */
+export function shiftCues(cues, deltaMs, options = {}) {
+    const input = readCues(cues, DEFAULT_MAX_CUES);
+    if (typeof deltaMs !== 'number' || !Number.isSafeInteger(deltaMs))
+        throw new RangeError('deltaMs must be a safe integer');
+    const negative = policy(options.negative);
+    const result = [];
+    for (const cue of input) {
+        const shifted = applyNegative(cue, cue.startMs + deltaMs, cue.endMs + deltaMs, negative);
+        if (shifted)
+            result.push(shifted);
+    }
+    return result;
+}
+/** Maps t to anchor + (t - anchor) * factor, rounded; a cue that collapses to zero length is an error. */
+export function scaleCues(cues, factor, options = {}) {
+    const input = readCues(cues, DEFAULT_MAX_CUES);
+    if (typeof factor !== 'number' || !Number.isFinite(factor) || factor <= 0) {
+        throw new RangeError('factor must be a positive finite number');
+    }
+    const anchor = options.anchorMs === undefined ? 0 : time('anchorMs', options.anchorMs, 0);
+    const rounding = options.rounding ?? 'round';
+    const round = rounding === 'round'
+        ? Math.round
+        : rounding === 'floor'
+            ? Math.floor
+            : rounding === 'ceil'
+                ? Math.ceil
+                : undefined;
+    if (!round)
+        throw new TypeError('unknown rounding');
+    const negative = policy(options.negative);
+    const map = (t) => round(anchor + (t - anchor) * factor);
+    const result = [];
+    for (const cue of input) {
+        const start = map(cue.startMs);
+        const end = map(cue.endMs);
+        if (end <= start && Number.isSafeInteger(start) && Number.isSafeInteger(end)) {
+            throw new RangeError('scaled cue has no positive duration');
+        }
+        const scaled = applyNegative(cue, start, end, negative);
+        if (scaled)
+            result.push(scaled);
+    }
+    return result;
+}
+/** Splits at strictly increasing interior times. Pieces get ids `${id}#1`, `${id}#2`, ... when the cue has an id. */
+export function splitCue(cue, atMs, texts) {
+    const [checked] = readCues([cue], 1);
+    if (!Array.isArray(atMs) || atMs.length === 0)
+        throw new TypeError('atMs must be a non-empty array');
+    let previous = checked.startMs;
+    for (const [i, at] of atMs.entries()) {
+        time(`atMs[${i}]`, at, 0);
+        if (at <= previous || at >= checked.endMs)
+            throw new RangeError(`atMs[${i}] must be increasing and inside the cue`);
+        previous = at;
+    }
+    if (texts !== undefined) {
+        if (!Array.isArray(texts) ||
+            texts.length !== atMs.length + 1 ||
+            texts.some((t) => typeof t !== 'string')) {
+            throw new TypeError('texts must contain one string per piece');
+        }
+    }
+    const bounds = [checked.startMs, ...atMs, checked.endMs];
+    return bounds.slice(0, -1).map((start, i) => {
+        const piece = make(checked, start, bounds[i + 1], checked.id === undefined ? undefined : `${checked.id}#${i + 1}`);
+        return texts ? { ...piece, text: texts[i] } : piece;
+    });
+}
+/** Intersects cues with [windowStartMs, windowEndMs); cues with no remaining duration are removed. */
+export function clipCues(cues, windowStartMs, windowEndMs, options = {}) {
+    const input = readCues(cues, limit('maxCues', options.maxCues, DEFAULT_MAX_CUES));
+    const from = time('windowStartMs', windowStartMs, 0);
+    const to = time('windowEndMs', windowEndMs, 0);
+    if (to <= from)
+        throw new RangeError('window must have positive duration');
+    const offset = options.rebase === true ? from : 0;
+    const result = [];
+    for (const cue of input) {
+        const start = Math.max(cue.startMs, from);
+        const end = Math.min(cue.endMs, to);
+        if (end > start)
+            result.push(make(cue, start - offset, end - offset));
+    }
+    return result;
+}
+/** Stable sort by start then end; returns new cue objects. */
+export function sortCues(cues) {
+    return readCues(cues, DEFAULT_MAX_CUES)
+        .map((cue, index) => ({ cue, index }))
+        .sort((a, b) => a.cue.startMs - b.cue.startMs || a.cue.endMs - b.cue.endMs || a.index - b.index)
+        .map(({ cue }) => make(cue, cue.startMs, cue.endMs));
+}
+/** All pairs that share positive duration (touching cues do not overlap), ordered by (first, second). */
+export function findOverlaps(cues, options = {}) {
+    const input = readCues(cues, limit('maxCues', options.maxCues, DEFAULT_MAX_CUES));
+    const maxPairs = limit('maxPairs', options.maxPairs, DEFAULT_MAX_PAIRS);
+    const order = input
+        .map((_, i) => i)
+        .sort((a, b) => input[a].startMs - input[b].startMs || a - b);
+    const active = [];
+    const found = [];
+    for (const index of order) {
+        const cue = input[index];
+        for (let k = active.length - 1; k >= 0; k--) {
+            if (input[active[k]].endMs <= cue.startMs)
+                active.splice(k, 1);
+        }
+        for (const other of active) {
+            if (found.length >= maxPairs)
+                throw new RangeError('overlap pairs exceed maxPairs');
+            const o = input[other];
+            found.push({
+                first: Math.min(index, other),
+                second: Math.max(index, other),
+                startMs: Math.max(o.startMs, cue.startMs),
+                endMs: Math.min(o.endMs, cue.endMs),
+            });
+        }
+        active.push(index);
+    }
+    return found.sort((a, b) => a.first - b.first || a.second - b.second);
+}
+/** Sorts by start and removes overlaps against the previously kept cue; empty results are dropped. */
+export function resolveOverlaps(cues, overlapPolicy) {
+    if (overlapPolicy !== 'trim-previous' && overlapPolicy !== 'push-next')
+        throw new TypeError('unknown overlap policy');
+    const kept = [];
+    for (const cue of sortCues(cues)) {
+        const previous = kept[kept.length - 1];
+        if (previous && cue.startMs < previous.endMs) {
+            if (overlapPolicy === 'trim-previous') {
+                previous.endMs = cue.startMs;
+                if (previous.endMs <= previous.startMs)
+                    kept.pop();
+            }
+            else {
+                if (previous.endMs >= cue.endMs)
+                    continue;
+                cue.startMs = previous.endMs;
+            }
+        }
+        kept.push(cue);
+    }
+    return kept;
+}
+/** Union of cue time as sorted disjoint intervals; touching intervals are merged. */
+export function mergeIntervals(cues, options = {}) {
+    const input = readCues(cues, limit('maxCues', options.maxCues, DEFAULT_MAX_CUES));
+    const sorted = input
+        .map((c) => ({ startMs: c.startMs, endMs: c.endMs }))
+        .sort((a, b) => a.startMs - b.startMs);
+    const merged = [];
+    for (const interval of sorted) {
+        const last = merged[merged.length - 1];
+        if (last && interval.startMs <= last.endMs)
+            last.endMs = Math.max(last.endMs, interval.endMs);
+        else
+            merged.push(interval);
+    }
+    return merged;
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@lp-labs/subtitle-timing",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Subtitle cue shift, scale, split, clip, overlap and interval operations on millisecond times.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "npm run build && node scripts/check-types.mjs",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "format": "prettier --write src scripts tests *.json README.md",
+    "format:check": "prettier --check src scripts tests *.json README.md",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "prettier": "^3.6.2"
+  },
+  "prettier": {
+    "singleQuote": true,
+    "semi": true,
+    "trailingComma": "all",
+    "printWidth": 100,
+    "endOfLine": "lf"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": {
+    "name": "Libin Prasanth",
+    "url": "https://www.linkedin.com/in/libinprasanth/"
+  },
+  "funding": {
+    "type": "paypal",
+    "url": "https://www.paypal.me/LibinPrasanth"
+  }
+}