cursedbelt-core 1.0.0

package/src/core/media/segment.ts

@@ -0,0 +1,352 @@
+// Pure, dependency-free promptable image segmentation — the engine behind the
+// <MaskPainter>'s "auto-select" (Stage I, task 52). Given a source image's RGBA pixels
+// and a point/box prompt, it produces a BINARY alpha plane (0/255) marking the selected
+// object, which the painter lands as an EDITABLE mask region (never a final answer — the
+// owner refines or discards it). It is the object-select counterpart to {@link floodFillBGS}
+// (which clears an edge-connected BACKGROUND): both grow regions by color similarity, but
+// this one selects a FOREGROUND object from a user prompt and returns a mask, not an alpha.
+//
+// No DOM, no Bun, no npm dep — just typed pixel arrays — so it runs identically in the
+// browser, on a server (sharp's raw RGBA), and in unit tests, and is fully testable with no
+// canvas. The {@link ImageSegmenter} interface is the seam: the default region grower needs
+// no model download (instant, offline), and a heavier engine (SAM2-tiny / MobileSAM via
+// onnxruntime-web) can implement the SAME interface and drop in unchanged.
+
+/** A source image as raw RGBA pixels at its working dimensions. */
+export interface SegmentSource {
+  /** RGBA pixels, length `width * height * 4`. */
+  readonly data: Uint8ClampedArray;
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * What to select. `point` = magic-wand from a clicked pixel; `box` = the dominant object
+ * inside a dragged rectangle. Coordinates are in the SOURCE pixel space passed in `source`
+ * (the painter downscales both the image and the prompt together for large images).
+ */
+export type SegmentPrompt =
+  | { readonly type: 'point'; readonly x: number; readonly y: number }
+  | {
+      readonly type: 'box';
+      readonly x0: number;
+      readonly y0: number;
+      readonly x1: number;
+      readonly y1: number;
+    };
+
+export interface SegmentOptions {
+  /**
+   * Color-distance tolerance (RGB euclidean, 0–441) for region growth: a neighbor joins
+   * the region when it is within this distance of the seed color. Higher = looser (selects
+   * more, leaks across gradients sooner). Default {@link DEFAULT_TOLERANCE}. The painter maps
+   * a 0–100 "sensitivity" slider onto this via {@link sensitivityToTolerance}.
+   */
+  readonly tolerance?: number;
+  /**
+   * Morphological close radius (px) applied after growth to fill speckle + small holes and
+   * smooth the edge. 0 disables it. Default {@link DEFAULT_CLOSE_RADIUS}.
+   */
+  readonly closeRadius?: number;
+}
+
+/**
+ * A promptable image segmenter: `(source, prompt) → binary alpha plane (0/255)` at the
+ * source's dimensions, white where selected. `segment` may be sync (the pure region grower)
+ * or async (a model-backed engine); the painter always awaits it. `dispose` releases any
+ * held resources (e.g. an ONNX session) and is optional.
+ */
+export interface ImageSegmenter {
+  /** Stable identifier for diagnostics / telemetry (e.g. `'region-grow'`, `'mobile-sam'`). */
+  readonly id: string;
+  segment(
+    source: SegmentSource,
+    prompt: SegmentPrompt,
+    options?: SegmentOptions,
+  ): Uint8ClampedArray | Promise<Uint8ClampedArray>;
+  dispose?(): void;
+}
+
+export const DEFAULT_TOLERANCE = 28;
+export const DEFAULT_CLOSE_RADIUS = 2;
+
+/** Map a 0–100 "sensitivity" slider to a growth tolerance. 0 → tight (exact color), 100 →
+ *  loose. A gentle quadratic keeps the low end fine-grained where most clicks land. */
+export function sensitivityToTolerance(sensitivity: number): number {
+  const s = Math.max(0, Math.min(100, sensitivity)) / 100;
+  return Math.round(6 + s * s * 150); // ~6 (exact) … 156 (very loose)
+}
+
+// ── Region growth (the pure CV core) ───────────────────────────────────────────
+
+/** Flood a single connected region from `seed`, including 4-connected neighbors within
+ *  `tolSq` of the SEED color and inside the inclusive `bounds`. Returns a 0/255 mask. */
+function floodFrom(
+  data: Uint8ClampedArray,
+  width: number,
+  seed: readonly [number, number],
+  tolSq: number,
+  bounds: readonly [number, number, number, number],
+  out: Uint8ClampedArray,
+  visited: Uint8Array,
+  queue: Int32Array,
+): void {
+  const [bx0, by0, bx1, by1] = bounds;
+  const [sx, sy] = seed;
+  if (sx < bx0 || sy < by0 || sx > bx1 || sy > by1) return;
+  const seedIdx = sy * width + sx;
+  if (visited[seedIdx]) return;
+  const sr = data[seedIdx * 4];
+  const sg = data[seedIdx * 4 + 1];
+  const sb = data[seedIdx * 4 + 2];
+
+  let head = 0;
+  let tail = 0;
+  visited[seedIdx] = 1;
+  queue[tail++] = seedIdx;
+  while (head < tail) {
+    const idx = queue[head++];
+    out[idx] = 255;
+    const x = idx % width;
+    const y = (idx - x) / width;
+    for (let k = 0; k < 4; k++) {
+      let n: number;
+      if (k === 0) {
+        if (x <= bx0) continue;
+        n = idx - 1;
+      } else if (k === 1) {
+        if (x >= bx1) continue;
+        n = idx + 1;
+      } else if (k === 2) {
+        if (y <= by0) continue;
+        n = idx - width;
+      } else {
+        if (y >= by1) continue;
+        n = idx + width;
+      }
+      if (visited[n]) continue;
+      const dr = data[n * 4] - sr;
+      const dg = data[n * 4 + 1] - sg;
+      const db = data[n * 4 + 2] - sb;
+      if (dr * dr + dg * dg + db * db <= tolSq) {
+        visited[n] = 1;
+        queue[tail++] = n;
+      }
+    }
+  }
+}
+
+/** Grow + union a region from one or more seeds (each its own color-relative flood), then
+ *  morphologically close it. The shared building block for both prompt types. */
+function growRegion(
+  source: SegmentSource,
+  seeds: ReadonlyArray<readonly [number, number]>,
+  bounds: readonly [number, number, number, number],
+  tolerance: number,
+  closeRadius: number,
+): Uint8ClampedArray {
+  const { data, width, height } = source;
+  const px = width * height;
+  const mask = new Uint8ClampedArray(px);
+  const queue = new Int32Array(px);
+  const tolSq = tolerance * tolerance;
+  // Independent floods (fresh `visited` each) unioned into `mask`, so a later seed isn't
+  // starved by an earlier seed's rejected pixels — important for multi-tone box selects.
+  for (const seed of seeds) {
+    floodFrom(data, width, seed, tolSq, bounds, mask, new Uint8Array(px), queue);
+  }
+  return closeRadius > 0 ? closeMask(mask, width, height, closeRadius) : mask;
+}
+
+// ── Morphology ──────────────────────────────────────────────────────────────────
+
+/** 4-connected binary dilate (grow by 1px). */
+export function dilateMask(
+  mask: Uint8ClampedArray,
+  width: number,
+  height: number,
+): Uint8ClampedArray {
+  const out = new Uint8ClampedArray(mask.length);
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const i = y * width + x;
+      if (
+        mask[i] ||
+        (x > 0 && mask[i - 1]) ||
+        (x < width - 1 && mask[i + 1]) ||
+        (y > 0 && mask[i - width]) ||
+        (y < height - 1 && mask[i + width])
+      ) {
+        out[i] = 255;
+      }
+    }
+  }
+  return out;
+}
+
+/** 4-connected binary erode (shrink by 1px). */
+export function erodeMask(
+  mask: Uint8ClampedArray,
+  width: number,
+  height: number,
+): Uint8ClampedArray {
+  const out = new Uint8ClampedArray(mask.length);
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const i = y * width + x;
+      if (
+        mask[i] &&
+        (x === 0 || mask[i - 1]) &&
+        (x === width - 1 || mask[i + 1]) &&
+        (y === 0 || mask[i - width]) &&
+        (y === height - 1 || mask[i + width])
+      ) {
+        out[i] = 255;
+      }
+    }
+  }
+  return out;
+}
+
+/** Morphological close (dilate×r then erode×r): fills holes/gaps ≤ ~2·radius and smooths
+ *  the edge without changing the overall area. */
+export function closeMask(
+  mask: Uint8ClampedArray,
+  width: number,
+  height: number,
+  radius: number,
+): Uint8ClampedArray {
+  let m = mask;
+  for (let i = 0; i < radius; i++) m = dilateMask(m, width, height);
+  for (let i = 0; i < radius; i++) m = erodeMask(m, width, height);
+  return m;
+}
+
+// ── Resolution helpers (the painter caps work to keep auto-select ~instant) ──────
+
+/** Working size that fits within `maxPixels` while preserving aspect (never upsizes). */
+export function fitWorkingSize(
+  width: number,
+  height: number,
+  maxPixels: number,
+): { width: number; height: number; scale: number } {
+  if (width <= 0 || height <= 0) return { width: 0, height: 0, scale: 1 };
+  const total = width * height;
+  if (total <= maxPixels) return { width, height, scale: 1 };
+  const scale = Math.sqrt(maxPixels / total);
+  // Floor (not round) the dims so the working area is GUARANTEED ≤ maxPixels
+  // (floor(w·s)·floor(h·s) ≤ w·s·h·s = maxPixels), bounding auto-select latency.
+  return {
+    width: Math.max(1, Math.floor(width * scale)),
+    height: Math.max(1, Math.floor(height * scale)),
+    scale,
+  };
+}
+
+/** Area-average downscale of an RGBA buffer (stable colors → cleaner growth than nearest). */
+export function downscaleRgba(
+  data: Uint8ClampedArray,
+  sw: number,
+  sh: number,
+  dw: number,
+  dh: number,
+): Uint8ClampedArray {
+  if (dw === sw && dh === sh) return data;
+  const out = new Uint8ClampedArray(dw * dh * 4);
+  for (let y = 0; y < dh; y++) {
+    const sy0 = Math.floor((y * sh) / dh);
+    const sy1 = Math.max(sy0 + 1, Math.floor(((y + 1) * sh) / dh));
+    for (let x = 0; x < dw; x++) {
+      const sx0 = Math.floor((x * sw) / dw);
+      const sx1 = Math.max(sx0 + 1, Math.floor(((x + 1) * sw) / dw));
+      let r = 0;
+      let g = 0;
+      let b = 0;
+      let a = 0;
+      let count = 0;
+      for (let yy = sy0; yy < sy1 && yy < sh; yy++) {
+        for (let xx = sx0; xx < sx1 && xx < sw; xx++) {
+          const s = (yy * sw + xx) << 2;
+          r += data[s];
+          g += data[s + 1];
+          b += data[s + 2];
+          a += data[s + 3];
+          count++;
+        }
+      }
+      const o = (y * dw + x) << 2;
+      out[o] = count ? r / count : 0;
+      out[o + 1] = count ? g / count : 0;
+      out[o + 2] = count ? b / count : 0;
+      out[o + 3] = count ? a / count : 0;
+    }
+  }
+  return out;
+}
+
+/** Nearest-neighbor upscale of a 0/255 mask back to the source's natural dimensions. */
+export function upscaleMask(
+  mask: Uint8ClampedArray,
+  sw: number,
+  sh: number,
+  dw: number,
+  dh: number,
+): Uint8ClampedArray {
+  if (sw === dw && sh === dh) return mask;
+  const out = new Uint8ClampedArray(dw * dh);
+  for (let y = 0; y < dh; y++) {
+    const sy = Math.min(sh - 1, Math.floor((y * sh) / dh));
+    for (let x = 0; x < dw; x++) {
+      const sx = Math.min(sw - 1, Math.floor((x * sw) / dw));
+      out[y * dw + x] = mask[sy * sw + sx];
+    }
+  }
+  return out;
+}
+
+// ── The default engine ────────────────────────────────────────────────────────
+
+const clampInt = (v: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, Math.round(v)));
+
+/**
+ * The default, pure region-growing segmenter — no model, no download, instant + offline.
+ * `point` grows a magic-wand selection from the clicked pixel; `box` selects the dominant
+ * object inside the rectangle by growing from a spread of interior seeds, clipped to the
+ * box so it can't leak into the surrounding scene. Always returns a binary alpha plane at
+ * the source dimensions; the painter lands it as an editable region for accept/refine.
+ */
+export function createRegionSegmenter(defaults: SegmentOptions = {}): ImageSegmenter {
+  return {
+    id: 'region-grow',
+    segment(source, prompt, options) {
+      const { width, height } = source;
+      if (width <= 0 || height <= 0) return new Uint8ClampedArray(0);
+      const tolerance = options?.tolerance ?? defaults.tolerance ?? DEFAULT_TOLERANCE;
+      const closeRadius = options?.closeRadius ?? defaults.closeRadius ?? DEFAULT_CLOSE_RADIUS;
+
+      if (prompt.type === 'point') {
+        const seed: [number, number] = [
+          clampInt(prompt.x, 0, width - 1),
+          clampInt(prompt.y, 0, height - 1),
+        ];
+        return growRegion(source, [seed], [0, 0, width - 1, height - 1], tolerance, closeRadius);
+      }
+
+      // box — normalize + clamp, then seed a 3×3 grid of interior points and grow within bounds.
+      const bx0 = clampInt(Math.min(prompt.x0, prompt.x1), 0, width - 1);
+      const by0 = clampInt(Math.min(prompt.y0, prompt.y1), 0, height - 1);
+      const bx1 = clampInt(Math.max(prompt.x0, prompt.x1), 0, width - 1);
+      const by1 = clampInt(Math.max(prompt.y0, prompt.y1), 0, height - 1);
+      const seeds: Array<[number, number]> = [];
+      for (let r = 1; r <= 3; r++) {
+        for (let c = 1; c <= 3; c++) {
+          seeds.push([
+            clampInt(bx0 + ((bx1 - bx0) * c) / 4, bx0, bx1),
+            clampInt(by0 + ((by1 - by0) * r) / 4, by0, by1),
+          ]);
+        }
+      }
+      return growRegion(source, seeds, [bx0, by0, bx1, by1], tolerance, closeRadius);
+    },
+  };
+}

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

@@ -0,0 +1,19 @@
+import { describe, expect, test } from 'bun:test';
+import { formatBytes } from './size';
+
+describe('formatBytes', () => {
+  test('formats across unit boundaries, dropping the decimal at ≥ 100 / in bytes', () => {
+    expect(formatBytes(0)).toBe('0 B');
+    expect(formatBytes(512)).toBe('512 B');
+    expect(formatBytes(1024)).toBe('1.0 KB');
+    expect(formatBytes(1536)).toBe('1.5 KB');
+    expect(formatBytes(200 * 1024)).toBe('200 KB');
+    expect(formatBytes(1.4 * 1024 * 1024)).toBe('1.4 MB');
+    expect(formatBytes(2.1 * 1024 * 1024 * 1024)).toBe('2.1 GB');
+  });
+
+  test('non-finite / falsy inputs are 0 B, not NaN', () => {
+    expect(formatBytes(Number.NaN)).toBe('0 B');
+    expect(formatBytes(Number.POSITIVE_INFINITY)).toBe('0 B');
+  });
+});

package/src/core/media/size.ts

@@ -0,0 +1,3 @@
+// Human-readable byte sizes — implemented in cwip/core/format; re-exported here
+// so media-core consumers and charts/format.ts share one source of truth.
+export { formatBytes } from 'cwip/format';

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

@@ -0,0 +1,75 @@
+import { describe, expect, test } from 'bun:test';
+import { clampTrimRange, formatTimecode, trimDurationSeconds } from './trim';
+
+describe('clampTrimRange', () => {
+  test('passes a valid range through', () => {
+    expect(clampTrimRange(2, 8, { duration: 10 })).toEqual({ startSeconds: 2, endSeconds: 8 });
+  });
+
+  test('clamps the out-point to the duration', () => {
+    expect(clampTrimRange(2, 99, { duration: 10 })).toEqual({ startSeconds: 2, endSeconds: 10 });
+  });
+
+  test('un-inverts a backwards drag', () => {
+    expect(clampTrimRange(8, 2, { duration: 10 })).toEqual({ startSeconds: 2, endSeconds: 8 });
+  });
+
+  test('enforces a minimum selection length', () => {
+    const r = clampTrimRange(5, 5, { duration: 10, minDurationSeconds: 1 });
+    expect(r.endSeconds - r.startSeconds).toBeCloseTo(1, 5);
+    expect(r.startSeconds).toBe(5);
+  });
+
+  test('caps the selection at maxDurationSeconds, keeping the in-point', () => {
+    const r = clampTrimRange(2, 30, { duration: 60, maxDurationSeconds: 10 });
+    expect(r).toEqual({ startSeconds: 2, endSeconds: 12 });
+  });
+
+  test('when start near the end with a max cap, pulls start back to fit', () => {
+    const r = clampTrimRange(58, 60, {
+      duration: 60,
+      maxDurationSeconds: 10,
+      minDurationSeconds: 1,
+    });
+    expect(r.endSeconds).toBeLessThanOrEqual(60);
+    expect(r.endSeconds - r.startSeconds).toBeGreaterThanOrEqual(1);
+  });
+
+  test('handles missing duration (unbounded)', () => {
+    expect(clampTrimRange(1, 4)).toEqual({ startSeconds: 1, endSeconds: 4 });
+  });
+
+  test('coerces non-finite bounds', () => {
+    const r = clampTrimRange(Number.NaN, Number.NaN, { duration: 10 });
+    expect(r.startSeconds).toBeGreaterThanOrEqual(0);
+    expect(r.endSeconds).toBeGreaterThan(r.startSeconds);
+  });
+});
+
+describe('trimDurationSeconds', () => {
+  test('is the non-negative difference', () => {
+    expect(trimDurationSeconds(2, 8)).toBe(6);
+    expect(trimDurationSeconds(8, 2)).toBe(0);
+  });
+});
+
+describe('formatTimecode', () => {
+  test('m:ss under an hour', () => {
+    expect(formatTimecode(0)).toBe('0:00');
+    expect(formatTimecode(5)).toBe('0:05');
+    expect(formatTimecode(75)).toBe('1:15');
+  });
+
+  test('h:mm:ss past an hour', () => {
+    expect(formatTimecode(3661)).toBe('1:01:01');
+  });
+
+  test('tenths suffix', () => {
+    expect(formatTimecode(5.4, { tenths: true })).toBe('0:05.4');
+  });
+
+  test('negative/NaN render as 0:00', () => {
+    expect(formatTimecode(-3)).toBe('0:00');
+    expect(formatTimecode(Number.NaN)).toBe('0:00');
+  });
+});

package/src/core/media/trim.ts

@@ -0,0 +1,60 @@
+// Pure trim-range math + timecode formatting for the `<VideoTrimmer>` slider. Kept
+// in media-core (no DOM) so the in/out clamping — the part that must be CORRECT — is
+// unit-tested without rendering a video element.
+
+export interface ClampTrimOptions {
+  /** Total media duration; the out-point can never exceed it. */
+  duration?: number;
+  /** Optional cap on the selected length (end - start). */
+  maxDurationSeconds?: number;
+  /** Smallest allowed selection; defaults to 0.1s so start !== end. */
+  minDurationSeconds?: number;
+}
+
+export interface TrimRange {
+  startSeconds: number;
+  endSeconds: number;
+}
+
+/**
+ * Clamp a proposed [start, end] into a valid, ordered range:
+ * `0 <= start < end <= duration`, honoring an optional min/max selection length.
+ * Always returns `end > start` (by at least `minDurationSeconds`) so a degenerate or
+ * inverted drag can never produce a zero/negative trim.
+ */
+export function clampTrimRange(start: number, end: number, opts: ClampTrimOptions = {}): TrimRange {
+  const duration =
+    opts.duration != null && Number.isFinite(opts.duration) ? opts.duration : Infinity;
+  const minLen = Math.max(0.0001, opts.minDurationSeconds ?? 0.1);
+  const maxLen =
+    opts.maxDurationSeconds != null ? Math.max(minLen, opts.maxDurationSeconds) : Infinity;
+
+  let s = Number.isFinite(start) ? start : 0;
+  let e = Number.isFinite(end) ? end : duration;
+
+  if (e < s) [s, e] = [e, s]; // un-invert a backwards drag
+
+  s = Math.max(0, Math.min(s, Number.isFinite(duration) ? duration : s));
+  e = Math.min(e, duration);
+
+  // Enforce min length, nudging whichever bound has room.
+  if (e - s < minLen) {
+    if (s + minLen <= duration) e = s + minLen;
+    else s = Math.max(0, e - minLen);
+  }
+  // Enforce max length by pulling the end in (keep the in-point the user set).
+  if (e - s > maxLen) e = s + maxLen;
+  if (e > duration) {
+    e = duration;
+    s = Math.max(0, e - maxLen);
+  }
+
+  return { startSeconds: s, endSeconds: e };
+}
+
+export function trimDurationSeconds(start: number, end: number): number {
+  return Math.max(0, end - start);
+}
+
+// Implemented in cwip/core/format; aliased here for backward compat.
+export { formatClock as formatTimecode } from 'cwip/format';

package/src/core/media/types.ts

@@ -0,0 +1,147 @@
+// cursedbelt media-core — the pure, dependency-free contract shared by the Bun
+// server adapter (`src/server/media-bun`), the React components
+// (`cursedbelt/react/media`), and any app/test. ZERO npm deps: types + pure
+// functions only, so the exact same module loads identically in Bun, the browser,
+// and a unit test.
+//
+// Storage, auth, and signing are deliberately ABSENT here — a `MediaItem` carries
+// only a plain URL (the app resolves/signs it). Binary downloads stay plain GET
+// (00-README invariant #3): never route a `MediaItem.url` through the ctgr codec,
+// which base64-mangles binary bodies.
+
+/** Output container/codecs for {@link renderImage}. */
+export type ImageOutputFormat = 'jpeg' | 'png' | 'webp' | 'avif';
+
+/**
+ * A single, declarative image transform. The list is applied in order by the
+ * server adapter's `renderImage` (sharp) — the SAME spec can be built client-side
+ * (from the editor's design state) or server-side and produces an identical result.
+ */
+export type ImageOperation =
+  | { type: 'resize'; width?: number; height?: number; fit?: 'cover' | 'contain' | 'fill' }
+  | { type: 'crop'; left: number; top: number; width: number; height: number }
+  | { type: 'rotate'; angle: number }
+  | { type: 'flip'; direction: 'horizontal' | 'vertical' }
+  | { type: 'format-convert' }
+  | { type: 'compress'; quality: number }
+  /**
+   * Remove a uniform, edge-connected background. The pure BFS flood-fill lives in
+   * {@link floodFillBGS} (media-core); the server runs it on sharp's raw RGBA buffer,
+   * a client could call a rembg API instead. `tolerance` is the per-pixel color
+   * distance (0–441, euclidean over RGB) treated as "same as the seed".
+   */
+  | { type: 'remove-bg'; tolerance?: number };
+
+/**
+ * A complete image pipeline: a source (a file path on the server, or raw bytes) +
+ * an ordered op list + an output target. `input` is `Uint8Array` rather than Node's
+ * `Buffer` so the type stays browser-safe; a server `Buffer` is a `Uint8Array` and
+ * assigns cleanly.
+ */
+export type ImagePipelineSpec = {
+  input: Uint8Array | string;
+  operations: ImageOperation[];
+  output: { format: ImageOutputFormat; quality?: number };
+};
+
+/** Output container for {@link trimVideo}. */
+export type VideoFormat = 'mp4' | 'webm';
+/** Encode-quality preset → a CRF + bitrate ladder (see `videoCodecPlan`). */
+export type VideoQuality = 'high' | 'medium' | 'low';
+
+/** Args for a server-side trim (re-encode between two timestamps). */
+export type VideoTrimSpec = {
+  inputPath: string;
+  outputPath: string;
+  startSeconds: number;
+  endSeconds: number;
+  format?: VideoFormat;
+  quality?: VideoQuality;
+};
+
+/** Progress emitted while a server video op runs (parsed from ffmpeg stderr). */
+export type VideoProgressEvent = {
+  phase: 'probe' | 'encode' | 'done' | 'error';
+  progressPercent?: number;
+  error?: string;
+};
+
+/** The three media kinds the catalogue + lightbox understand. */
+export type MediaKind = 'image' | 'video' | 'audio';
+
+/**
+ * A URL-only catalogue item — the unit the `<MediaCatalogueViewer>` renders. It
+ * holds NO storage identity (no FsNode, no binary id): the app maps its own records
+ * to this and pre-resolves `url`/`thumbnailUrl` (signing private files as needed).
+ */
+export type MediaItem = {
+  id: string;
+  type: MediaKind;
+  /** The final URL the browser fetches. Signing is the app's job. Plain GET only. */
+  url: string;
+  thumbnailUrl?: string;
+  /** A browser-safe full-size URL to display instead of `url` when the original can't render inline
+   * (e.g. a JPEG derivative of a HEIC). The full view should prefer this over `url` when present. */
+  displayUrl?: string;
+  name: string;
+  sizeBytes?: number;
+  mimeType?: string;
+  width?: number;
+  height?: number;
+  durationSeconds?: number;
+};
+
+/**
+ * A gallery photo — a {@link MediaItem} specialized to images, plus the catalogue affordances a
+ * photo grid renders (tags for the filter strip, createdAt for ordering, favorite for the ♥).
+ * Like every media-core unit it carries only resolved URLs — no storage identity.
+ */
+export type GalleryPhoto = MediaItem & {
+  type: 'image';
+  tags?: string[];
+  createdAt?: number;
+  favorite?: boolean;
+};
+
+/**
+ * A single item in a MIXED media gallery (photos + videos in one grid) — a
+ * discriminated union so a consumer can render the right tile/stage per item.
+ * `mediaKind` is the explicit tag: `GalleryPhoto` carries `type:'image'` while
+ * `PlayableVideo` has no `type`, so a dedicated discriminator keeps the two
+ * unambiguous (and future audio can join without a structural clash).
+ */
+export type GalleryMedia =
+  | (PlayableVideo & { mediaKind: 'video' })
+  | (GalleryPhoto & { mediaKind: 'photo' });
+
+/** Which kinds a mixed media source/gallery lists — `all` = photos + videos. */
+export type MediaKindFilter = 'all' | 'image' | 'video';
+
+/** Background-processing lifecycle of a video's web-safe derivatives. */
+export type ProcessingStatus = 'pending' | 'processing' | 'ready' | 'failed';
+
+/**
+ * A surface-agnostic description of a playable video with every URL already resolved —
+ * the unit the `<VideoPlayer>` primitive consumes (distinct from {@link MediaItem}, which
+ * is the lightbox catalogue unit). It carries NO storage identity: a source pre-resolves
+ * the streaming URLs (signing/tokenising private ones), so the player couples to nothing.
+ * Richer than `MediaItem`: an HLS master + scrub-preview track for a real player HUD.
+ */
+export type PlayableVideo = {
+  id: string;
+  name: string;
+  /** Range-streamed progressive source (works for plaintext + decrypted-private bytes). */
+  streamUrl: string;
+  /** HLS adaptive master — when present, the player prefers it over `streamUrl`. */
+  hlsUrl?: string;
+  posterUrl?: string;
+  /** WebVTT scrub-preview track + its sprite sheet (hover/drag thumbnails). */
+  vttUrl?: string;
+  spriteUrl?: string;
+  durationSeconds?: number;
+  /** Free-form tags for a gallery filter strip. */
+  tags?: string[];
+  /** Undefined ⇒ plays raw; else drives the player's processing overlay. */
+  processingStatus?: ProcessingStatus;
+  processingProgress?: number;
+};

package/src/core/media/uploadLimits.ts

@@ -0,0 +1,18 @@
+// Upload size limits — the ONE source of truth shared by the upload client
+// (`cursedbelt/react/media` fileUploadClient) and the server file routes
+// (`cursedbelt-server/storage`). Pure constants, no deps, so both the browser
+// and Bun sides import the same numbers and can never drift.
+//
+// The law: NO single HTTP request may carry more than MAX_SINGLE_UPLOAD_BYTES of body.
+// Anything larger MUST use the chunked, direct-to-backend path (each chunk is a
+// separate request of at most DEFAULT_UPLOAD_CHUNK_SIZE). This keeps every upload
+// request comfortably under edge proxy body caps (e.g. Cloudflare's ~100 MB limit).
+
+/** Hard cap on the body of any SINGLE upload request (streamed PUT). 20 MiB. Bodies
+ *  above this are rejected 413 server-side and must go through chunked upload. */
+export const MAX_SINGLE_UPLOAD_BYTES = 20 * 1024 * 1024;
+
+/** Default per-chunk size for the chunked-upload path. Must stay < MAX_SINGLE_UPLOAD_BYTES
+ *  (each chunk is its own request). Also the client's default chunk THRESHOLD: files at or
+ *  below this upload as a single streamed PUT, larger files chunk. 8 MiB. */
+export const DEFAULT_UPLOAD_CHUNK_SIZE = 8 * 1024 * 1024;