videobook 0.0.0-stage → 0.2.0

package/dist/watermark-badge.js

@@ -0,0 +1,259 @@
+import sharp from "sharp";
+import QRCode from "qrcode";
+import { WATERMARK_LOGO_PATHS, watermarkProfileUrl } from "./watermark-platform.js";
+import { writeImageVariants } from "./tools/concat-images.js";
+export const DEFAULT_HANDLE = "justinwtanner";
+// Layout identifier persisted in artifact metadata so apply_watermark can
+// reuse an existing badge and skip regenerating an identical one.
+export const WATERMARK_BADGE_LAYOUT = "badge-v6";
+const WATERMARK_HANDLE_LAYOUT = "handle-v5";
+const WATERMARK_QR_LAYOUT = "qr-v1";
+export const BADGE_WIDTH = 480;
+const QR_SIZE = 384;
+const TILE_PAD = 48; // white frame around the QR — ≥4 quiet-zone modules up to QR v5
+const TILE_SIZE = QR_SIZE + TILE_PAD * 2; // 480
+const PILL_GAP = 12;
+const PILL_HEIGHT = 88;
+const HANDLE_PILL_CONTENT = 26;
+export const BADGE_HEIGHT = TILE_SIZE + PILL_GAP + PILL_HEIGHT; // 580
+export const BADGE_ASPECT = BADGE_WIDTH / BADGE_HEIGHT;
+export const QR_ONLY_BADGE_HEIGHT = TILE_SIZE;
+export const QR_ONLY_BADGE_ASPECT = BADGE_WIDTH / QR_ONLY_BADGE_HEIGHT;
+export const HANDLE_ONLY_BADGE_HEIGHT = PILL_HEIGHT;
+export const DEFAULT_HANDLE_PADDING = 32;
+export const MIN_HANDLE_PADDING = 0;
+export const MAX_HANDLE_PADDING = 96;
+export const DEFAULT_HANDLE_ROUNDING = 100;
+export const MIN_HANDLE_ROUNDING = 0;
+export const MAX_HANDLE_ROUNDING = 100;
+export function defaultUrl(handle, platform = "x") {
+    return watermarkProfileUrl(handle, platform);
+}
+export function watermarkHandleLabel(handle) {
+    return handle.replace(/^@/, "");
+}
+function clampHandlePadding(value) {
+    if (!Number.isFinite(value))
+        return DEFAULT_HANDLE_PADDING;
+    return Math.round(Math.min(MAX_HANDLE_PADDING, Math.max(MIN_HANDLE_PADDING, value)));
+}
+export function handlePillHeight(paddingY = DEFAULT_HANDLE_PADDING) {
+    const clamped = clampHandlePadding(paddingY);
+    return Math.max(HANDLE_PILL_CONTENT + 4, PILL_HEIGHT + 2 * (clamped - DEFAULT_HANDLE_PADDING));
+}
+function watermarkCombinedBadgeHeight(paddingY = DEFAULT_HANDLE_PADDING) {
+    return TILE_SIZE + PILL_GAP + handlePillHeight(paddingY);
+}
+function clampHandleRounding(value) {
+    if (!Number.isFinite(value))
+        return DEFAULT_HANDLE_ROUNDING;
+    return Math.round(Math.min(MAX_HANDLE_ROUNDING, Math.max(MIN_HANDLE_ROUNDING, value)));
+}
+function escapeXml(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+export function watermarkBadgeAspect(includeQr = true, paddingY = DEFAULT_HANDLE_PADDING) {
+    return BADGE_WIDTH / (includeQr ? watermarkCombinedBadgeHeight(paddingY) : handlePillHeight(paddingY));
+}
+function watermarkBadgeVariant(options) {
+    return options.variant ?? (options.includeQr === false ? "handle" : "combined");
+}
+function watermarkBadgeLayout(variant) {
+    if (variant === "qr")
+        return WATERMARK_QR_LAYOUT;
+    return variant === "combined" ? WATERMARK_BADGE_LAYOUT : WATERMARK_HANDLE_LAYOUT;
+}
+function watermarkBadgeHeight(variant, paddingY) {
+    if (variant === "qr")
+        return QR_ONLY_BADGE_HEIGHT;
+    return variant === "combined"
+        ? watermarkCombinedBadgeHeight(paddingY)
+        : handlePillHeight(paddingY);
+}
+export async function buildWatermarkBadgePng(url, handle, options = {}) {
+    const platform = options.platform ?? "x";
+    const variant = watermarkBadgeVariant(options);
+    const includeQr = variant !== "handle";
+    const includeHandle = variant !== "qr";
+    const includePlatformIcon = includeHandle && (options.includePlatformIcon ?? options.includeXIcon ?? true);
+    const includeHandleBorder = includeHandle && (options.includeHandleBorder ?? true);
+    const handlePadding = clampHandlePadding(options.handlePadding ?? DEFAULT_HANDLE_PADDING);
+    const handlePaddingY = clampHandlePadding(options.handlePaddingY ?? DEFAULT_HANDLE_PADDING);
+    const handleRounding = clampHandleRounding(options.handleRounding ?? DEFAULT_HANDLE_ROUNDING);
+    const qrBuffer = includeQr
+        ? await QRCode.toBuffer(url, {
+            type: "png",
+            margin: 0,
+            color: { dark: "#0B0B0F", light: "#FFFFFF" },
+            errorCorrectionLevel: "H",
+            width: QR_SIZE,
+        })
+        : null;
+    const pillHeight = handlePillHeight(handlePaddingY);
+    const badgeHeight = watermarkBadgeHeight(variant, handlePaddingY);
+    const pillY = variant === "combined" ? TILE_SIZE + PILL_GAP : 0;
+    const label = watermarkHandleLabel(handle);
+    const iconSize = HANDLE_PILL_CONTENT;
+    const iconGap = 14;
+    const iconSpace = includePlatformIcon ? iconSize + iconGap : 0;
+    const availableWidth = BADGE_WIDTH - 2 - handlePadding * 2 - iconSpace;
+    const fontSize = Math.max(12, Math.min(28, Math.floor(availableWidth / (0.6 * Math.max(1, Array.from(label).length)))));
+    // Font fallback changes SVG baseline metrics between macOS and Linux.
+    // Place the painted glyph bounds in the pill, independent of those metrics.
+    const labelSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="${BADGE_WIDTH}" height="${fontSize * 3}">
+    <text x="${BADGE_WIDTH / 2}" y="${fontSize * 2}" text-anchor="middle" font-family="Helvetica, Arial, sans-serif" font-size="${fontSize}" font-weight="700" letter-spacing="0.1" fill="#FFFFFF">${escapeXml(label)}</text>
+  </svg>`;
+    const labelPixels = includeHandle && label.trim()
+        ? await sharp(Buffer.from(labelSvg)).trim({ threshold: 1, lineArt: true }).png().toBuffer()
+        : null;
+    const labelImage = labelPixels
+        ? await sharp(labelPixels).resize({
+            width: Math.floor(availableWidth),
+            height: HANDLE_PILL_CONTENT,
+            fit: "inside",
+            withoutEnlargement: true,
+        }).png().toBuffer({ resolveWithObject: true })
+        : null;
+    const labelWidth = labelImage?.info.width ?? 0;
+    const contentWidth = iconSpace + labelWidth;
+    const contentX = (BADGE_WIDTH - contentWidth) / 2;
+    const pillWidth = Math.min(BADGE_WIDTH - 2, Math.ceil(contentWidth + handlePadding * 2));
+    const pillX = (BADGE_WIDTH - pillWidth) / 2;
+    const logoY = pillY + (pillHeight - iconSize) / 2;
+    const pillRadius = ((pillHeight - 2) / 2) * (handleRounding / 100);
+    const border = includeHandleBorder
+        ? ` stroke="#FFFFFF" stroke-opacity="0.55" stroke-width="2"`
+        : "";
+    const tile = includeQr
+        ? `<rect x="0" y="0" width="${TILE_SIZE}" height="${TILE_SIZE}" rx="40" fill="#FFFFFF"/>`
+        : "";
+    const pill = includeHandle
+        ? `<rect x="${pillX}" y="${pillY + 1}" width="${pillWidth}" height="${pillHeight - 2}" rx="${pillRadius}" fill="#0B0B0F" fill-opacity="0.92"${border}/>
+  ${includePlatformIcon ? `<svg x="${contentX}" y="${logoY}" width="${iconSize}" height="${iconSize}" viewBox="0 0 24 24"><path d="${WATERMARK_LOGO_PATHS[platform]}" fill="#FFFFFF"/></svg>` : ""}`
+        : "";
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${BADGE_WIDTH}" height="${badgeHeight}" viewBox="0 0 ${BADGE_WIDTH} ${badgeHeight}">
+  ${tile}
+  ${pill}
+</svg>`;
+    const background = await sharp(Buffer.from(svg)).png().toBuffer();
+    const layers = [];
+    if (qrBuffer)
+        layers.push({ input: qrBuffer, top: TILE_PAD, left: TILE_PAD });
+    if (labelImage)
+        layers.push({
+            input: labelImage.data,
+            left: Math.round(contentX + iconSpace),
+            top: pillY + Math.round((pillHeight - labelImage.info.height) / 2),
+        });
+    if (layers.length === 0)
+        return background;
+    return sharp(background)
+        .composite(layers)
+        .png()
+        .toBuffer();
+}
+/** Build the badge and persist it as an image artifact with preview variants. */
+export async function createWatermarkAsset(engine, handle, url, options = {}) {
+    const platform = options.platform ?? "x";
+    const variant = watermarkBadgeVariant(options);
+    const includePlatformIcon = options.includePlatformIcon ?? options.includeXIcon ?? true;
+    const includeHandleBorder = options.includeHandleBorder ?? true;
+    const handlePadding = clampHandlePadding(options.handlePadding ?? DEFAULT_HANDLE_PADDING);
+    const handlePaddingY = clampHandlePadding(options.handlePaddingY ?? DEFAULT_HANDLE_PADDING);
+    const handleRounding = clampHandleRounding(options.handleRounding ?? DEFAULT_HANDLE_ROUNDING);
+    let buffer;
+    try {
+        buffer = await buildWatermarkBadgePng(url, handle, {
+            variant,
+            platform,
+            includePlatformIcon,
+            includeHandleBorder,
+            handlePadding,
+            handlePaddingY,
+            handleRounding,
+        });
+    }
+    catch (err) {
+        return { ok: false, error: `Failed to build watermark card: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    const assetIdentity = handle.toLowerCase().replace(/[^a-z0-9]+/g, "-") || "link";
+    const assetName = `watermark-${variant}-${assetIdentity}-${Date.now().toString(36)}`;
+    const created = await engine.artifacts.create("img", assetName);
+    if (!created.ok) {
+        return { ok: false, error: `Failed to create image asset: ${created.error.message}` };
+    }
+    const assetId = created.value.artifactId;
+    const writeResult = await engine.files.write(assetId, "original.png", buffer);
+    if (!writeResult.ok) {
+        await engine.artifacts.delete(assetId).catch(() => undefined);
+        return { ok: false, error: writeResult.error.message };
+    }
+    const metadataResult = await engine.metadata.artifacts.write(assetId, "original", {
+        origin: "watermark",
+        layout: watermarkBadgeLayout(variant),
+        created_at: new Date().toISOString(),
+        handle,
+        url,
+        platform,
+        include_qr: variant !== "handle",
+        include_handle: variant !== "qr",
+        include_platform_icon: variant !== "qr" && includePlatformIcon,
+        include_x_icon: variant !== "qr" && platform === "x" && includePlatformIcon,
+        include_handle_border: variant !== "qr" && includeHandleBorder,
+        handle_padding: variant !== "qr" ? handlePadding : null,
+        handle_padding_y: variant !== "qr" ? handlePaddingY : null,
+        handle_rounding: variant !== "qr" ? handleRounding : null,
+        width: BADGE_WIDTH,
+        height: watermarkBadgeHeight(variant, handlePaddingY),
+    });
+    if (!metadataResult.ok) {
+        await engine.artifacts.delete(assetId).catch(() => undefined);
+        return { ok: false, error: metadataResult.error.message };
+    }
+    const variantsResult = await writeImageVariants(engine, assetId, buffer);
+    if (!variantsResult.ok) {
+        await engine.artifacts.delete(assetId).catch(() => undefined);
+        return { ok: false, error: variantsResult.error };
+    }
+    return { ok: true, assetId };
+}
+/** Find an existing badge artifact for this handle + url (same layout), so
+ *  repeated applies share one card instead of minting duplicates. */
+export async function findWatermarkAsset(engine, handle, url, options = {}) {
+    const platform = options.platform ?? "x";
+    const variant = watermarkBadgeVariant(options);
+    const layout = watermarkBadgeLayout(variant);
+    const includePlatformIcon = options.includePlatformIcon ?? options.includeXIcon ?? true;
+    const includeHandleBorder = options.includeHandleBorder ?? true;
+    const handlePadding = clampHandlePadding(options.handlePadding ?? DEFAULT_HANDLE_PADDING);
+    const handlePaddingY = clampHandlePadding(options.handlePaddingY ?? DEFAULT_HANDLE_PADDING);
+    const handleRounding = clampHandleRounding(options.handleRounding ?? DEFAULT_HANDLE_ROUNDING);
+    for (const artifact of engine.artifacts.list()) {
+        if (artifact.kind !== "image")
+            continue;
+        const meta = await engine.metadata.artifacts.read(artifact.artifactId, "original");
+        if (!meta.ok)
+            continue;
+        const storedPaddingY = typeof meta.value.handle_padding_y === "number"
+            ? meta.value.handle_padding_y
+            : DEFAULT_HANDLE_PADDING;
+        if (meta.value.origin === "watermark"
+            && meta.value.layout === layout
+            && (meta.value.platform ?? "x") === platform
+            && meta.value.handle === handle
+            && (variant === "handle" || meta.value.url === url)
+            && (variant === "qr" || (meta.value.include_platform_icon ?? meta.value.include_x_icon) === includePlatformIcon)
+            && (variant === "qr" || meta.value.include_handle_border === includeHandleBorder)
+            && (variant === "qr" || meta.value.handle_padding === handlePadding)
+            && (variant === "qr" || storedPaddingY === handlePaddingY)
+            && (variant === "qr" || meta.value.handle_rounding === handleRounding)) {
+            return artifact.artifactId;
+        }
+    }
+    return null;
+}

package/dist/watermark-config.js

@@ -0,0 +1,111 @@
+/**
+ * Persisted watermark handle preferences.
+ *
+ * The chat watermark review remembers the X handles you've used so it can default to
+ * your last-used (or explicitly saved) handle instead of asking every time. The
+ * authenticated user's handle is read live via @apicity/x's /2/users/me endpoint
+ * (see x/authenticated-handle.ts); `authenticatedHandle` below is a read-through
+ * cache so the review still pre-fills when the API is unreachable.
+ *
+ * Stored as unversioned application state in the main Dolt database.
+ */
+import { getActiveEngine } from "./queue.js";
+import { watermarkProfileFor } from "./lightning-defaults.js";
+const RECENT_LIMIT = 8;
+const EMPTY_CONFIG = { savedHandle: null, recent: [], authenticatedHandle: null };
+const SETTINGS_KEY = "application.watermark.v1";
+/** Trim surrounding whitespace then strip one leading @; empty string ⇒ null. */
+export function normalizeHandle(handle) {
+    const cleaned = handle.trim().replace(/^@/, "").trim();
+    return cleaned.length > 0 ? cleaned : null;
+}
+let writeChain = Promise.resolve();
+function serialize(fn) {
+    const next = writeChain.then(fn, fn);
+    writeChain = next.catch(() => { });
+    return next;
+}
+function settingsKey(platform) {
+    return platform === "x" ? SETTINGS_KEY : "application.watermark.tiktok.v1";
+}
+function readConfig(engine, platform = "x") {
+    const parsed = engine.settings.get(settingsKey(platform));
+    if (!parsed)
+        return { ...EMPTY_CONFIG };
+    const recent = Array.isArray(parsed.recent)
+        ? parsed.recent.filter((handle) => typeof handle === "string")
+        : [];
+    const savedHandle = typeof parsed.savedHandle === "string" ? parsed.savedHandle : null;
+    const authenticatedHandle = typeof parsed.authenticatedHandle === "string" ? parsed.authenticatedHandle : null;
+    const profile = parsed.profile && typeof parsed.profile === "object" && !Array.isArray(parsed.profile)
+        ? parsed.profile
+        : undefined;
+    return { savedHandle, recent, authenticatedHandle, ...(profile ? { profile } : {}) };
+}
+export function effectiveWatermarkProfile(config, platform) {
+    return watermarkProfileFor(platform, {
+        ...config.profile,
+        ...(config.savedHandle ? { handle: config.savedHandle } : {}),
+    });
+}
+export async function readWatermarkConfig(engine = getActiveEngine(), platform = "x") {
+    return readConfig(engine, platform);
+}
+function writeWatermarkConfig(engine, config, platform = "x") {
+    const written = engine.settings.set(settingsKey(platform), config);
+    if (!written.ok)
+        throw new Error(written.error.message);
+}
+/** Record a freshly-used handle: unshift into `recent` (case-insensitive dedup,
+ *  capped), and pin it as `savedHandle` when `saveDefault` is set. No-op for
+ *  blank handles. Returns the updated config. */
+export async function recordHandle(handle, opts = {}, engine = getActiveEngine()) {
+    const normalized = normalizeHandle(handle);
+    const platform = opts.platform ?? "x";
+    if (!normalized)
+        return readConfig(engine, platform);
+    return serialize(async () => {
+        const current = readConfig(engine, platform);
+        const deduped = current.recent.filter((h) => h.toLowerCase() !== normalized.toLowerCase());
+        const next = {
+            savedHandle: opts.saveDefault ? normalized : current.savedHandle,
+            recent: [normalized, ...deduped].slice(0, RECENT_LIMIT),
+            authenticatedHandle: current.authenticatedHandle,
+            ...(current.profile ? { profile: current.profile } : {}),
+        };
+        writeWatermarkConfig(engine, next, platform);
+        return next;
+    });
+}
+/** Cache the authenticated X handle (read-through fallback when the API is
+ *  unreachable). Pass null to clear. No-op when the value is unchanged. */
+export async function setAuthenticatedHandle(handle, engine = getActiveEngine()) {
+    const normalized = handle === null ? null : normalizeHandle(handle);
+    return serialize(async () => {
+        const current = readConfig(engine);
+        if (current.authenticatedHandle === normalized)
+            return current;
+        const next = {
+            savedHandle: current.savedHandle,
+            recent: current.recent,
+            authenticatedHandle: normalized,
+            ...(current.profile ? { profile: current.profile } : {}),
+        };
+        writeWatermarkConfig(engine, next);
+        return next;
+    });
+}
+export async function saveWatermarkProfile(profile, platform = "tiktok", engine = getActiveEngine()) {
+    return serialize(async () => {
+        const current = readConfig(engine, platform);
+        const handle = typeof profile.handle === "string" ? normalizeHandle(profile.handle) : null;
+        const next = {
+            savedHandle: handle ?? current.savedHandle,
+            recent: current.recent,
+            authenticatedHandle: current.authenticatedHandle,
+            profile: { ...current.profile, ...profile, ...(handle ? { handle } : {}) },
+        };
+        writeWatermarkConfig(engine, next, platform);
+        return next;
+    });
+}

package/dist/watermark-handle-position.js

@@ -0,0 +1,55 @@
+export const DEFAULT_HANDLE_VERTICAL_PERCENT = 33;
+export const MIN_HANDLE_VERTICAL_PERCENT = 10;
+export const MAX_HANDLE_VERTICAL_PERCENT = 90;
+export const WATERMARK_HANDLE_PLACEMENTS = [
+    "center",
+    "above-qr",
+    "on-qr",
+    "below-qr",
+];
+function clampHandleVerticalPercent(value) {
+    if (!Number.isFinite(value))
+        return DEFAULT_HANDLE_VERTICAL_PERCENT;
+    return Math.min(MAX_HANDLE_VERTICAL_PERCENT, Math.max(MIN_HANDLE_VERTICAL_PERCENT, value));
+}
+function watermarkHandleOverlayY(verticalPercent) {
+    const boundedPercent = clampHandleVerticalPercent(verticalPercent);
+    return `main_h*${boundedPercent}/100-overlay_h/2`;
+}
+function axisPosition(align, main, overlay, padding) {
+    if (align === "start")
+        return padding;
+    if (align === "end")
+        return main - overlay - padding;
+    return Math.round((main - overlay) / 2);
+}
+function watermarkQrOverlayPixels(corner, canvasWidth, canvasHeight, qrSize, padding) {
+    const [vertical, horizontal] = corner.split("-");
+    return {
+        x: axisPosition(horizontal === "left" ? "start" : horizontal === "right" ? "end" : "center", canvasWidth, qrSize, padding),
+        y: axisPosition(vertical === "top" ? "start" : vertical === "bottom" ? "end" : "center", canvasHeight, qrSize, padding),
+    };
+}
+function clampOverlayOrigin(value, main, overlay, padding) {
+    return Math.round(Math.min(main - overlay - padding, Math.max(padding, value)));
+}
+export function watermarkHandleOverlayPosition(options) {
+    if (options.placement === "center") {
+        return {
+            x: "(main_w-overlay_w)/2",
+            y: watermarkHandleOverlayY(options.handleVerticalPercent ?? DEFAULT_HANDLE_VERTICAL_PERCENT),
+        };
+    }
+    const qr = watermarkQrOverlayPixels(options.corner, options.canvasWidth, options.canvasHeight, options.qrSize, options.padding);
+    const gap = Math.max(2, Math.round(options.qrSize * 0.06));
+    const x = qr.x + (options.qrSize - options.handleWidth) / 2;
+    const y = options.placement === "above-qr"
+        ? qr.y - options.handleHeight - gap
+        : options.placement === "below-qr"
+            ? qr.y + options.qrSize + gap
+            : qr.y + (options.qrSize - options.handleHeight) / 2;
+    return {
+        x: String(clampOverlayOrigin(x, options.canvasWidth, options.handleWidth, options.padding)),
+        y: String(clampOverlayOrigin(y, options.canvasHeight, options.handleHeight, options.padding)),
+    };
+}

package/dist/watermark-platform.js

@@ -0,0 +1,15 @@
+export const WATERMARK_PLATFORMS = ["x", "tiktok"];
+export const WATERMARK_PLATFORM_LABELS = {
+    x: "X",
+    tiktok: "TikTok",
+};
+export const WATERMARK_LOGO_PATHS = {
+    x: "M18.901 1.153h3.68l-8.04 9.19L24 22.846h-7.406l-5.8-7.584-6.638 7.584H.474l8.6-9.83L0 1.154h7.594l5.243 6.932ZM17.61 20.644h2.039L6.486 3.24H4.298Z",
+    tiktok: "M12.525.02c1.31-.02 2.61-.01 3.91-.02.08 1.53.63 3.09 1.75 4.17 1.12 1.11 2.7 1.62 4.24 1.79v4.03c-1.44-.05-2.89-.35-4.2-.97-.57-.26-1.1-.59-1.62-.93-.01 2.92.01 5.84-.02 8.75-.08 1.4-.54 2.79-1.35 3.94-1.31 1.92-3.58 3.17-5.91 3.21-1.43.08-2.86-.31-4.08-1.03-2.02-1.19-3.44-3.37-3.65-5.71-.02-.5-.03-1-.01-1.49.18-1.9 1.12-3.72 2.58-4.96 1.66-1.44 3.98-2.13 6.15-1.72.02 1.48-.04 2.96-.04 4.44-.99-.32-2.15-.23-3.02.37-.63.41-1.11 1.04-1.36 1.75-.21.51-.15 1.07-.14 1.61.24 1.64 1.82 3.02 3.5 2.87 1.12-.01 2.19-.66 2.77-1.61.19-.33.4-.67.41-1.06.1-1.79.06-3.57.07-5.36.01-4.03-.01-8.05.02-12.07z",
+};
+export function watermarkProfileUrl(handle, platform = "x") {
+    return platform === "tiktok" ? `https://www.tiktok.com/@${handle}` : `https://x.com/${handle}`;
+}
+export function isWatermarkPlatform(value) {
+    return value === "x" || value === "tiktok";
+}

package/dist/watermark-timing.js

@@ -0,0 +1,16 @@
+export function effectiveWatermarkTiming(label, duration, startSeconds, endSeconds) {
+    if (!Number.isFinite(duration) || duration <= 0)
+        throw new Error("Video has no usable duration");
+    const effectiveStart = startSeconds ?? 0;
+    if (effectiveStart < 0 || effectiveStart >= duration) {
+        throw new Error(`${label} start must be before the ${duration.toFixed(2)}s clip end`);
+    }
+    const effectiveEnd = endSeconds === undefined ? undefined : Math.min(endSeconds, duration);
+    if (effectiveEnd !== undefined && effectiveEnd <= effectiveStart) {
+        throw new Error(`${label} end must be after its start`);
+    }
+    return {
+        ...(startSeconds !== undefined ? { startSeconds } : {}),
+        ...(effectiveEnd !== undefined ? { endSeconds: effectiveEnd } : {}),
+    };
+}