@agent-native/core 0.84.22 → 0.84.23

package/corpus/templates/clips/actions/lib/ensure-seekable-video.ts

@@ -0,0 +1,256 @@
+/**
+ * Repair an already-stored recording so it plays back and seeks instantly.
+ *
+ * This is the fetch-based counterpart to the inline seekable pass in
+ * `finalize-recording`. It re-fetches a recording's stored provider media,
+ * runs the format-appropriate seekable rewrite (MP4 faststart / WebM Cues
+ * remux), and, when that changed the bytes, re-uploads the fixed file and
+ * repoints the recording at it.
+ *
+ * Used by:
+ *   - `reprocess-recording` — owner/agent triggered backfill of clips that were
+ *     uploaded before the seekable pass existed (or via the streaming path,
+ *     which never applied it).
+ *   - `finalize-recording` — a best-effort background pass for the resumable
+ *     streaming path, whose bytes live at the provider and were never buffered
+ *     server-side for an inline rewrite.
+ *
+ * Everything is best-effort and non-destructive: if we can't fetch, can't
+ * improve, or can't re-upload, the existing recording is left exactly as-is.
+ */
+
+import {
+  readAppState,
+  writeAppState,
+} from "@agent-native/core/application-state";
+import { uploadFile } from "@agent-native/core/file-upload";
+import { MAX_UPLOAD_BYTES } from "@shared/upload-limits.js";
+import { and, eq } from "drizzle-orm";
+
+import { getDb, schema } from "../../server/db/index.js";
+import { ownerEmailMatches } from "../../server/lib/recordings.js";
+import {
+  makeSeekable,
+  type VideoFormat,
+} from "../../server/lib/video-remux.js";
+import { isLoomRecordingSource } from "../../shared/loom.js";
+
+const PROVIDER_FETCH_TIMEOUT_MS = 60_000;
+
+export type EnsureSeekableStatus =
+  | "optimized"
+  | "already-optimized"
+  | "skipped-not-ready"
+  | "skipped-no-media"
+  | "skipped-local-media"
+  | "skipped-too-large"
+  | "skipped-fetch-failed"
+  | "skipped-upload-failed"
+  | "not-found";
+
+export interface EnsureSeekableResult {
+  recordingId: string;
+  status: EnsureSeekableStatus;
+  changed: boolean;
+  videoUrl?: string | null;
+  detail?: string;
+}
+
+/** application_state key marking a recording's media as already made seekable. */
+export function seekableMarkerKey(recordingId: string): string {
+  return `recording-seekable-${recordingId}`;
+}
+
+/**
+ * Record that `videoUrl` for `recordingId` has been made seekable, so later
+ * sweeps skip it. Scoped by URL so a re-upload that changes the URL is not
+ * mistaken for already-processed.
+ */
+export async function markRecordingSeekable(
+  recordingId: string,
+  videoUrl: string | null | undefined,
+): Promise<void> {
+  await writeAppState(seekableMarkerKey(recordingId), {
+    recordingId,
+    videoUrl: videoUrl ?? null,
+    at: new Date().toISOString(),
+  });
+}
+
+async function isAlreadyMarked(
+  recordingId: string,
+  videoUrl: string | null,
+): Promise<boolean> {
+  const marker = await readAppState(seekableMarkerKey(recordingId)).catch(
+    () => null,
+  );
+  return Boolean(
+    marker &&
+    typeof marker === "object" &&
+    (marker as { videoUrl?: unknown }).videoUrl === videoUrl,
+  );
+}
+
+function isRemoteProviderUrl(videoUrl: string | null | undefined): boolean {
+  return typeof videoUrl === "string" && /^https:\/\//i.test(videoUrl.trim());
+}
+
+async function fetchProviderBytes(
+  videoUrl: string,
+): Promise<
+  { ok: true; bytes: Uint8Array } | { ok: false; reason: EnsureSeekableStatus }
+> {
+  const controller = new AbortController();
+  const timeout = setTimeout(
+    () => controller.abort(),
+    PROVIDER_FETCH_TIMEOUT_MS,
+  );
+  try {
+    const res = await fetch(videoUrl, { signal: controller.signal });
+    if (!res.ok) return { ok: false, reason: "skipped-fetch-failed" };
+
+    const declaredLength = Number(res.headers.get("content-length") ?? "0");
+    if (Number.isFinite(declaredLength) && declaredLength > MAX_UPLOAD_BYTES) {
+      return { ok: false, reason: "skipped-too-large" };
+    }
+
+    const buf = new Uint8Array(await res.arrayBuffer());
+    if (buf.byteLength === 0)
+      return { ok: false, reason: "skipped-fetch-failed" };
+    if (buf.byteLength > MAX_UPLOAD_BYTES) {
+      return { ok: false, reason: "skipped-too-large" };
+    }
+    return { ok: true, bytes: buf };
+  } catch {
+    return { ok: false, reason: "skipped-fetch-failed" };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/**
+ * Ensure a single recording's stored media is seekable. Owner-scoped: pass the
+ * resolved owner email so the DB lookup can only touch that owner's rows.
+ */
+export async function ensureRecordingSeekable(params: {
+  recordingId: string;
+  ownerEmail: string;
+  force?: boolean;
+}): Promise<EnsureSeekableResult> {
+  const { recordingId, ownerEmail, force = false } = params;
+  const db = getDb();
+
+  const [rec] = await db
+    .select({
+      id: schema.recordings.id,
+      status: schema.recordings.status,
+      videoUrl: schema.recordings.videoUrl,
+      videoFormat: schema.recordings.videoFormat,
+      sourceAppName: schema.recordings.sourceAppName,
+    })
+    .from(schema.recordings)
+    .where(
+      and(
+        eq(schema.recordings.id, recordingId),
+        ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+      ),
+    );
+
+  if (!rec) {
+    return { recordingId, status: "not-found", changed: false };
+  }
+  if (rec.status !== "ready") {
+    return { recordingId, status: "skipped-not-ready", changed: false };
+  }
+  if (isLoomRecordingSource(rec)) {
+    return { recordingId, status: "skipped-local-media", changed: false };
+  }
+  if (!rec.videoUrl) {
+    return { recordingId, status: "skipped-no-media", changed: false };
+  }
+  // Only provider-hosted media can be re-fetched and re-uploaded. Local/dev
+  // blobs (served from application_state via /api/video) and other relative
+  // URLs are left untouched.
+  if (!isRemoteProviderUrl(rec.videoUrl)) {
+    return {
+      recordingId,
+      status: "skipped-local-media",
+      changed: false,
+      videoUrl: rec.videoUrl,
+    };
+  }
+
+  if (!force && (await isAlreadyMarked(recordingId, rec.videoUrl))) {
+    return {
+      recordingId,
+      status: "already-optimized",
+      changed: false,
+      videoUrl: rec.videoUrl,
+    };
+  }
+
+  const fetched = await fetchProviderBytes(rec.videoUrl);
+  if (!fetched.ok) {
+    return { recordingId, status: fetched.reason, changed: false };
+  }
+
+  const videoFormat: VideoFormat = rec.videoFormat === "mp4" ? "mp4" : "webm";
+  const seekable = await makeSeekable({
+    mediaBytes: fetched.bytes,
+    videoFormat,
+  });
+
+  if (!seekable.changed) {
+    // Already seekable (or unimprovable) — remember so we don't refetch it.
+    await markRecordingSeekable(recordingId, rec.videoUrl);
+    return {
+      recordingId,
+      status: "already-optimized",
+      changed: false,
+      videoUrl: rec.videoUrl,
+    };
+  }
+
+  const mimeType = videoFormat === "mp4" ? "video/mp4" : "video/webm";
+  const upload = await uploadFile({
+    data: seekable.bytes,
+    filename: `${recordingId}.${videoFormat}`,
+    mimeType,
+    ownerEmail,
+    skipCompressionWait: true,
+  });
+
+  if (!upload?.url) {
+    // Could not re-upload — do NOT touch the row; the original still plays.
+    return {
+      recordingId,
+      status: "skipped-upload-failed",
+      changed: false,
+      videoUrl: rec.videoUrl,
+    };
+  }
+
+  await db
+    .update(schema.recordings)
+    .set({
+      videoUrl: upload.url,
+      videoSizeBytes: seekable.bytes.byteLength,
+      updatedAt: new Date().toISOString(),
+    })
+    .where(
+      and(
+        eq(schema.recordings.id, recordingId),
+        ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+      ),
+    );
+
+  await markRecordingSeekable(recordingId, upload.url);
+  await writeAppState("refresh-signal", { ts: Date.now() });
+
+  return {
+    recordingId,
+    status: "optimized",
+    changed: true,
+    videoUrl: upload.url,
+  };
+}

package/corpus/templates/clips/actions/reprocess-recording.ts

@@ -0,0 +1,160 @@
+/**
+ * Repair the playback of already-stored recordings.
+ *
+ * Clips uploaded via the streaming path (or before the seekable rewrite
+ * existed) can ship raw MediaRecorder output: an MP4 with a trailing `moov`
+ * atom or a WebM with no Cues index. Those load slowly and re-buffer on every
+ * seek even though the file downloads fine. This action re-fetches the stored
+ * media, rewrites it to be start-playable and seekable (MP4 faststart / WebM
+ * Cues remux), re-uploads the fixed file, and repoints the recording at it.
+ *
+ * It's idempotent and non-destructive: clips that are already seekable are
+ * skipped, and any clip we can't improve or re-upload is left untouched.
+ *
+ * Usage:
+ *   pnpm action reprocess-recording --id=<recordingId>
+ *   pnpm action reprocess-recording --ids='["id1","id2"]'
+ *   pnpm action reprocess-recording --all --limit=20
+ *   pnpm action reprocess-recording --id=<recordingId> --force
+ */
+
+import { defineAction } from "@agent-native/core";
+import { and, desc, eq, isNotNull } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import {
+  getCurrentOwnerEmail,
+  ownerEmailMatches,
+} from "../server/lib/recordings.js";
+import {
+  ensureRecordingSeekable,
+  type EnsureSeekableResult,
+} from "./lib/ensure-seekable-video.js";
+
+const MAX_TARGETS_PER_CALL = 100;
+const DEFAULT_ALL_LIMIT = 20;
+
+function parseIds(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.filter((v): v is string => typeof v === "string" && !!v);
+  }
+  if (typeof value === "string" && value.trim()) {
+    try {
+      const parsed = JSON.parse(value);
+      if (Array.isArray(parsed)) {
+        return parsed.filter((v): v is string => typeof v === "string" && !!v);
+      }
+    } catch {
+      // Fall back to a single comma-separated / plain id string.
+      return value
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    }
+  }
+  return [];
+}
+
+export default defineAction({
+  description:
+    "Repair slow-loading or buffering recordings by rewriting their stored video to be start-playable and seekable (MP4 faststart / WebM Cues remux) and re-uploading it. Use for clips that take a long time to load or re-buffer when scrubbing. Pass `id` for one clip, `ids` for several, or `all: true` to sweep the caller's ready clips (bounded by `limit`). Already-seekable clips are skipped unless `force` is true.",
+  schema: z.object({
+    id: z.string().optional().describe("A single recording id to repair."),
+    ids: z
+      .union([z.array(z.string()), z.string()])
+      .optional()
+      .describe(
+        "Multiple recording ids (array, or JSON/comma string for CLI).",
+      ),
+    all: z.coerce
+      .boolean()
+      .optional()
+      .describe(
+        "Repair the caller's own ready clips, most recent first, up to `limit`.",
+      ),
+    limit: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(MAX_TARGETS_PER_CALL)
+      .optional()
+      .describe(
+        `Max clips to process when using \`all\` (default ${DEFAULT_ALL_LIMIT}).`,
+      ),
+    force: z.coerce
+      .boolean()
+      .optional()
+      .describe("Re-run even on clips already marked seekable."),
+  }),
+  run: async (args) => {
+    const db = getDb();
+    const ownerEmail = getCurrentOwnerEmail();
+    const force = Boolean(args.force);
+
+    let targetIds: string[] = [];
+    if (args.id) targetIds.push(args.id);
+    targetIds.push(...parseIds(args.ids));
+
+    if (args.all) {
+      const limit = args.limit ?? DEFAULT_ALL_LIMIT;
+      const rows = await db
+        .select({ id: schema.recordings.id })
+        .from(schema.recordings)
+        .where(
+          and(
+            ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+            eq(schema.recordings.status, "ready"),
+            isNotNull(schema.recordings.videoUrl),
+          ),
+        )
+        .orderBy(desc(schema.recordings.createdAt))
+        .limit(limit);
+      targetIds.push(...rows.map((r) => r.id));
+    }
+
+    // De-dupe while preserving order, and bound the batch so a single call
+    // can't run unboundedly under the hosted foreground budget.
+    targetIds = Array.from(new Set(targetIds)).slice(0, MAX_TARGETS_PER_CALL);
+
+    if (targetIds.length === 0) {
+      return {
+        ok: true,
+        processed: 0,
+        changed: 0,
+        results: [] as EnsureSeekableResult[],
+        message:
+          "No recordings to reprocess. Pass id / ids, or all: true to sweep your clips.",
+      };
+    }
+
+    const results: EnsureSeekableResult[] = [];
+    for (const recordingId of targetIds) {
+      try {
+        results.push(
+          await ensureRecordingSeekable({ recordingId, ownerEmail, force }),
+        );
+      } catch (err) {
+        console.warn("[reprocess-recording] failed for", recordingId, err);
+        results.push({
+          recordingId,
+          status: "skipped-fetch-failed",
+          changed: false,
+          detail: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    const changed = results.filter((r) => r.changed).length;
+    console.log(
+      `Reprocessed ${results.length} recording(s); ${changed} rewritten for smoother playback.`,
+    );
+
+    return {
+      ok: true,
+      processed: results.length,
+      changed,
+      results,
+    };
+  },
+});

package/corpus/templates/clips/changelog/2026-07-01-shared-clips-now-start-playing-and-scrub-instantly-instead-o.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-01
+---
+
+Shared clips now start playing and scrub instantly instead of buffering — recordings are made seekable on upload, and you can repair older clips

package/corpus/templates/clips/server/lib/video-remux.ts

@@ -0,0 +1,222 @@
+/**
+ * Make recorded video seekable so browsers can start playback immediately and
+ * scrub without re-buffering the whole file.
+ *
+ * Two problems this fixes, both produced by `MediaRecorder` output:
+ *   - MP4: the `moov` metadata atom is written AFTER `mdat`, so a player must
+ *     download the entire file before it can start / seek. We relocate it with
+ *     the pure-TypeScript {@link applyFaststart} (no ffmpeg needed).
+ *   - WebM: MediaRecorder emits a "live" stream with no Cues (seek index) and an
+ *     unknown Segment duration, so Chrome refuses to honor `currentTime = X`
+ *     seeks and has to scan/download to move around. A cheap `ffmpeg -c copy`
+ *     remux rewrites the container with a SeekHead + Cues index and a real
+ *     duration — no re-encode, so it's fast and lossless.
+ *
+ * Everything here is best-effort: on any failure (ffmpeg missing, bad input,
+ * timeout) we return the ORIGINAL bytes with `changed: false`, so callers never
+ * regress relative to uploading the raw recording.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { applyFaststart, hasPlayableMp4Metadata } from "./faststart.js";
+
+const REMUX_TIMEOUT_MS = 120_000;
+const STDERR_LIMIT = 16 * 1024;
+const MAX_CONCURRENT_REMUXES = 2;
+// EBML magic that every valid Matroska/WebM file starts with.
+const EBML_MAGIC = [0x1a, 0x45, 0xdf, 0xa3];
+
+const requireFromThisFile = createRequire(import.meta.url);
+let cachedFfmpegStaticPath: string | null | undefined;
+let activeRemuxes = 0;
+const remuxWaiters: Array<() => void> = [];
+
+export type VideoFormat = "webm" | "mp4";
+
+export interface SeekableResult {
+  /** The seekable bytes, or the original bytes when nothing changed. */
+  bytes: Uint8Array;
+  /** True when the returned bytes differ from the input. */
+  changed: boolean;
+}
+
+function ffmpegCommand(): string {
+  if (process.env.FFMPEG_PATH) return process.env.FFMPEG_PATH;
+  return resolveFfmpegStaticPath() ?? "ffmpeg";
+}
+
+function resolveFfmpegStaticPath(): string | null {
+  if (cachedFfmpegStaticPath !== undefined) return cachedFfmpegStaticPath;
+  try {
+    const resolved = requireFromThisFile("ffmpeg-static");
+    cachedFfmpegStaticPath =
+      typeof resolved === "string" && resolved && existsSync(resolved)
+        ? resolved
+        : null;
+  } catch {
+    cachedFfmpegStaticPath = null;
+  }
+  return cachedFfmpegStaticPath;
+}
+
+/** Whether a server-side ffmpeg binary is resolvable. */
+export function isFfmpegAvailable(): boolean {
+  return Boolean(process.env.FFMPEG_PATH) || resolveFfmpegStaticPath() !== null;
+}
+
+function startsWithMagic(bytes: Uint8Array, magic: number[]): boolean {
+  if (bytes.byteLength < magic.length) return false;
+  for (let i = 0; i < magic.length; i++) {
+    if (bytes[i] !== magic[i]) return false;
+  }
+  return true;
+}
+
+async function runFfmpeg(args: string[]): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(ffmpegCommand(), args, {
+      stdio: ["ignore", "ignore", "pipe"],
+    });
+    let stderr = "";
+    const timeout = setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(new Error(`ffmpeg remux timed out\n${stderr}`));
+    }, REMUX_TIMEOUT_MS);
+
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr = (stderr + chunk.toString("utf8")).slice(-STDERR_LIMIT);
+    });
+    child.on("error", (err) => {
+      clearTimeout(timeout);
+      reject(new Error(`${err.message}\n${stderr}`));
+    });
+    child.on("close", (code) => {
+      clearTimeout(timeout);
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(new Error(`ffmpeg exited with code ${code}\n${stderr}`));
+    });
+  });
+}
+
+async function withRemuxSlot<T>(fn: () => Promise<T>): Promise<T> {
+  if (activeRemuxes >= MAX_CONCURRENT_REMUXES) {
+    await new Promise<void>((resolve) => remuxWaiters.push(resolve));
+  }
+  activeRemuxes += 1;
+  try {
+    return await fn();
+  } finally {
+    activeRemuxes = Math.max(0, activeRemuxes - 1);
+    remuxWaiters.shift()?.();
+  }
+}
+
+/**
+ * Rewrite a WebM/Matroska file with a SeekHead + Cues index and a real
+ * duration via a lossless `ffmpeg -c copy` remux. Returns the original bytes
+ * unchanged when ffmpeg is unavailable, the input isn't WebM, or anything
+ * goes wrong.
+ */
+export async function remuxWebmToSeekable(
+  mediaBytes: Uint8Array,
+): Promise<SeekableResult> {
+  const unchanged: SeekableResult = { bytes: mediaBytes, changed: false };
+
+  if (mediaBytes.byteLength === 0) return unchanged;
+  if (!startsWithMagic(mediaBytes, EBML_MAGIC)) return unchanged;
+  if (!isFfmpegAvailable()) return unchanged;
+
+  const dir = await mkdtemp(join(tmpdir(), "clips-remux-"));
+  const inputPath = join(dir, "input.webm");
+  const outputPath = join(dir, "output.webm");
+
+  try {
+    await writeFile(inputPath, mediaBytes);
+    await withRemuxSlot(() =>
+      runFfmpeg([
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        "-nostdin",
+        "-y",
+        // Regenerate presentation timestamps so a live MediaRecorder stream
+        // gets a coherent, seekable timeline in the remuxed output.
+        "-fflags",
+        "+genpts",
+        "-i",
+        inputPath,
+        // Stream-copy every track: no re-encode, so this stays fast + lossless.
+        "-map",
+        "0",
+        "-c",
+        "copy",
+        "-f",
+        "webm",
+        outputPath,
+      ]),
+    );
+
+    const info = await stat(outputPath).catch(() => null);
+    if (!info || info.size === 0) return unchanged;
+
+    const out = new Uint8Array(await readFile(outputPath));
+    // Validate the muxer actually produced a WebM before trusting it.
+    if (!startsWithMagic(out, EBML_MAGIC)) return unchanged;
+
+    return { bytes: out, changed: true };
+  } catch (err) {
+    console.warn("[video-remux] webm remux failed, keeping original", {
+      err: err instanceof Error ? err.message : String(err),
+    });
+    return unchanged;
+  } finally {
+    await rm(dir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Make an MP4 start-playable by moving its `moov` atom ahead of `mdat`. Pure
+ * TypeScript — no ffmpeg. Returns the original bytes when already faststarted
+ * or when the result would fail metadata validation.
+ */
+export function faststartMp4(mediaBytes: Uint8Array): SeekableResult {
+  if (mediaBytes.byteLength === 0) return { bytes: mediaBytes, changed: false };
+  try {
+    const out = applyFaststart(mediaBytes);
+    if (out === mediaBytes) return { bytes: mediaBytes, changed: false };
+    if (!hasPlayableMp4Metadata(out)) {
+      return { bytes: mediaBytes, changed: false };
+    }
+    return { bytes: out, changed: true };
+  } catch (err) {
+    console.warn("[video-remux] mp4 faststart failed, keeping original", {
+      err: err instanceof Error ? err.message : String(err),
+    });
+    return { bytes: mediaBytes, changed: false };
+  }
+}
+
+/**
+ * Make recorded media seekable based on its container format. Dispatches to
+ * {@link faststartMp4} for MP4 and {@link remuxWebmToSeekable} for WebM.
+ * Always resolves; unknown formats and failures return the input unchanged.
+ */
+export async function makeSeekable(input: {
+  mediaBytes: Uint8Array;
+  videoFormat: VideoFormat;
+}): Promise<SeekableResult> {
+  if (input.videoFormat === "mp4") return faststartMp4(input.mediaBytes);
+  if (input.videoFormat === "webm") {
+    return remuxWebmToSeekable(input.mediaBytes);
+  }
+  return { bytes: input.mediaBytes, changed: false };
+}

package/corpus/templates/content/.agents/skills/frontend-design/SKILL.md

@@ -53,6 +53,8 @@ Default to Apple/Linear-level restraint: make the primary workflow obvious, then
 - **Visual assets**: Websites, games, and object-focused pages need real or generated media when images help users understand the subject.
 - **Responsive fit**: Text must not overflow buttons, cards, tabs, sidebars, or fixed-format tools. Use stable dimensions for boards, grids, toolbars, and counters.
 
+**Beat convergence, not just defaults.** You sample toward the "on-distribution" center, so naming what to avoid is not enough: every "don't" needs a "do", or you converge on the next safe option (ban Inter and you reach for Roboto; ban purple gradients and you reach for Space Grotesk + a teal accent on every screen). Commit to one named direction, pair any reference with the reason it fits ("Linear: the quiet confidence of its spacing" — a bare "Linear" collapses back to the average), and match implementation effort to the vision: maximalist wants elaborate motion and effects, minimal wants restraint and precise spacing. When building on an existing app, inspect its tokens/type/components first and treat any drift back to a default as a missing token to pin, not something to re-prompt.
+
 ## Agent-Native UI Rules
 
 - Agent-native apps use React, Vite, Tailwind CSS, shadcn/ui, and `@tabler/icons-react`.