@agent-native/core 0.84.22 → 0.84.23

package/corpus/README.md

@@ -28,4 +28,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ## Generated Counts
 
 - core files: 2043
-- template files: 4962
+- template files: 4967

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @agent-native/core
 
+## 0.84.23
+
+### Patch Changes
+
+- fde28eb: Expose notification delivery channel results so callers can distinguish custom-channel delivery from inbox persistence.
+- fde28eb: Re-enable Claude Sonnet 5 as the visible and default Sonnet model now that the Builder gateway supports it.
+- fde28eb: Sharpen the exported Design skill's quality bar to defeat "AI slop": frame the variant flow as separating taste/exploration/spec/code, pair every banned default with a concrete alternative, warn about second-order convergence, and add explicit guidance for building on an existing design system or codebase.
+
 ## 0.84.22
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.84.22",
+  "version": "0.84.23",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/corpus/core/src/agent/model-config.ts

@@ -120,7 +120,7 @@ export function getContextWindowForModel(modelId: string): number {
   return DEFAULT_CONTEXT_WINDOW;
 }
 
-const ENABLE_CLAUDE_SONNET_5 = false;
+const ENABLE_CLAUDE_SONNET_5 = true;
 
 export const CLAUDE_SONNET_MODEL_ID = ENABLE_CLAUDE_SONNET_5
   ? "claude-sonnet-5"

package/corpus/core/src/cli/skills.ts

@@ -363,14 +363,28 @@ iteration, or a human-in-the-loop choice among design directions.
 
 ## Design Quality Bar
 
+Generic "AI slop" comes from letting one prompt set taste, explore, and emit code
+at once — so the model returns the training-average (Inter, an indigo/violet
+gradient, a centered hero, three rounded cards). The variant flow above exists to
+separate those jobs; use it, and hold this bar:
+
 - Before generating, name the concrete audience, the screen's primary job, and
   the visual thesis. If the brief is vague, make a reasonable choice and state
   it instead of producing a generic dashboard/landing-page default.
-- For existing products, inspect the current screen, design system, tokens,
-  component language, or codebase context before inventing a new direction.
+- Refuse the defaults, and pair every "don't" with a "do" (banning Inter alone
+  just makes you reach for Roboto). Avoid Inter/Roboto/system fonts, the
+  indigo/violet slop palette (\`#6366F1\`/\`#8B5CF6\`/\`#A855F7\`) and purple-on-white
+  gradients, and centered-hero + three-icon-card layouts; instead pick a
+  distinctive font pairing, one non-default palette family with a single decisive
+  accent, and an asymmetric layout with a clear focal point.
 - Make each direction distinct in structure and behavior, not just palette.
   Give every variant one memorable signature choice, then keep the surrounding
-  chrome disciplined.
+  chrome disciplined. Even your creative picks converge (Space Grotesk
+  everywhere) — vary deliberately so two directions never share a fingerprint.
+- For existing products, inspect the current screen, design system, tokens, and
+  component language before inventing a new direction. Treat any drift back to a
+  default as a missing token to pin, and vary layout per screen so on-brand does
+  not become same-in-your-colors.
 - Treat copy, data, and imagery as design material. Use realistic domain
   content and first-party/generated assets when images matter; avoid lorem
   ipsum, vague SaaS filler, and decorative placeholder boxes.

package/corpus/core/src/notifications/index.ts

@@ -8,6 +8,7 @@ export type {
 
 export {
   notify,
+  notifyWithDelivery,
   registerNotificationChannel,
   unregisterNotificationChannel,
   listNotificationChannels,

package/corpus/core/src/notifications/registry.ts

@@ -13,6 +13,11 @@ import {
   type Notification,
 } from "./types.js";
 
+export interface NotificationDeliveryResult {
+  notification?: Notification;
+  deliveredChannels: string[];
+}
+
 registerEvent({
   name: "notification.sent",
   description:
@@ -84,6 +89,13 @@ export async function notify(
   input: NotificationInput,
   meta: NotificationMeta,
 ): Promise<Notification | undefined> {
+  return (await notifyWithDelivery(input, meta)).notification;
+}
+
+export async function notifyWithDelivery(
+  input: NotificationInput,
+  meta: NotificationMeta,
+): Promise<NotificationDeliveryResult> {
   if (!meta?.owner) {
     throw new Error("notify: meta.owner is required");
   }
@@ -166,7 +178,7 @@ export async function notify(
     }
   }
 
-  return stored;
+  return { notification: stored, deliveredChannels: delivered };
 }
 
 function selectChannels(allowlist?: string[]): NotificationChannel[] {

package/corpus/core/src/templates/default/.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`.

package/corpus/core/src/templates/workspace-core/.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`.

package/corpus/templates/analytics/.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`.

package/corpus/templates/analytics/scripts/emit-netlify-dashboard-report-cron.ts

@@ -135,7 +135,24 @@ function siteOrigin(request) {
   return url.origin;
 }
 
+async function readScheduledInvocation(request) {
+  if (request.method !== "POST") return null;
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    return null;
+  }
+  const nextRun = typeof body?.next_run === "string" ? body.next_run : "";
+  return nextRun && Number.isFinite(Date.parse(nextRun))
+    ? { nextRun }
+    : null;
+}
+
 export default async function handler(request) {
+  const scheduled = await readScheduledInvocation(request);
+  if (!scheduled) return new Response("Not Found", { status: 404 });
+
   const url = new URL(WORKER_PATH, siteOrigin(request));
   const response = await fetch(url.toString(), {
     method: "POST",
@@ -143,7 +160,7 @@ export default async function handler(request) {
       "content-type": "application/json",
       "x-agent-native-analytics-alert-cron": CRON_TOKEN,
     },
-    body: JSON.stringify({ scheduled: true }),
+    body: JSON.stringify({ scheduled: true, next_run: scheduled.nextRun }),
   });
 
   if (!response.ok && response.status !== 202) {

package/corpus/templates/analytics/server/db/schema.ts

@@ -207,7 +207,7 @@ export const analyticsAlertRules = table("analytics_alert_rules", {
   lastEvaluatedAt: text("last_evaluated_at"),
   lastTriggeredAt: text("last_triggered_at"),
   lastStatus: text("last_status", {
-    enum: ["ok", "triggered", "cooldown", "error"],
+    enum: ["ok", "triggered", "cooldown", "error", "running"],
   }),
   lastError: text("last_error"),
   createdAt: text("created_at").notNull().default(now()),

package/corpus/templates/analytics/server/jobs/analytics-alerts.ts

@@ -1,4 +1,5 @@
 import {
+  claimAnalyticsAlertRuleEvaluation,
   evaluateAndNotifyAnalyticsAlertRule,
   listEnabledAnalyticsAlertRules,
   markAnalyticsAlertRuleError,
@@ -50,8 +51,10 @@ export async function runAnalyticsAlertsOnce(
     remaining = rules.length >= sweepLimit ? 1 : 0;
 
     for (const rule of rules) {
-      processed++;
       try {
+        const claimed = await claimAnalyticsAlertRuleEvaluation(rule);
+        if (!claimed) continue;
+        processed++;
         const result = await evaluateAndNotifyAnalyticsAlertRule(rule);
         if (result.status === "triggered") triggered++;
       } catch (err) {

package/corpus/templates/analytics/server/lib/analytics-alerts.ts

@@ -1,8 +1,8 @@
 import { randomUUID } from "node:crypto";
 
-import { notify } from "@agent-native/core/notifications";
+import { notifyWithDelivery } from "@agent-native/core/notifications";
 import { recordChange } from "@agent-native/core/server";
-import { and, asc, desc, eq, gte, isNull, lte, sql } from "drizzle-orm";
+import { and, asc, desc, eq, gte, isNull, lte, or, sql } from "drizzle-orm";
 
 import { getDb, schema } from "../db/index.js";
 
@@ -21,7 +21,12 @@ export interface AnalyticsAlertFilter {
 
 export type AnalyticsAlertThresholdMode = "event_count" | "distinct_count";
 export type AnalyticsAlertSeverity = "warning" | "critical";
-export type AnalyticsAlertStatus = "ok" | "triggered" | "cooldown" | "error";
+export type AnalyticsAlertStatus =
+  | "ok"
+  | "triggered"
+  | "cooldown"
+  | "error"
+  | "running";
 
 export interface AnalyticsAlertRuleInput {
   id?: string;
@@ -108,6 +113,8 @@ function nowIso(): string {
   return new Date().toISOString();
 }
 
+const ALERT_RULE_RUNNING_STALE_MS = 15 * 60 * 1000;
+
 function safeJsonParse<T>(raw: unknown, fallback: T): T {
   if (typeof raw !== "string" || !raw.trim()) return fallback;
   try {
@@ -372,6 +379,7 @@ export async function listEnabledAnalyticsAlertRules(options: {
       options.orgId ? eq(table.orgId, options.orgId) : isNull(table.orgId),
     );
   }
+  clauses.push(alertRuleNotRunningWhere(new Date()));
   const rows = await db
     .select()
     .from(table)
@@ -385,6 +393,52 @@ export async function listEnabledAnalyticsAlertRules(options: {
   return rows.map(rowToRule);
 }
 
+function alertRuleNotRunningWhere(now: Date) {
+  const table = schema.analyticsAlertRules;
+  const staleRunningBefore = new Date(
+    now.getTime() - ALERT_RULE_RUNNING_STALE_MS,
+  ).toISOString();
+  return or(
+    isNull(table.lastStatus),
+    sql`${table.lastStatus} <> 'running'`,
+    isNull(table.lastEvaluatedAt),
+    lte(table.lastEvaluatedAt, staleRunningBefore),
+  );
+}
+
+function alertRulePreviousEvaluationWhere(rule: AnalyticsAlertRule) {
+  const table = schema.analyticsAlertRules;
+  return rule.lastEvaluatedAt
+    ? eq(table.lastEvaluatedAt, rule.lastEvaluatedAt)
+    : isNull(table.lastEvaluatedAt);
+}
+
+export async function claimAnalyticsAlertRuleEvaluation(
+  rule: AnalyticsAlertRule,
+  now: Date = new Date(),
+): Promise<boolean> {
+  const db = getDb() as any;
+  const table = schema.analyticsAlertRules;
+  const claimedAt = now.toISOString();
+  const rows = await db
+    .update(table)
+    .set({
+      lastEvaluatedAt: claimedAt,
+      lastStatus: "running",
+      lastError: null,
+    })
+    .where(
+      and(
+        eq(table.id, rule.id),
+        eq(table.enabled, true),
+        alertRuleNotRunningWhere(now),
+        alertRulePreviousEvaluationWhere(rule),
+      ),
+    )
+    .returning({ id: table.id });
+  return rows.length > 0;
+}
+
 export async function evaluateAndNotifyAnalyticsAlertRule(
   rule: AnalyticsAlertRule,
   now: Date = new Date(),
@@ -416,12 +470,13 @@ export async function evaluateAndNotifyAnalyticsAlertRule(
   }
 
   const body = alertBody(rule, evaluation);
-  const stored = await notify(
+  const channels = ensureInboxNotificationChannel(rule.channels);
+  const delivery = await notifyWithDelivery(
     {
       severity: rule.severity,
       title: `Analytics alert: ${rule.name}`,
       body,
-      channels: rule.channels,
+      channels,
       metadata: {
         kind: "analytics_alert",
         ruleId: rule.id,
@@ -438,13 +493,22 @@ export async function evaluateAndNotifyAnalyticsAlertRule(
         filters: rule.filters,
         sampleEvents: evaluation.sampleEvents,
         emailRecipients: rule.emailRecipients,
+        requestedChannels: rule.channels,
       },
     },
     { owner: rule.ownerEmail },
   );
+  if (delivery.deliveredChannels.length === 0) {
+    await markRuleStatus(rule.id, {
+      lastEvaluatedAt: evaluatedAt,
+      lastStatus: "error",
+      lastError: "Analytics alert notification was not delivered.",
+    });
+    return { ruleId: rule.id, status: "error", ...evaluation };
+  }
 
   await recordIncident(rule, {
-    notificationId: stored?.id,
+    notificationId: delivery.notification?.id,
     triggeredAt: evaluatedAt,
     windowStart,
     windowEnd,
@@ -459,11 +523,16 @@ export async function evaluateAndNotifyAnalyticsAlertRule(
   return {
     ruleId: rule.id,
     status: "triggered",
-    notificationId: stored?.id,
+    notificationId: delivery.notification?.id,
     ...evaluation,
   };
 }
 
+function ensureInboxNotificationChannel(channels: string[]): string[] {
+  const normalized = channels.map((channel) => channel.trim()).filter(Boolean);
+  return normalized.includes("inbox") ? normalized : ["inbox", ...normalized];
+}
+
 export async function markAnalyticsAlertRuleError(
   id: string,
   error: unknown,

package/corpus/templates/assets/.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`.

package/corpus/templates/brain/.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`.

package/corpus/templates/calendar/.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`.

package/corpus/templates/chat/.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`.

package/corpus/templates/clips/.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`.

package/corpus/templates/clips/.agents/skills/recording/SKILL.md

@@ -31,9 +31,38 @@ Some recordings are linked to a meeting — when `meeting_id` is non-null on the
 4. **Record.** Start a `MediaRecorder` with `mimeType: "video/webm;codecs=vp9,opus"` (fallback to vp8, then browser default). Use `timeslice: 2000` so chunks arrive every 2s.
 5. **Upload each chunk.** `ondataavailable` POSTs the chunk bytes to `/api/uploads/chunk` with headers `X-Recording-Id` and `X-Chunk-Index`. Don't retry inline — buffer failed chunks in `IndexedDB` and let a background worker re-send.
 6. **Live transcription.** Alongside the MediaRecorder, `useLiveTranscription` runs the Web Speech API to accumulate transcript text in real time. On stop, the client calls `save-browser-transcript` to persist the result immediately — no API key needed. Desktop recordings use local Whisper/macOS speech first when available, and fall back to Web Speech in the webview on non-mac before relying on upload transcription.
-7. **Finalize.** On stop, send the final chunk to `/api/uploads/:id/chunk?isFinal=1`. The route calls `finalize-recording`, which stitches chunks, uploads the finished media when storage is configured, transitions `status` to `ready`, then kicks off `request-transcript` for higher-quality output (see `ai-video-tools`).
+7. **Finalize.** On stop, send the final chunk to `/api/uploads/:id/chunk?isFinal=1`. The route calls `finalize-recording`, which stitches chunks, makes the media seekable (see below), uploads the finished media when storage is configured, transitions `status` to `ready`, then kicks off `request-transcript` for higher-quality output (see `ai-video-tools`).
 8. **Navigate.** Once the row is `ready` the UI navigates to `/r/:id`.
 
+## Seekable playback (don't ship raw MediaRecorder output)
+
+Raw `MediaRecorder` files are not friendly to progressive HTTP playback, which
+shows up as "clip takes minutes to load" and "re-buffers every time I seek"
+even though the file downloads fine:
+
+- **MP4** is written with the `moov` metadata atom *after* `mdat`, so a player
+  must fetch the whole file before it can start or seek.
+- **WebM** is a live stream with no Cues (seek index) and an unknown Segment
+  duration, so Chrome won't honor `currentTime = X` and has to scan/download.
+
+`finalize-recording` fixes this before upload: MP4 gets pure-TS faststart
+(`server/lib/faststart.ts`), WebM gets a lossless `ffmpeg -c copy` remux that
+writes a SeekHead + Cues + real duration (`server/lib/video-remux.ts`). Both are
+best-effort — on failure we upload the original, never block finalize. Recordings
+above `CLIPS_INLINE_REMUX_MAX_BYTES` (default 200 MB) skip the inline pass and
+are repaired in the background.
+
+The **streaming/resumable** upload path forwards raw bytes straight to the
+provider and cannot rewrite them inline, so `finalize-recording` schedules a
+background `ensureRecordingSeekable` pass for those.
+
+To repair clips uploaded before this existed (or via streaming), call the
+`reprocess-recording` action: `--id`, `--ids='[...]'`, or `--all --limit=N`. It
+re-fetches provider media, rewrites it, re-uploads, and repoints the row. It's
+idempotent (already-seekable clips are skipped unless `--force`) and only touches
+provider-hosted clips owned by the caller. This is the right tool when a user
+reports a specific slow/buffering clip.
+
 ## Loom import
 
 Use `import-loom-recording` for Loom share or embed URLs. The action validates

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

@@ -40,12 +40,27 @@ import {
   getResumableSession,
 } from "../server/lib/resumable-session.js";
 import { isStreamingUploadDisabled } from "../server/lib/streaming-upload-mode.js";
+import { remuxWebmToSeekable } from "../server/lib/video-remux.js";
 import {
   requiresConfiguredVideoStorage,
   STORAGE_SETUP_REQUIRED_REASON,
 } from "../server/lib/video-storage.js";
+import {
+  ensureRecordingSeekable,
+  markRecordingSeekable,
+} from "./lib/ensure-seekable-video.js";
 import requestTranscript from "./request-transcript.js";
 
+// Recordings up to this size get their seekable rewrite applied inline during
+// finalize (we already hold the assembled bytes). Larger recordings are handed
+// off to the background/reprocess path so we don't stretch the finalize
+// request or exhaust serverless /tmp. Override with CLIPS_INLINE_REMUX_MAX_BYTES.
+function inlineRemuxMaxBytes(): number {
+  const raw = Number(process.env.CLIPS_INLINE_REMUX_MAX_BYTES ?? "");
+  if (Number.isFinite(raw) && raw > 0) return Math.floor(raw);
+  return 200 * 1024 * 1024;
+}
+
 /**
  * Decode a base64 string back into a Uint8Array.
  * We store chunks as base64 in application_state because the SQL JSON
@@ -118,6 +133,10 @@ async function markRecordingReady(params: {
   finalHasAudio: boolean;
   finalHasCamera: boolean;
   existingTitle: string;
+  // Whether a seekable rewrite (MP4 faststart / WebM Cues remux) was already
+  // applied to the uploaded bytes. When false, a best-effort background repair
+  // is triggered so streamed/raw uploads still become seekable.
+  seekableApplied: boolean;
 }) {
   const {
     id,
@@ -131,6 +150,7 @@ async function markRecordingReady(params: {
     finalHasAudio,
     finalHasCamera,
     existingTitle,
+    seekableApplied,
   } = params;
   const db = getDb();
   const now = new Date().toISOString();
@@ -181,6 +201,30 @@ async function markRecordingReady(params: {
   });
   await writeAppState("refresh-signal", { ts: Date.now() });
 
+  if (seekableApplied) {
+    // Uploaded bytes are already start-playable and seekable — remember it so
+    // later reprocess sweeps skip this clip.
+    await markRecordingSeekable(id, videoUrl).catch((err) => {
+      console.warn("[finalize] failed to write seekable marker", {
+        id,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    });
+  } else {
+    // Streaming/resumable (or oversized) uploads shipped raw MediaRecorder
+    // bytes with no seekable rewrite: an MP4 with a trailing moov or a WebM
+    // without a Cues index buffers on load and re-buffers on every seek. Fix
+    // it in the background so playback is smooth without blocking finalize.
+    void Promise.resolve(
+      ensureRecordingSeekable({ recordingId: id, ownerEmail }),
+    ).catch((err: unknown) => {
+      console.warn("[finalize] background seekable remux failed", {
+        id,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    });
+  }
+
   // Kick off transcription in the background — fire-and-forget so the chunk
   // endpoint gets a quick response. The request context (user email via
   // AsyncLocalStorage) carries through to async continuations.
@@ -375,6 +419,10 @@ export default defineAction({
             ...readyParams,
             videoUrl,
             videoSizeBytes: resumableSession.bytesUploaded,
+            // Streaming path forwards raw MediaRecorder bytes straight to the
+            // provider — no faststart/Cues rewrite happened. Repair in the
+            // background.
+            seekableApplied: false,
           });
           // Delete only after durable state is written — so a retry before
           // this point can still find the session and re-enter this path.
@@ -521,9 +569,14 @@ export default defineAction({
       // recordings.
       parts.length = 0;
 
-      // Apply faststart to MP4 files — moves the moov atom before mdat so
-      // browsers can begin playback immediately via HTTP range requests.
+      // Make the assembled recording seekable before upload — we already hold
+      // the full bytes, so a viewer never has to wait through a non-seekable
+      // first play. MP4: relocate moov ahead of mdat (pure TS). WebM: remux to
+      // add a Cues index + real duration (ffmpeg -c copy). When neither runs
+      // (unknown format, oversized, or ffmpeg unavailable) `seekableApplied`
+      // stays false and markRecordingReady schedules a background repair.
       let uploadData = assembled;
+      let seekableApplied = false;
       if (videoFormat === "mp4") {
         try {
           uploadData = applyFaststart(assembled);
@@ -561,6 +614,32 @@ export default defineAction({
           }
           throw err;
         }
+        // moov is present and validated — the MP4 is start-playable/seekable.
+        seekableApplied = true;
+      } else if (videoFormat === "webm") {
+        // MediaRecorder WebM has no Cues index and an unknown duration, so
+        // Chrome buffers on load and re-buffers on every seek. A lossless
+        // `ffmpeg -c copy` remux rewrites it with a SeekHead + Cues + real
+        // duration. Bounded by size so finalize stays fast; larger clips get a
+        // background pass. Best-effort: on any failure we upload the original.
+        if (assembled.byteLength <= inlineRemuxMaxBytes()) {
+          try {
+            const seekable = await remuxWebmToSeekable(uploadData);
+            if (seekable.changed) {
+              uploadData = seekable.bytes;
+              seekableApplied = true;
+              debugLog("[finalize] webm remux applied", {
+                id,
+                bytes: uploadData.byteLength,
+              });
+            }
+          } catch (err) {
+            console.warn("[finalize] webm remux failed, uploading as-is", {
+              id,
+              err: err instanceof Error ? err.message : String(err),
+            });
+          }
+        }
       }
 
       let upload: Awaited<ReturnType<typeof uploadFile>>;
@@ -721,12 +800,13 @@ export default defineAction({
       debugLog("[finalize] done", {
         id,
         videoUrl: upload.url,
-        bytes: assembled.byteLength,
+        bytes: uploadData.byteLength,
       });
       return markRecordingReady({
         ...readyParams,
         videoUrl: upload.url,
-        videoSizeBytes: assembled.byteLength,
+        videoSizeBytes: uploadData.byteLength,
+        seekableApplied,
       });
     } finally {
       // Unconditional chunk scratch-space cleanup. Runs on success AND on