A demo by Trigger.dev

Convex × Trigger.dev

Choose a photo. Describe a change. Let Trigger.dev do the background work.

+ {(preview || !connected) && ( +

+ {preview + ? connectionError + ? "Connection unavailable. This is a read-only preview." + : "Read-only preview. Connect Convex to try an edit." + : "Connecting to Convex. Your saved images are still available below."} +

+ )} + +

1. Choose an image

+ +

+ +

2. Describe your edit

+ + Describe your edit + +

{
+                if (event.key === "Enter" && !event.shiftKey && !event.nativeEvent.isComposing) {
+                  event.preventDefault();
+                  event.currentTarget.form?.requestSubmit();
+                }
+              }}
+              onChange={(event) =>
+                selectDraft({ ...draft, prompt: event.target.value, preset: DEFAULT_PRESET })
+              }
+            />
+            {board?.turnstileSiteKey && <div className="turnstile" ref={widget} />}
+            <div className="submit-row">
+              <button
+                className="primary-button"
+                type="submit"
+                disabled={disabled}
+                aria-describedby={disabledReason ? "submit-reason" : undefined}
+              >
+                Submit
+              </button>
+            </div>
+            {disabledReason && (
+              <p id="submit-reason" className="muted" role="status">
+                {disabledReason}
+              </p>
+            )}
+          </form>
+          {restored && !editing && (
+            <p className="muted">{job ? "Restored your last edit." : "Restored your draft."}</p>
+          )}
+          {!busy && editor.selection && !job && board && (
+            <p className="muted">
+              Your previous submission is not available here. Submit to safely check the same
+              request again.
+            </p>
+          )}
+          {job && jobFinished(job) && (
+            <button
+              className="text-button"
+              type="button"
+              onClick={() => selectDraft({ ...draft, prompt: "" })}
+            >
+              New edit
+            </button>
+          )}
+          {storageError && (
+            <p className="error" role="alert">
+              {storageError}
+            </p>
+          )}
+          {error && (
+            <p className="error" role="alert">
+              {error}
+            </p>
+          )}
+        </section>
+
+        <div ref={resultSection} className="result-anchor">
+          <JobView
+            key={job?.id ?? "empty"}
+            job={job}
+            pending={pending}
+            preview={preview}
+            sessionToken={token}
+            onLoad={(job) => history.download(job, true)}
+          />
+          {history.error && (
+            <p className="error" role="alert">
+              {history.error}
+            </p>
+          )}
+        </div>
+
+        {jobs.length > 0 && (
+          <details className="history">
+            <summary>Previous edits</summary>
+            <ul>
+              {jobs.map((previous) => (
+                <li key={previous.id}>
+                  <button
+                    type="button"
+                    className="history-item"
+                    disabled={busy}
+                    onClick={() => {
+                      persistEditor({
+                        draft: draftFor(previous),
+                        selection: {
+                          key: keyFor(previous),
+                          id: previous.id,
+                          requestId: previous.requestId,
+                        },
+                      });
+                      setRestored(false);
+                      setError(null);
+                      showResult();
+                    }}
+                  >
+                    <strong>{SAMPLES.find((sample) => sample.id === previous.sample)?.name}</strong>
+                    <span>{previous.prompt}</span>
+                  </button>
+                </li>
+              ))}
+            </ul>
+            {history.jobs.length > 0 && (
+              <button
+                className="text-button"
+                type="button"
+                disabled={history.clearing}
+                onClick={() => void history.clear(remoteJobs.map((job) => job.id))}
+              >
+                {history.clearing ? "Clearing…" : "Clear local history"}
+              </button>
+            )}
+          </details>
+        )}
+      </main>
+      <footer>
+        <span>
+          Built by <a href="https://trigger.dev">Trigger.dev</a> with{" "}
+          <a href="https://convex.dev">Convex</a>.{" "}
+          <a
+            href="https://github.com/triggerdotdev/trigger.dev/tree/main/packages/convex#readme"
+            target="_blank"
+            rel="noreferrer"
+          >
+            Integration docs ↗
+          </a>
+        </span>
+        <span>
+          Private to this browser. Photos from{" "}
+          <a href={photograph.source} target="_blank" rel="noreferrer">
+            Unsplash
+          </a>
+          .
+        </span>
+      </footer>
+      <ImagePicker
+        open={pickerOpen}
+        selected={draft.sample}
+        onClose={() => setPickerOpen(false)}
+        onChoose={(sample) => selectDraft({ ...draft, sample, preset: DEFAULT_PRESET })}
+      />
+    </div>
+  );
+}
diff --git a/packages/convex/example/src/ImagePicker.tsx b/packages/convex/example/src/ImagePicker.tsx
new file mode 100644
index 00000000000..3664b7a08d5
--- /dev/null
+++ b/packages/convex/example/src/ImagePicker.tsx
@@ -0,0 +1,65 @@
+import { useEffect, useRef } from "react";
+import { SAMPLES } from "../shared/catalog";
+import type { SampleId } from "../shared/types";
+
+export function ImagePicker({
+  open,
+  selected,
+  onChoose,
+  onClose,
+}: {
+  open: boolean;
+  selected: SampleId;
+  onChoose: (sample: SampleId) => void;
+  onClose: () => void;
+}) {
+  const dialog = useRef<HTMLDialogElement>(null);
+  useEffect(() => {
+    const element = dialog.current;
+    if (open && !element?.open) element?.showModal();
+    if (!open && element?.open) element.close();
+  }, [open]);
+  return (
+    <dialog
+      ref={dialog}
+      className="image-picker"
+      aria-labelledby="image-picker-title"
+      onCancel={(event) => {
+        event.preventDefault();
+        onClose();
+      }}
+      closedby="any"
+      onClose={onClose}
+    >
+      <div className="dialog-heading">
+        <h2 id="image-picker-title">Choose an image</h2>
+        <button
+          type="button"
+          className="text-button"
+          onClick={onClose}
+          aria-label="Close image picker"
+        >
+          Close
+        </button>
+      </div>
+      {open && (
+        <div className="image-options">
+          {SAMPLES.map((sample) => (
+            <button
+              type="button"
+              key={sample.id}
+              aria-pressed={selected === sample.id}
+              onClick={() => {
+                onChoose(sample.id);
+                onClose();
+              }}
+            >
+              <img src={sample.file} alt="" loading="lazy" width={320} height={220} />
+              <span>{sample.name}</span>
+            </button>
+          ))}
+        </div>
+      )}
+    </dialog>
+  );
+}
diff --git a/packages/convex/example/src/JobPanel.tsx b/packages/convex/example/src/JobPanel.tsx
new file mode 100644
index 00000000000..af069299eb1
--- /dev/null
+++ b/packages/convex/example/src/JobPanel.tsx
@@ -0,0 +1,165 @@
+import { useState } from "react";
+import { SAMPLES } from "../shared/catalog";
+import type { Job } from "../shared/types";
+import { workflowPhase } from "./workflow";
+
+const TERMINAL = new Set([
+  "completed",
+  "failed",
+  "canceled",
+  "cancelled",
+  "crashed",
+  "expired",
+  "timed_out",
+  "system_failure",
+]);
+export function jobFinished(job: Job) {
+  return !!job.results.length || TERMINAL.has(job.status.toLowerCase());
+}
+
+export function JobPanel({
+  job,
+  pending,
+  preview,
+  onLoad,
+  realtimeProgress,
+  realtimePhase,
+  realtimeStatus,
+  realtimeCompleted = false,
+  realtimeIssue = false,
+}: {
+  job?: Job;
+  sessionToken?: string;
+  pending: boolean;
+  preview: boolean;
+  onLoad: (job: Job) => Promise<void>;
+  realtimeProgress?: number;
+  realtimePhase?: ReturnType<typeof workflowPhase>;
+  realtimeStatus?: string;
+  realtimeCompleted?: boolean;
+  realtimeIssue?: boolean;
+}) {
+  const [failedUrl, setFailedUrl] = useState<string | null>(null);
+  const image = job?.results.find((result) => result.kind === "hero") ?? job?.results[0];
+  const local = image?.url.startsWith("blob:");
+  const source = SAMPLES.find((sample) => sample.id === job?.sample);
+  const failed =
+    !!job && jobFinished(job) && !job.results.length && job.status.toLowerCase() !== "completed";
+  const displayStatus = realtimeStatus ?? job?.status ?? "";
+  const queued =
+    !!job &&
+    [
+      "pending",
+      "queued",
+      "enqueued",
+      "dequeued",
+      "delayed",
+      "reserved",
+      "pending_version",
+      "waiting_for_deploy",
+    ].includes(displayStatus.toLowerCase());
+  const active = !!job && !jobFinished(job);
+  const progress = job
+    ? Math.min(job.results.length ? 100 : 95, Math.max(job.progress, realtimeProgress ?? 0))
+    : 0;
+  const phase = realtimePhase ?? workflowPhase(progress, !!job?.results.length);
+  const message = pending
+    ? "Sending your edit to Convex…"
+    : failed
+      ? "This edit could not be completed."
+      : image
+        ? "Loading your edited image…"
+        : realtimeCompleted
+          ? "Checking your image with Convex…"
+          : queued
+            ? "Your edit is queued on Trigger.dev."
+            : active
+              ? phase === "prepare"
+                ? "Trigger.dev is preparing your image."
+                : phase === "edit"
+                  ? "Trigger.dev is applying your edit."
+                  : "Trigger.dev is finishing your image."
+              : job
+                ? "Your image is being checked before delivery."
+                : preview
+                  ? "Connect Convex to try an edit."
+                  : "Your edited image will appear here.";
+
+  return (
+    <section
+      className="step result-step"
+      id="result"
+      aria-labelledby="result-title"
+      aria-busy={pending || active}
+    >
+      <h2 id="result-title">3. Your image</h2>
+      {local && image && failedUrl !== image.url ? (
+        <>
+          <img
+            className="edited-image"
+            src={image.url}
+            alt={`Edited ${source?.name ?? "photograph"}`}
+            onError={() => setFailedUrl(image.url)}
+          />
+          <div className="image-actions">
+            <a className="download-button" href={image.url} download={`${job!.sample}-edited.avif`}>
+              Download image
+            </a>
+          </div>
+        </>
+      ) : (
+        <div className="result-placeholder" role="status">
+          <p>
+            {local
+              ? "The image preview could not be displayed. You can still download it."
+              : message}
+          </p>
+          {job && !failed && !image && (
+            <div className="workflow-progress" aria-label={`Image editing progress: ${phase}`}>
+              <progress max={100} value={progress} />
+              <ol>
+                {(["Prepare", "Edit", "Finish"] as const).map((label, index) => {
+                  const phases = ["prepare", "edit", "finish"];
+                  const current = phase === phases[index];
+                  const complete = phases.indexOf(phase) > index || phase === "ready";
+                  return (
+                    <li
+                      key={label}
+                      className={current ? "current" : complete ? "complete" : ""}
+                      aria-current={current ? "step" : undefined}
+                    >
+                      {label}
+                    </li>
+                  );
+                })}
+              </ol>
+            </div>
+          )}
+          {active && realtimeIssue && (
+            <span className="muted">Live updates unavailable; showing saved progress.</span>
+          )}
+          {active && (
+            <p className="muted">
+              The job continues in the background, even if you close this tab.
+            </p>
+          )}
+          {image && !local && (
+            <button type="button" className="text-button" onClick={() => void onLoad(job!)}>
+              Load image
+            </button>
+          )}
+          {local && image && (
+            <a href={image.url} download={`${job!.sample}-edited.avif`}>
+              Download image
+            </a>
+          )}
+          {failed && (
+            <p className="error" role="alert">
+              {job.error ?? "Please try again."}
+            </p>
+          )}
+        </div>
+      )}
+    </section>
+  );
+}
diff --git a/packages/convex/example/src/RealtimeJobPanel.tsx b/packages/convex/example/src/RealtimeJobPanel.tsx
new file mode 100644
index 00000000000..bba89180aca
--- /dev/null
+++ b/packages/convex/example/src/RealtimeJobPanel.tsx
@@ -0,0 +1,111 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useAction, useMutation } from "convex/react";
+import { useRealtimeRun } from "@trigger.dev/react-hooks";
+import { api } from "../convex/_generated/api";
+import type { Id } from "../convex/_generated/dataModel";
+import type { Job } from "../shared/types";
+import { JobPanel, jobFinished } from "./JobPanel";
+import { progressFromRun, workflowPhase } from "./workflow";
+
+type Credential = {
+  accessToken: string;
+  baseURL: string;
+  expiresAt: number;
+  runId: string;
+  jobId: string;
+  sessionToken: string;
+};
+type Props = {
+  job?: Job;
+  pending: boolean;
+  preview: boolean;
+  sessionToken: string;
+  onLoad: (job: Job) => Promise<void>;
+};
+
+export function RealtimeJobPanel({ job, pending, preview, sessionToken, onLoad }: Props) {
+  const mint = useAction(api.realtime.token);
+  const refreshJob = useMutation(api.jobs.refresh);
+  const [credential, setCredential] = useState<Credential>();
+  const [streamIssue, setStreamIssue] = useState(false);
+  const [refreshIssue, setRefreshIssue] = useState(false);
+  const attemptedRefreshes = useRef(new Set<string>());
+
+  const canStream =
+    !!job?.realtimeEligible && !!job.runId && !job.results.length && !jobFinished(job);
+  const identity = canStream ? `${job.id}:${job.runId}:${sessionToken}` : "";
+  const identityRef = useRef(identity);
+  identityRef.current = identity;
+  const jobId = job?.id;
+
+  const mintToken = useCallback(async () => {
+    if (!jobId || !identity || identityRef.current !== identity)
+      throw new Error("Realtime unavailable");
+    const next = await mint({ jobId: jobId as Id<"edits">, sessionToken });
+    if (!next) throw new Error("Realtime unavailable");
+    if (identityRef.current !== identity) throw new Error("Realtime credential expired");
+    setCredential({ ...next, jobId, sessionToken });
+    setStreamIssue(false);
+    return next.accessToken;
+  }, [identity, jobId, mint, sessionToken]);
+
+  useEffect(() => {
+    setCredential(undefined);
+    setStreamIssue(false);
+    setRefreshIssue(false);
+    if (!canStream) return;
+    let cancelled = false;
+    void mintToken().catch(() => {
+      if (!cancelled && identityRef.current === identity) setStreamIssue(true);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [canStream, identity, mintToken]);
+
+  const matchingCredential =
+    !!credential &&
+    credential.jobId === job?.id &&
+    credential.runId === job?.runId &&
+    credential.sessionToken === sessionToken;
+  const enabled = canStream && !!matchingCredential;
+  const runId = enabled ? (job?.runId ?? undefined) : undefined;
+  const { run, error } = useRealtimeRun(runId, {
+    enabled,
+    accessToken: matchingCredential ? credential?.accessToken : undefined,
+    baseURL: matchingCredential ? credential?.baseURL : undefined,
+    refreshAccessToken: mintToken,
+  });
+
+  const matchingRun = enabled && run?.id === job?.runId ? run : undefined;
+  const realtimeStatus = matchingRun ? String(matchingRun.status).toUpperCase() : undefined;
+  const realtimeCompleted =
+    !!matchingRun &&
+    (matchingRun.isCompleted || ["EXPIRED", "TIMED_OUT"].includes(realtimeStatus ?? ""));
+
+  useEffect(() => {
+    if (!job || !matchingRun || !realtimeCompleted) return;
+    const key = `${job.id}:${matchingRun.id}`;
+    if (attemptedRefreshes.current.has(key)) return;
+    attemptedRefreshes.current.add(key);
+    void refreshJob({ jobId: job.id as Id<"edits">, sessionToken }).catch(() => {
+      setRefreshIssue(true);
+    });
+  }, [job, matchingRun, realtimeCompleted, refreshJob, sessionToken]);
+
+  const progress = job ? progressFromRun(job, matchingRun) : 0;
+  const phase = workflowPhase(progress, !!job?.results.length);
+  return (
+    <JobPanel
+      job={job}
+      pending={pending}
+      preview={preview}
+      onLoad={onLoad}
+      realtimeProgress={progress}
+      realtimePhase={matchingRun ? phase : undefined}
+      realtimeStatus={realtimeStatus}
+      realtimeCompleted={realtimeCompleted}
+      realtimeIssue={streamIssue || refreshIssue || (enabled && !!error)}
+    />
+  );
+}
diff --git a/packages/convex/example/src/cache.ts b/packages/convex/example/src/cache.ts
new file mode 100644
index 00000000000..017aead0f59
--- /dev/null
+++ b/packages/convex/example/src/cache.ts
@@ -0,0 +1,94 @@
+import type { ImageResult, Job } from "../shared/types";
+
+const DATABASE = "convex-image-processing";
+const STORE = "jobs";
+export const MAX_HISTORY = 20;
+
+type CachedResult = Omit<ImageResult, "url"> & { blob: Blob };
+type CachedJob = Omit<Job, "results"> & { results: CachedResult[] };
+
+async function openDatabase(sessionToken: string): Promise<IDBDatabase> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(sessionToken));
+  const scope = Array.from(new Uint8Array(digest), (byte) =>
+    byte.toString(16).padStart(2, "0")
+  ).join("");
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(`${DATABASE}-${scope}`, 1);
+    request.onupgradeneeded = () => request.result.createObjectStore(STORE, { keyPath: "id" });
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () =>
+      reject(request.error ?? new Error("Could not open local image history."));
+  });
+}
+
+async function transact<T>(
+  sessionToken: string,
+  mode: IDBTransactionMode,
+  action: (store: IDBObjectStore) => IDBRequest<T>
+): Promise<T> {
+  const db = await openDatabase(sessionToken);
+  return new Promise((resolve, reject) => {
+    const transaction = db.transaction(STORE, mode);
+    const request = action(transaction.objectStore(STORE));
+    let result: T;
+    request.onsuccess = () => {
+      result = request.result;
+    };
+    transaction.oncomplete = () => {
+      db.close();
+      resolve(result);
+    };
+    transaction.onabort = () => {
+      db.close();
+      reject(transaction.error ?? request.error ?? new Error("Local image history failed."));
+    };
+  });
+}
+
+export async function listCachedJobs(sessionToken: string): Promise<CachedJob[]> {
+  const jobs = await transact<CachedJob[]>(sessionToken, "readonly", (store) => store.getAll());
+  return jobs.sort((a, b) => b.createdAt - a.createdAt).slice(0, MAX_HISTORY);
+}
+
+export async function saveCachedJob(job: Job, blobs: Blob[], sessionToken: string): Promise<void> {
+  const record: CachedJob = {
+    ...job,
+    results: job.results.map((result, index) => {
+      const { url: _url, ...metadata } = result;
+      return { ...metadata, blob: blobs[index] };
+    }),
+  };
+  const db = await openDatabase(sessionToken);
+  await new Promise<void>((resolve, reject) => {
+    const transaction = db.transaction(STORE, "readwrite");
+    const store = transaction.objectStore(STORE);
+    store.put(record);
+    const all = store.getAll() as IDBRequest<CachedJob[]>;
+    all.onsuccess = () => {
+      const excess = all.result.sort((a, b) => b.createdAt - a.createdAt).slice(MAX_HISTORY);
+      for (const old of excess) store.delete(old.id);
+    };
+    transaction.oncomplete = () => {
+      db.close();
+      resolve();
+    };
+    transaction.onabort = () => {
+      db.close();
+      reject(transaction.error ?? all.error ?? new Error("Could not save local images."));
+    };
+  });
+}
+
+export async function clearCachedJobs(sessionToken: string): Promise<void> {
+  await transact<undefined>(sessionToken, "readwrite", (store) => store.clear());
+}
+
+export function withObjectUrls(job: CachedJob): Job {
+  return {
+    ...job,
+    results: job.results.map(({ blob, ...result }) => ({
+      ...result,
+      url: URL.createObjectURL(blob),
+    })),
+  };
+}
diff --git a/packages/convex/example/src/connection.tsx b/packages/convex/example/src/connection.tsx
new file mode 100644
index 00000000000..6197e5a37a0
--- /dev/null
+++ b/packages/convex/example/src/connection.tsx
@@ -0,0 +1,30 @@
+import { Component, type ReactNode } from "react";
+import { useAction, useConvexConnectionState, useQuery } from "convex/react";
+import { api } from "../convex/_generated/api";
+import App, { getSessionToken } from "./App";
+import { RealtimeJobPanel } from "./RealtimeJobPanel";
+
+export function ConnectedApp() {
+  const sessionToken = getSessionToken();
+  const board = useQuery(api.jobs.board, { sessionToken });
+  const processImages = useAction(api.jobs.process);
+  const connection = useConvexConnectionState();
+  return (
+    <App
+      board={board}
+      processImages={processImages}
+      connected={connection.isWebSocketConnected}
+      JobView={RealtimeJobPanel}
+    />
+  );
+}
+
+export class ConnectionBoundary extends Component<{ children: ReactNode }, { failed: boolean }> {
+  state = { failed: false };
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+  render() {
+    return this.state.failed ? <App preview connectionError /> : this.props.children;
+  }
+}
diff --git a/packages/convex/example/src/editorState.test.ts b/packages/convex/example/src/editorState.test.ts
new file mode 100644
index 00000000000..8e01f13ebd1
--- /dev/null
+++ b/packages/convex/example/src/editorState.test.ts
@@ -0,0 +1,62 @@
+import { afterEach, beforeEach, expect, test, vi } from "vitest";
+import { draftFor, emptyEditor, keyFor, readEditor, selectedJob, writeEditor } from "./editorState";
+import type { Job } from "../shared/types";
+
+const OWNER = "a".repeat(64);
+const job: Job = {
+  id: "new-edit",
+  requestId: "submitted-request",
+  sample: "coast",
+  preset: "balanced",
+  prompt: "Turn the waves gold",
+  createdAt: 1,
+  expiresAt: Date.now() + 60_000,
+  status: "EXECUTING",
+  syncStatus: "polling",
+  progress: 25,
+  stage: "Editing",
+  runId: "run-example",
+  error: null,
+  results: [],
+};
+beforeEach(() => {
+  const values = new Map<string, string>();
+  vi.stubGlobal("localStorage", {
+    getItem: (key: string) => values.get(key) ?? null,
+    setItem: (key: string, value: string) => {
+      values.set(key, value);
+    },
+  });
+});
+afterEach(() => vi.unstubAllGlobals());
+
+test("reload preserves the exact photo, prompt, and selected background job", () => {
+  const editor = { draft: draftFor(job), selection: { key: keyFor(job), id: job.id } };
+  writeEditor(OWNER, editor);
+  expect(readEditor(OWNER)).toEqual(editor);
+  expect(selectedJob(readEditor(OWNER), [job])?.id).toBe(job.id);
+});
+
+test("reload before the submission response finds its job by request ID, not old matching inputs", () => {
+  writeEditor(OWNER, {
+    draft: draftFor(job),
+    selection: { key: keyFor(job), requestId: job.requestId },
+  });
+  const old = { ...job, id: "old-edit", requestId: "old-request", status: "COMPLETED" };
+  expect(selectedJob(readEditor(OWNER), [old])).toBeUndefined();
+  expect(selectedJob(readEditor(OWNER), [old, job])?.id).toBe(job.id);
+  expect(selectedJob(readEditor(OWNER), [{ ...job, status: "COMPLETED" }])?.id).toBe(job.id);
+});
+
+test("a new browser session does not inherit another session's saved editor", () => {
+  writeEditor(OWNER, { draft: draftFor(job), selection: { key: keyFor(job), id: job.id } });
+  expect(readEditor("b".repeat(64))).toEqual(emptyEditor());
+});
+
+test("edited inputs never display the previously selected result", () => {
+  const editor = {
+    draft: { ...draftFor(job), prompt: "A different edit" },
+    selection: { key: keyFor(job), id: job.id },
+  };
+  expect(selectedJob(editor, [job])).toBeUndefined();
+});
diff --git a/packages/convex/example/src/editorState.ts b/packages/convex/example/src/editorState.ts
new file mode 100644
index 00000000000..8fb7ca21bf8
--- /dev/null
+++ b/packages/convex/example/src/editorState.ts
@@ -0,0 +1,66 @@
+import { PRESETS, PROMPT_LIMIT, SAMPLES } from "../shared/catalog";
+import type { Job } from "../shared/types";
+
+export type Draft = Pick<Job, "sample" | "preset" | "prompt">;
+export type Selection = { key: string; id?: string; requestId?: string };
+export type EditorState = { draft: Draft; selection: Selection | null };
+const STORAGE_KEY = "convex-image-processing-editor";
+
+export const keyFor = (draft: Draft) =>
+  JSON.stringify([draft.sample, draft.preset, draft.prompt.trim()]);
+export const draftFor = ({ sample, preset, prompt }: Draft): Draft => ({ sample, preset, prompt });
+export const emptyEditor = (): EditorState => ({
+  draft: { sample: SAMPLES[0]!.id, preset: "balanced", prompt: "" },
+  selection: null,
+});
+
+export function readEditor(sessionToken: string): EditorState {
+  try {
+    const saved = JSON.parse(localStorage.getItem(STORAGE_KEY) ?? "null");
+    const draft = saved?.draft;
+    if (
+      saved?.sessionToken !== sessionToken ||
+      !SAMPLES.some((sample) => sample.id === draft?.sample) ||
+      !PRESETS.some((preset) => preset.id === draft?.preset) ||
+      typeof draft?.prompt !== "string" ||
+      draft.prompt.length > PROMPT_LIMIT
+    )
+      return emptyEditor();
+    const selection = saved.selection;
+    return {
+      draft: draftFor(draft),
+      selection:
+        selection?.key === keyFor(draft) &&
+        (typeof selection.id === "string" || typeof selection.requestId === "string")
+          ? {
+              key: selection.key,
+              id: typeof selection.id === "string" ? selection.id : undefined,
+              requestId: typeof selection.requestId === "string" ? selection.requestId : undefined,
+            }
+          : null,
+    };
+  } catch {
+    return emptyEditor();
+  }
+}
+
+export function writeEditor(sessionToken: string, editor: EditorState): boolean {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify({ sessionToken, ...editor }));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function selectedJob(editor: EditorState, jobs: Job[]): Job | undefined {
+  const selected = editor.selection;
+  if (!selected || selected.key !== keyFor(editor.draft)) return undefined;
+  return jobs.find(
+    (job) =>
+      keyFor(job) === selected.key &&
+      (selected.id
+        ? job.id === selected.id
+        : !!selected.requestId && job.requestId === selected.requestId)
+  );
+}
diff --git a/packages/convex/example/src/main.tsx b/packages/convex/example/src/main.tsx
new file mode 100644
index 00000000000..f63cb9bda9b
--- /dev/null
+++ b/packages/convex/example/src/main.tsx
@@ -0,0 +1,31 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { ConvexProvider, ConvexReactClient } from "convex/react";
+import App from "./App";
+import { ConnectedApp, ConnectionBoundary } from "./connection";
+import "./styles.css";
+
+const url = import.meta.env.VITE_CONVEX_URL?.trim();
+let client: ConvexReactClient | undefined;
+let invalidUrl = false;
+if (url) {
+  try {
+    client = new ConvexReactClient(url);
+  } catch {
+    invalidUrl = true;
+  }
+}
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    {client ? (
+      <ConnectionBoundary>
+        <ConvexProvider client={client}>
+          <ConnectedApp />
+        </ConvexProvider>
+      </ConnectionBoundary>
+    ) : (
+      <App preview connectionError={invalidUrl} />
+    )}
+  </StrictMode>
+);
diff --git a/packages/convex/example/src/styles.css b/packages/convex/example/src/styles.css
new file mode 100644
index 00000000000..67e8f2f61e3
--- /dev/null
+++ b/packages/convex/example/src/styles.css
@@ -0,0 +1,407 @@
+:root {
+  font-family: Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  color: #242925;
+  background: #f8f9f8;
+  font-synthesis: none;
+  -webkit-font-smoothing: antialiased;
+  --muted: #68716b;
+  --border: #dfe4df;
+  --mint: #3fffa8;
+}
+* {
+  box-sizing: border-box;
+}
+body {
+  margin: 0;
+}
+button,
+textarea {
+  font: inherit;
+}
+a {
+  color: inherit;
+  text-underline-offset: 3px;
+}
+button,
+a {
+  -webkit-tap-highlight-color: transparent;
+}
+button {
+  cursor: pointer;
+}
+button:disabled {
+  cursor: not-allowed;
+  opacity: 0.55;
+}
+:focus-visible {
+  outline: 2px solid #087745;
+  outline-offset: 4px;
+}
+h1,
+h2,
+p {
+  margin: 0;
+}
+img {
+  display: block;
+  max-width: 100%;
+}
+.app-shell {
+  max-width: 880px;
+  padding: 0 28px;
+  margin: 0 auto;
+}
+main {
+  max-width: 704px;
+  margin: 0 auto;
+}
+.intro {
+  padding: 26px 0 20px;
+}
+.byline {
+  font-size: 12px;
+  color: var(--muted);
+  margin-bottom: 8px;
+}
+h1 {
+  font-size: clamp(30px, 5vw, 43px);
+  letter-spacing: -1.5px;
+  line-height: 1.2;
+  font-weight: 650;
+}
+.intro > p:last-child {
+  margin-top: 10px;
+  font-size: 15px;
+  line-height: 1.7;
+  color: #505b53;
+}
+.banner {
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 13px 16px;
+  margin-bottom: 22px;
+  color: var(--muted);
+  font-size: 13px;
+  line-height: 1.6;
+}
+.step {
+  background: #fff;
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 18px;
+  margin-bottom: 14px;
+}
+h2 {
+  font-size: 17px;
+  font-weight: 650;
+  letter-spacing: -0.3px;
+  margin-bottom: 12px;
+}
+.step-heading {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  margin-bottom: 12px;
+}
+.step-heading h2 {
+  margin: 0;
+}
+.choose-button {
+  min-height: 40px;
+  padding: 9px 14px;
+  border: 1px solid #cdd4cd;
+  border-radius: 5px;
+  background: #fff;
+  color: #276244;
+  font-size: 14px;
+  font-weight: 550;
+}
+.choose-button:hover:not(:disabled) {
+  background: #f1f8f3;
+}
+.source-image,
+.edited-image {
+  width: 100%;
+  max-height: 320px;
+  object-fit: contain;
+  border-radius: 4px;
+  background: #f1f3f0;
+}
+.image-actions {
+  display: flex;
+  justify-content: flex-end;
+  margin-top: 10px;
+  font-size: 13px;
+}
+.text-button {
+  padding: 5px 0;
+  border: 0;
+  background: transparent;
+  color: #276244;
+  font-size: 13px;
+  text-decoration: underline;
+  text-underline-offset: 3px;
+}
+textarea {
+  width: 100%;
+  display: block;
+  min-height: 105px;
+  resize: vertical;
+  border: 1px solid #cdd4cd;
+  border-radius: 5px;
+  padding: 12px 14px;
+  color: inherit;
+  background: #fff;
+  font-size: 14px;
+  line-height: 1.65;
+}
+textarea:disabled {
+  background: #f8f9f8;
+  color: var(--muted);
+}
+.submit-row {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  margin-top: 12px;
+}
+.muted {
+  color: var(--muted);
+  font-size: 12px;
+  line-height: 1.65;
+}
+.primary-button {
+  padding: 11px 20px;
+  border: 1px solid #2ae995;
+  border-radius: 5px;
+  background: var(--mint);
+  color: #123624;
+  font-size: 14px;
+  font-weight: 600;
+  white-space: nowrap;
+}
+.primary-button:hover:not(:disabled) {
+  background: #31f59b;
+}
+.primary-button:disabled {
+  background: #eef1ed;
+  color: var(--muted);
+  border-color: var(--border);
+  opacity: 1;
+}
+.turnstile {
+  margin-top: 14px;
+}
+.error {
+  padding: 12px 14px;
+  margin-top: 14px;
+  background: #fff5f3;
+  color: #8f3126;
+  border: 1px solid #f0d2cd;
+  border-radius: 5px;
+  font-size: 13px;
+  line-height: 1.6;
+  overflow-wrap: anywhere;
+}
+.result-anchor {
+  scroll-margin-top: 24px;
+}
+.result-placeholder {
+  min-height: 88px;
+  padding: 20px 14px;
+  display: grid;
+  justify-items: center;
+  align-content: center;
+  gap: 8px;
+  text-align: center;
+  border-radius: 5px;
+  background: #f8f9f7;
+  color: #505b53;
+  font-size: 14px;
+  line-height: 1.6;
+}
+.workflow-progress {
+  width: min(320px, 100%);
+}
+.workflow-progress progress {
+  width: 100%;
+  height: 7px;
+  accent-color: #159757;
+}
+.workflow-progress ol {
+  display: flex;
+  justify-content: space-between;
+  padding: 0;
+  margin: 5px 0 0;
+  list-style: none;
+  color: #879089;
+  font-size: 11px;
+}
+.workflow-progress li.current {
+  color: #276244;
+  font-weight: 600;
+}
+.workflow-progress li.complete {
+  color: #505b53;
+}
+@media (prefers-reduced-motion: no-preference) {
+  .workflow-progress progress::-webkit-progress-value {
+    transition: width 180ms ease;
+  }
+}
+.download-button {
+  display: inline-block;
+  padding: 9px 14px;
+  background: #f1f8f3;
+  border: 1px solid #cadfd0;
+  border-radius: 5px;
+  color: #226342;
+  text-decoration: none;
+  font-weight: 550;
+}
+.history {
+  padding: 0 3px;
+  margin: 4px 0 16px;
+  font-size: 13px;
+  color: var(--muted);
+}
+.history summary {
+  cursor: pointer;
+}
+.history ul {
+  list-style: none;
+  padding: 0;
+  margin: 12px 0;
+}
+.history-item {
+  display: flex;
+  gap: 14px;
+  align-items: baseline;
+  width: 100%;
+  text-align: left;
+  padding: 10px 0;
+  border: 0;
+  border-bottom: 1px solid var(--border);
+  background: transparent;
+  color: inherit;
+  font-size: 12px;
+}
+.history-item strong {
+  min-width: 85px;
+  color: #38463c;
+  font-weight: 550;
+}
+.history-item span {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+footer {
+  display: flex;
+  justify-content: space-between;
+  gap: 16px;
+  margin-top: 20px;
+  padding: 16px 0 20px;
+  border-top: 1px solid var(--border);
+  color: var(--muted);
+  font-size: 11px;
+  line-height: 1.7;
+}
+.image-picker {
+  width: min(760px, calc(100% - 32px));
+  max-height: 85vh;
+  padding: 24px;
+  background: #fff;
+  color: inherit;
+  border: 1px solid var(--border);
+  border-radius: 10px;
+}
+.image-picker::backdrop {
+  background: rgb(12 22 16 / 45%);
+}
+.dialog-heading {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 20px;
+  margin-bottom: 18px;
+}
+.dialog-heading h2 {
+  margin: 0;
+}
+.image-options {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 14px;
+}
+.image-options button {
+  text-align: left;
+  padding: 5px;
+  border: 1px solid var(--border);
+  border-radius: 5px;
+  color: inherit;
+  background: #fff;
+}
+.image-options button[aria-pressed="true"] {
+  border-color: #248653;
+  box-shadow: 0 0 0 1px #248653;
+  background: #f1fbf5;
+}
+.image-options img {
+  width: 100%;
+  height: auto;
+  aspect-ratio: 3 / 2;
+  object-fit: cover;
+  border-radius: 3px;
+}
+.image-options span {
+  display: block;
+  padding: 8px 5px 4px;
+  font-size: 13px;
+}
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+@media (max-width: 600px) {
+  .app-shell {
+    padding: 0 18px;
+  }
+  .intro {
+    padding: 22px 0 16px;
+  }
+  .step {
+    padding: 16px;
+  }
+  .submit-row {
+    align-items: stretch;
+    flex-direction: column;
+  }
+  .image-options {
+    grid-template-columns: repeat(2, 1fr);
+    gap: 10px;
+  }
+  .image-picker {
+    padding: 18px;
+  }
+  footer {
+    flex-direction: column;
+    gap: 6px;
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    scroll-behavior: auto !important;
+  }
+}
diff --git a/packages/convex/example/src/usePrivateHistory.ts b/packages/convex/example/src/usePrivateHistory.ts
new file mode 100644
index 00000000000..858d9510302
--- /dev/null
+++ b/packages/convex/example/src/usePrivateHistory.ts
@@ -0,0 +1,143 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { Job } from "../shared/types";
+import {
+  clearCachedJobs,
+  listCachedJobs,
+  MAX_HISTORY,
+  saveCachedJob,
+  withObjectUrls,
+} from "./cache";
+
+export function usePrivateHistory(token: string) {
+  const [jobs, setJobs] = useState<Job[]>([]);
+  const [error, setError] = useState<string | null>(null);
+  const [clearing, setClearing] = useState(false);
+  const stored = useRef(new Map<string, Job>());
+  const downloads = useRef(new Map<string, Promise<void>>());
+  const dismissed = useRef(new Set<string>());
+  const generation = useRef(0);
+  const clearingRef = useRef(false);
+
+  const remember = useCallback((job: Job) => {
+    const previous = stored.current.get(job.id);
+    if (previous) previous.results.forEach((result) => URL.revokeObjectURL(result.url));
+    stored.current.set(job.id, job);
+    const latest = [...stored.current.values()].sort((a, b) => b.createdAt - a.createdAt);
+    for (const old of latest.slice(MAX_HISTORY)) {
+      old.results.forEach((result) => URL.revokeObjectURL(result.url));
+      stored.current.delete(old.id);
+    }
+    setJobs(latest.slice(0, MAX_HISTORY));
+  }, []);
+
+  const releaseHistory = useCallback(() => {
+    generation.current++;
+    for (const job of stored.current.values())
+      job.results.forEach((result) => URL.revokeObjectURL(result.url));
+    stored.current.clear();
+  }, []);
+
+  useEffect(() => {
+    if (!token) return;
+    const current = ++generation.current;
+    void listCachedJobs(token)
+      .then((cached) => {
+        if (current !== generation.current) return;
+        for (const job of cached) {
+          if (!stored.current.has(job.id)) remember(withObjectUrls(job));
+        }
+      })
+      .catch(() => {
+        if (current === generation.current)
+          setError(
+            "Browser storage is unavailable. You can still download your image while this page is open."
+          );
+      });
+    return releaseHistory;
+  }, [token, remember, releaseHistory]);
+
+  const download = useCallback(
+    (remote: Job, explicit = false): Promise<void> => {
+      if (
+        !token ||
+        clearingRef.current ||
+        !remote.results.length ||
+        stored.current.has(remote.id) ||
+        (!explicit && dismissed.current.has(remote.id))
+      )
+        return Promise.resolve();
+      const pending = downloads.current.get(remote.id);
+      if (pending) return pending;
+      const current = generation.current;
+      const operation = (async () => {
+        try {
+          const blobs = await Promise.all(
+            remote.results.map(async (result) => {
+              const response = await fetch(result.url, {
+                headers: { Authorization: `Bearer ${token}` },
+                signal: AbortSignal.timeout(20_000),
+              });
+              if (!response.ok || !response.headers.get("Content-Type")?.includes("image/avif"))
+                throw new Error("Image unavailable");
+              const blob = await response.blob();
+              if (blob.size !== result.bytes) throw new Error("Incomplete image");
+              return blob;
+            })
+          );
+          if (current !== generation.current) return;
+          let cacheError: string | null = null;
+          try {
+            await saveCachedJob(remote, blobs, token);
+          } catch {
+            cacheError =
+              "Your image could not be saved in this browser. Download it to keep a copy.";
+          }
+          if (current !== generation.current) return;
+          remember({
+            ...remote,
+            results: remote.results.map((result, index) => ({
+              ...result,
+              url: URL.createObjectURL(blobs[index]!),
+            })),
+          });
+          setError(cacheError);
+        } catch {
+          if (current === generation.current)
+            setError("Your image could not be loaded. Its temporary server copy may have expired.");
+        } finally {
+          downloads.current.delete(remote.id);
+        }
+      })();
+      downloads.current.set(remote.id, operation);
+      return operation;
+    },
+    [token, remember]
+  );
+
+  const clear = useCallback(
+    async (remoteIds: string[]) => {
+      if (clearingRef.current) return;
+      clearingRef.current = true;
+      setClearing(true);
+      generation.current++;
+      remoteIds.forEach((id) => dismissed.current.add(id));
+      try {
+        await Promise.allSettled(downloads.current.values());
+        await clearCachedJobs(token);
+        for (const job of stored.current.values())
+          job.results.forEach((result) => URL.revokeObjectURL(result.url));
+        stored.current.clear();
+        setJobs([]);
+        setError(null);
+      } catch {
+        setError("Local history could not be cleared. Please try again.");
+      } finally {
+        clearingRef.current = false;
+        setClearing(false);
+      }
+    },
+    [token]
+  );
+
+  return { jobs, error, download, clear, clearing };
+}
diff --git a/packages/convex/example/src/workflow.test.ts b/packages/convex/example/src/workflow.test.ts
new file mode 100644
index 00000000000..d87dcc002dc
--- /dev/null
+++ b/packages/convex/example/src/workflow.test.ts
@@ -0,0 +1,43 @@
+import { expect, test } from "vitest";
+import type { Job } from "../shared/types";
+import { progressFromRun, workflowPhase } from "./workflow";
+
+const job: Job = {
+  id: "job",
+  sample: "forest",
+  prompt: "edit",
+  preset: "balanced",
+  createdAt: 0,
+  expiresAt: 1,
+  status: "EXECUTING",
+  syncStatus: "pending",
+  progress: 25,
+  stage: "Editing",
+  runId: "run",
+  error: null,
+  results: [],
+};
+
+test("Realtime completion does not mark the image ready before Convex publishes results", () => {
+  expect(progressFromRun(job, { id: "run", metadata: { progress: 100 } })).toBe(95);
+  expect(workflowPhase(95, false)).toBe("finish");
+});
+
+test("ignores workflow metadata from a different run", () => {
+  expect(progressFromRun(job, { id: "other-run", metadata: { progress: 90 } })).toBe(25);
+});
+
+test("ignores non-finite progress metadata", () => {
+  expect(
+    progressFromRun(job, { id: "run", metadata: { progress: Number.POSITIVE_INFINITY } })
+  ).toBe(25);
+});
+
+test("counts ready flags idempotently", () => {
+  const run = {
+    id: "run",
+    metadata: { phase: "finish", heroReady: true, cardReady: true, squareReady: false },
+  };
+  expect(progressFromRun(job, run)).toBe(85);
+  expect(progressFromRun(job, run)).toBe(85);
+});
diff --git a/packages/convex/example/src/workflow.ts b/packages/convex/example/src/workflow.ts
new file mode 100644
index 00000000000..5d894b03e74
--- /dev/null
+++ b/packages/convex/example/src/workflow.ts
@@ -0,0 +1,35 @@
+import type { Job } from "../shared/types";
+
+export type WorkflowPhase = "prepare" | "edit" | "finish" | "ready";
+
+function finiteNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+export function progressFromRun(job: Job, run: unknown): number {
+  if (!run || typeof run !== "object") return Math.min(job.progress, job.results.length ? 100 : 95);
+  const snapshot = run as { id?: unknown; metadata?: unknown };
+  if (snapshot.id !== job.runId) return Math.min(job.progress, job.results.length ? 100 : 95);
+  const metadata = snapshot.metadata;
+  const record =
+    metadata && typeof metadata === "object" ? (metadata as Record<string, unknown>) : {};
+  const phaseProgress = finiteNumber(record.progress) ?? 0;
+  const readyFlags = [record.heroReady, record.cardReady, record.squareReady];
+  const hasReadyFlags = readyFlags.some((flag) => typeof flag === "boolean");
+  const completedExports = hasReadyFlags
+    ? readyFlags.filter((flag) => flag === true).length
+    : finiteNumber(record.completedExports);
+  const exportProgress =
+    record.phase === "finish" && completedExports !== undefined
+      ? 65 + Math.max(0, Math.min(3, completedExports)) * 10
+      : 0;
+  const progress = Math.max(job.progress, phaseProgress, exportProgress);
+  return Math.max(0, Math.min(job.results.length ? 100 : 95, progress));
+}
+
+export function workflowPhase(progress: number, hasResults: boolean): WorkflowPhase {
+  if (hasResults) return "ready";
+  if (progress < 25) return "prepare";
+  if (progress < 65) return "edit";
+  return "finish";
+}
diff --git a/packages/convex/example/trigger.config.ts b/packages/convex/example/trigger.config.ts
new file mode 100644
index 00000000000..c7127f7ebad
--- /dev/null
+++ b/packages/convex/example/trigger.config.ts
@@ -0,0 +1,15 @@
+import { defineConfig } from "@trigger.dev/sdk";
+import { additionalFiles } from "@trigger.dev/build/extensions/core";
+
+export default defineConfig({
+  project: "proj_wcwcgcodbajkuocrovpq",
+  runtime: "node-24",
+  dirs: ["./trigger"],
+  maxDuration: 120,
+  retries: { default: { maxAttempts: 1 } },
+  legacyDevProcessCwdBehaviour: false,
+  build: {
+    external: ["sharp"],
+    extensions: [additionalFiles({ files: ["./public/samples/*.jpg"] })],
+  },
+});
diff --git a/packages/convex/example/trigger/artifacts.ts b/packages/convex/example/trigger/artifacts.ts
new file mode 100644
index 00000000000..2adfdf2b348
--- /dev/null
+++ b/packages/convex/example/trigger/artifacts.ts
@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { jobWorkerToken } from "../shared/workerAuth";
+
+export const workerSchema = z.object({
+  serviceUrl: z.string().url(),
+  jobId: z.string().min(1),
+});
+export type Worker = z.infer<typeof workerSchema>;
+export type Slot = "prepared" | "edited" | "hero" | "card" | "square";
+const TYPES = {
+  prepared: "image/jpeg",
+  edited: "image/png",
+  hero: "image/avif",
+  card: "image/avif",
+  square: "image/avif",
+};
+function address(worker: Worker, slot: Slot) {
+  return `${worker.serviceUrl}/api/artifacts?jobId=${encodeURIComponent(worker.jobId)}&slot=${slot}`;
+}
+export async function readArtifact(worker: Worker, slot: Slot) {
+  const response = await fetch(address(worker, slot), {
+    headers: {
+      Authorization: `Bearer ${await jobWorkerToken(process.env.DEMO_ARTIFACT_SECRET, worker.jobId)}`,
+    },
+    signal: AbortSignal.timeout(20_000),
+  });
+  if (!response.ok) throw new Error(`Temporary image could not be read: HTTP ${response.status}`);
+  return new Uint8Array(await response.arrayBuffer());
+}
+export async function saveArtifact(worker: Worker, slot: Slot, data: Uint8Array) {
+  const response = await fetch(address(worker, slot), {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${await jobWorkerToken(process.env.DEMO_ARTIFACT_SECRET, worker.jobId)}`,
+      "Content-Type": TYPES[slot],
+    },
+    body: new Uint8Array(data),
+    signal: AbortSignal.timeout(20_000),
+  });
+  if (!response.ok) throw new Error(`Temporary image could not be saved: HTTP ${response.status}`);
+}
diff --git a/packages/convex/example/trigger/model.test.ts b/packages/convex/example/trigger/model.test.ts
new file mode 100644
index 00000000000..261a6dcb40e
--- /dev/null
+++ b/packages/convex/example/trigger/model.test.ts
@@ -0,0 +1,46 @@
+import { afterEach, expect, test, vi } from "vitest";
+import sharp from "sharp";
+
+const { generateImage, image } = vi.hoisted(() => ({
+  generateImage: vi.fn(),
+  image: vi.fn(() => "test-image-model"),
+}));
+vi.mock("ai", () => ({ generateImage, createGateway: () => ({ image }) }));
+import { editWithModel } from "./model";
+import { MODEL_ID } from "../shared/catalog";
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.clearAllMocks();
+});
+
+test("one image request has no paid retries and returns a bounded PNG", async () => {
+  vi.stubEnv("AI_GATEWAY_API_KEY", "test-only");
+  const source = await sharp({
+    create: { width: 1200, height: 800, channels: 3, background: "red" },
+  })
+    .png()
+    .toBuffer();
+  generateImage.mockResolvedValue({ images: [{}], image: { uint8Array: source } });
+  const output = await editWithModel(source, "Make it blue");
+  const decoded = await sharp(output).metadata();
+  expect(decoded.width).toBeLessThanOrEqual(1024);
+  expect(decoded.height).toBeLessThanOrEqual(1024);
+  expect(decoded.format).toBe("png");
+  expect(image).toHaveBeenCalledWith(MODEL_ID);
+  expect(generateImage).toHaveBeenCalledTimes(1);
+  expect(generateImage.mock.calls[0]![0]).toMatchObject({
+    n: 1,
+    maxImagesPerCall: 1,
+    maxRetries: 0,
+  });
+});
+
+test("provider failures do not leak request contents or cause another model call", async () => {
+  vi.stubEnv("AI_GATEWAY_API_KEY", "test-only");
+  generateImage.mockRejectedValue(new Error("private-prompt-and-image-bytes"));
+  await expect(editWithModel(new Uint8Array([1]), "private prompt")).rejects.toThrow(
+    "No automatic paid retry"
+  );
+  expect(generateImage).toHaveBeenCalledTimes(1);
+});
diff --git a/packages/convex/example/trigger/model.ts b/packages/convex/example/trigger/model.ts
new file mode 100644
index 00000000000..4b93ebbb51b
--- /dev/null
+++ b/packages/convex/example/trigger/model.ts
@@ -0,0 +1,31 @@
+import { createGateway, generateImage } from "ai";
+import sharp from "sharp";
+import { MODEL_ID } from "../shared/catalog";
+
+export async function editWithModel(input: Uint8Array, prompt: string) {
+  const apiKey = process.env.AI_GATEWAY_API_KEY;
+  if (!apiKey) throw new Error("AI_GATEWAY_API_KEY is not configured on Trigger.");
+  try {
+    const gateway = createGateway({ apiKey });
+    const result = await generateImage({
+      model: gateway.image(MODEL_ID),
+      prompt: {
+        text: `Edit this photograph according to the following instruction. Return one edited image.\n\n${prompt}`,
+        images: [input],
+      },
+      n: 1,
+      maxImagesPerCall: 1,
+      maxRetries: 0,
+      abortSignal: AbortSignal.timeout(90_000),
+    });
+    if (result.images.length !== 1) throw new Error("Expected one image");
+    return await sharp(result.image.uint8Array, { limitInputPixels: 12_000_000 })
+      .rotate()
+      .resize({ width: 1024, height: 1024, fit: "inside", withoutEnlargement: true })
+      .png()
+      .toBuffer();
+  } catch {
+    // Provider errors can contain prompts and image bytes. Keep them out of task errors.
+    throw new Error("The image model request failed. No automatic paid retry was made.");
+  }
+}
diff --git a/packages/convex/example/trigger/process-image.ts b/packages/convex/example/trigger/process-image.ts
new file mode 100644
index 00000000000..9ae70aee6cf
--- /dev/null
+++ b/packages/convex/example/trigger/process-image.ts
@@ -0,0 +1,71 @@
+import { logger, metadata, schemaTask } from "@trigger.dev/sdk";
+import { z } from "zod";
+import { PROMPT_LIMIT, VARIANTS } from "../shared/catalog";
+import { workerSchema } from "./artifacts";
+import { prepareImage, editImage, exportImage, sampleSchema, presetSchema } from "./steps";
+
+async function report(
+  phase: "prepare" | "edit" | "finish" | "ready",
+  stage: string,
+  progress: number
+) {
+  metadata.set("phase", phase).set("stage", stage).set("progress", progress);
+  await metadata.flush().catch(() => logger.warn("Progress update unavailable"));
+}
+
+export const processImage = schemaTask({
+  id: "convex-edit-image",
+  schema: workerSchema.extend({
+    sample: sampleSchema,
+    preset: presetSchema,
+    prompt: z.string().trim().min(1).max(PROMPT_LIMIT),
+  }),
+  queue: { name: "convex-image-pipeline", concurrencyLimit: 1 },
+  machine: "small-1x",
+  maxDuration: 120,
+  retry: { maxAttempts: 1 },
+  run: async (payload) => {
+    if (!process.env.AI_GATEWAY_API_KEY)
+      throw new Error("Add AI_GATEWAY_API_KEY to the Trigger project before enabling image edits.");
+    const started = Date.now();
+    const worker = {
+      serviceUrl: payload.serviceUrl,
+      jobId: payload.jobId,
+    };
+    await report("prepare", "Preparing the photograph", 5);
+    const prepared = await prepareImage
+      .triggerAndWait(
+        { ...worker, sample: payload.sample },
+        {
+          idempotencyKey: `${payload.jobId}:prepare`,
+          ttl: "5m",
+        }
+      )
+      .unwrap();
+    await report("edit", "Editing with the Muse image model", 25);
+    await editImage
+      .triggerAndWait(
+        { ...worker, prompt: payload.prompt },
+        {
+          idempotencyKey: `${payload.jobId}:model`,
+          ttl: "5m",
+        }
+      )
+      .unwrap();
+    await report("finish", "Exporting three images in parallel", 65);
+    const batch = await exportImage.batchTriggerAndWait(
+      VARIANTS.map((variant) => ({
+        payload: { ...worker, preset: payload.preset, kind: variant.kind },
+        options: { idempotencyKey: `${payload.jobId}:export:${variant.kind}`, ttl: "5m" },
+      }))
+    );
+    const variants = batch.runs.map((run) => {
+      if (!run.ok)
+        throw new Error("An image export failed. The paid edit will not be retried automatically.");
+      return run.output;
+    });
+    for (const variant of VARIANTS) metadata.set(`${variant.kind}Ready`, true);
+    await report("ready", "Images ready", 100);
+    return { inputBytes: prepared.inputBytes, processingMs: Date.now() - started, variants };
+  },
+});
diff --git a/packages/convex/example/trigger/processor.test.ts b/packages/convex/example/trigger/processor.test.ts
new file mode 100644
index 00000000000..9149d5cc0fc
--- /dev/null
+++ b/packages/convex/example/trigger/processor.test.ts
@@ -0,0 +1,18 @@
+import { expect, test } from "vitest";
+import sharp from "sharp";
+import { createImageSet } from "./processor";
+import { VARIANTS } from "../shared/catalog";
+
+test("creates real cropped AVIF files at the requested dimensions", async () => {
+  const output = await createImageSet("coast", "balanced");
+  expect(output.variants).toHaveLength(3);
+  for (const [index, image] of output.variants.entries()) {
+    const decoded = await sharp(image.data).metadata();
+    expect(decoded.width).toBe(VARIANTS[index]!.width);
+    expect(decoded.height).toBe(VARIANTS[index]!.height);
+    expect(decoded.format).toBe("heif");
+    expect(image.bytes).toBe(image.data.byteLength);
+    expect(image.bytes).toBeGreaterThan(0);
+  }
+  expect(output.processingMs).toBeGreaterThan(0);
+}, 60_000);
diff --git a/packages/convex/example/trigger/processor.ts b/packages/convex/example/trigger/processor.ts
new file mode 100644
index 00000000000..766547c618a
--- /dev/null
+++ b/packages/convex/example/trigger/processor.ts
@@ -0,0 +1,51 @@
+import sharp from "sharp";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { AVIF_EFFORT, PRESETS, SAMPLES, VARIANTS } from "../shared/catalog";
+import type { SampleId, PresetId, VariantKind } from "../shared/types";
+
+sharp.concurrency(1);
+
+export async function encodeVariant(input: Uint8Array, preset: PresetId, kind: VariantKind) {
+  const settings = PRESETS.find((candidate) => candidate.id === preset);
+  const variant = VARIANTS.find((candidate) => candidate.kind === kind);
+  if (!settings || !variant) throw new Error("Unknown preset or output");
+  const data = await sharp(input, { limitInputPixels: 12_000_000 })
+    .rotate()
+    .resize(variant.width, variant.height, { fit: "cover" })
+    .avif({ quality: settings.quality, effort: AVIF_EFFORT })
+    .toBuffer();
+  return {
+    kind: variant.kind,
+    width: variant.width,
+    height: variant.height,
+    format: "avif" as const,
+    bytes: data.byteLength,
+    data,
+  };
+}
+
+export async function createImageSet(
+  sample: SampleId,
+  preset: PresetId,
+  report: (stage: string, progress: number) => Promise<void> = async () => {}
+) {
+  const source = SAMPLES.find((candidate) => candidate.id === sample);
+  const settings = PRESETS.find((candidate) => candidate.id === preset);
+  if (!source || !settings) throw new Error("Unknown sample or preset");
+  const input = await readFile(resolve(process.cwd(), "public", source.file.slice(1)));
+  const start = performance.now();
+  const variants = [];
+  for (const [index, variant] of VARIANTS.entries()) {
+    await report(
+      `Trigger: cropping and compressing ${variant.width} × ${variant.height}`,
+      10 + index * 25
+    );
+    variants.push(await encodeVariant(input, preset, variant.kind));
+  }
+  return {
+    variants,
+    inputBytes: input.byteLength,
+    processingMs: Math.round(performance.now() - start),
+  };
+}
diff --git a/packages/convex/example/trigger/steps.ts b/packages/convex/example/trigger/steps.ts
new file mode 100644
index 00000000000..9306959cd8a
--- /dev/null
+++ b/packages/convex/example/trigger/steps.ts
@@ -0,0 +1,65 @@
+import { logger, metadata, schemaTask } from "@trigger.dev/sdk";
+import { z } from "zod";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import sharp from "sharp";
+import { SAMPLES, PRESETS, PROMPT_LIMIT } from "../shared/catalog";
+import { workerSchema, readArtifact, saveArtifact } from "./artifacts";
+import { editWithModel } from "./model";
+import { encodeVariant } from "./processor";
+
+sharp.concurrency(1);
+export const sampleSchema = z.enum(SAMPLES.map((sample) => sample.id));
+export const presetSchema = z.enum(PRESETS.map((preset) => preset.id));
+
+export const prepareImage = schemaTask({
+  id: "convex-image-prepare",
+  schema: workerSchema.extend({ sample: sampleSchema }),
+  queue: { name: "convex-image-prepare", concurrencyLimit: 1 },
+  machine: "small-1x",
+  maxDuration: 60,
+  retry: { maxAttempts: 1 },
+  run: async (payload) => {
+    const source = SAMPLES.find((sample) => sample.id === payload.sample)!;
+    const bytes = await readFile(resolve(process.cwd(), "public", source.file.slice(1)));
+    const prepared = await sharp(bytes, { limitInputPixels: 12_000_000 })
+      .rotate()
+      .resize({ width: 1024, height: 1024, fit: "inside", withoutEnlargement: true })
+      .jpeg({ quality: 85 })
+      .toBuffer();
+    await saveArtifact(payload, "prepared", prepared);
+    return { inputBytes: bytes.byteLength };
+  },
+});
+
+export const editImage = schemaTask({
+  id: "convex-image-model-edit",
+  schema: workerSchema.extend({ prompt: z.string().trim().min(1).max(PROMPT_LIMIT) }),
+  queue: { name: "convex-image-model", concurrencyLimit: 1 },
+  machine: "small-1x",
+  maxDuration: 120,
+  retry: { maxAttempts: 1 },
+  run: async (payload) => {
+    const input = await readArtifact(payload, "prepared");
+    const edited = await editWithModel(input, payload.prompt);
+    await saveArtifact(payload, "edited", edited);
+    return { edited: true };
+  },
+});
+
+export const exportImage = schemaTask({
+  id: "convex-image-export",
+  schema: workerSchema.extend({ preset: presetSchema, kind: z.enum(["hero", "card", "square"]) }),
+  queue: { name: "convex-image-exports", concurrencyLimit: 3 },
+  machine: "small-1x",
+  maxDuration: 90,
+  retry: { maxAttempts: 1 },
+  run: async (payload) => {
+    const input = await readArtifact(payload, "edited");
+    const { data, ...result } = await encodeVariant(input, payload.preset, payload.kind);
+    await saveArtifact(payload, payload.kind, data);
+    metadata.parent.set(`${payload.kind}Ready`, true);
+    await metadata.flush().catch(() => logger.warn("Parent progress update unavailable"));
+    return result;
+  },
+});
diff --git a/packages/convex/example/tsconfig.json b/packages/convex/example/tsconfig.json
new file mode 100644
index 00000000000..3af9b61b672
--- /dev/null
+++ b/packages/convex/example/tsconfig.json
@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["vite/client", "node"],
+    "allowImportingTsExtensions": true
+  },
+  "include": ["src", "convex", "shared", "trigger", "trigger.config.ts"],
+  "exclude": ["node_modules"]
+}
diff --git a/packages/convex/example/vitest.config.ts b/packages/convex/example/vitest.config.ts
new file mode 100644
index 00000000000..82ac2676d7c
--- /dev/null
+++ b/packages/convex/example/vitest.config.ts
@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["{src,convex,trigger,shared}/**/*.test.{ts,tsx}"],
+  },
+});
diff --git a/packages/convex/package.json b/packages/convex/package.json
index b8e6dc89e25..b5f1cd9ba75 100644
--- a/packages/convex/package.json
+++ b/packages/convex/package.json
@@ -15,7 +15,9 @@
   "files": [
     "dist",
     "src/component",
-    "!src/component/**/*.test.ts"
+    "skills/*/SKILL.md",
+    "!src/component/**/*.test.ts",
+    "!example/**"
   ],
   "exports": {
     ".": {
diff --git a/packages/convex/skills/trigger-convex/SKILL.md b/packages/convex/skills/trigger-convex/SKILL.md
new file mode 100644
index 00000000000..4095258c0a8
--- /dev/null
+++ b/packages/convex/skills/trigger-convex/SKILL.md
@@ -0,0 +1,264 @@
+---
+name: trigger-convex
+description: >
+  Integrates Trigger.dev background tasks with Convex using @trigger.dev/convex.
+  Use when triggering work transactionally from a Convex mutation, showing reactive
+  run state, handling completion callbacks, combining Trigger Realtime with Convex,
+  restoring jobs after reload, or repairing paused synchronization. Covers ownership,
+  idempotency, scoped browser tokens, and credential-safe task payloads. Not for
+  Convex-only applications or Trigger.dev applications without Convex.
+license: Apache-2.0
+---
+
+# Trigger.dev with Convex
+
+## Check the installed contract first
+
+Locate `@trigger.dev/convex/package.json`, then read the adjacent `README.md` and
+`dist/client/index.d.ts`. In a non-hoisted installation, resolve the package with:
+
+```bash
+node -p "require.resolve('@trigger.dev/convex/package.json')"
+```
+
+Use the installed declarations as authority. Older releases do not expose
+`refresh()`. If it is absent, use durable polling or upgrade to a compatible
+release; do not invent a replacement method or accept browser-supplied run state.
+Keep the application's Convex version compatible with the package's peer dependency.
+Do not pin an arbitrary preview URL unless the user explicitly needs that preview.
+
+Choose the relevant flow:
+
+| Request | Approach |
+| --- | --- |
+| Enqueue a report, render, import, or AI task | Call `trigger.trigger` inside the application's authenticated mutation. |
+| Display durable status/results | Authorize the application's job, then call `trigger.getRun` from a query. |
+| Update application records on completion | Register a short internal mutation using `vRun`. |
+| Display responsive browser progress | Subscribe to Trigger Realtime; request an authorized Convex refresh on terminal events. |
+| Restore an edit after reload or leaving the page | Persist the selected application job/request ID and inputs; recover owned work from Convex. |
+| Recover paused status synchronization | Repair credentials/callback failures, then call authorized `resume`; do not enqueue another task. |
+
+## Install and configure
+
+Install `@trigger.dev/convex` and `convex`. Deploy the actual task separately with
+Trigger.dev; the component does not deploy task code. Keep `TRIGGER_SECRET_KEY`
+only in the Convex server environment, for the intended Trigger environment.
+
+```typescript
+// convex/convex.config.ts
+import { defineApp } from "convex/server";
+import triggerComponent from "@trigger.dev/convex/convex.config.js";
+
+const app = defineApp();
+app.use(triggerComponent);
+export default app;
+```
+
+Run `npx convex dev` to generate the application's component references.
+
+```typescript
+// convex/trigger.ts
+import { Trigger } from "@trigger.dev/convex";
+import { components } from "./_generated/api";
+
+export const trigger: Trigger = new Trigger(components.trigger);
+```
+
+Constructor options are `secretKey`, `baseUrl`, and `onComplete`. The default API
+is `https://api.trigger.dev`; `TRIGGER_API_URL` is not automatically read by the
+component. Set `baseUrl` explicitly for a different API host. HTTP is allowed only
+for localhost development. Keep server keys out of `VITE_`/`NEXT_PUBLIC_` variables.
+
+## Enqueue atomically and authorize reads
+
+Maintain an application-owned job table. The component has no user/tenant model.
+This example assumes an existing deployed `process-text` task that accepts `{ text }`.
+Validate business limits and authorize any referenced documents/files before enqueueing.
+
+```typescript
+// convex/schema.ts
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  jobs: defineTable({
+    owner: v.string(),
+    requestId: v.string(),
+    text: v.string(),
+    componentRunId: v.optional(v.string()),
+  }).index("by_owner_request", ["owner", "requestId"])
+    .index("by_componentRunId", ["componentRunId"]),
+});
+```
+
+```typescript
+// convex/jobs.ts
+import { vRun } from "@trigger.dev/convex";
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server";
+import { trigger } from "./trigger";
+
+export const request = mutation({
+  args: { text: v.string(), requestId: v.string() },
+  returns: v.id("jobs"),
+  handler: async (ctx, args) => {
+    const user = await ctx.auth.getUserIdentity();
+    if (!user) throw new Error("Unauthorized");
+    const owner = user.tokenIdentifier;
+    const existing = await ctx.db.query("jobs")
+      .withIndex("by_owner_request", q => q.eq("owner", owner).eq("requestId", args.requestId))
+      .unique();
+    if (existing) {
+      if (existing.text !== args.text) throw new Error("Request ID reused for different input");
+      return existing._id;
+    }
+    const jobId = await ctx.db.insert("jobs", { owner, ...args });
+    const componentRunId = await trigger.trigger(ctx, "process-text", { text: args.text }, {
+      idempotencyKey: `process-text:${owner}:${args.requestId}`,
+    });
+    await ctx.db.patch(jobId, { componentRunId });
+    return jobId;
+  },
+});
+
+export const status = query({
+  args: { jobId: v.id("jobs") },
+  returns: v.union(vRun, v.null()),
+  handler: async (ctx, { jobId }) => {
+    const user = await ctx.auth.getUserIdentity();
+    const job = await ctx.db.get(jobId);
+    if (!user || !job || job.owner !== user.tokenIdentifier) return null;
+    return job.componentRunId ? trigger.getRun(ctx, job.componentRunId) : null;
+  },
+});
+```
+
+Preserve the same request ID when retrying an unconfirmed submission. Namespace
+component idempotency keys by tenant/owner, task, and logical request. They dedupe
+across the entire component instance, not just a task, and do not compare payloads.
+An application mutation rollback also rolls back the component enqueue/scheduling.
+Do not replace this with a direct SDK trigger from an action if atomicity is required.
+Use type-only task imports when adding task payload inference; do not bundle task
+implementations, Sharp, or provider clients into the Convex mutation runtime.
+
+There are three distinct identifiers:
+
+- Application `jobId`: accept this from the browser and enforce ownership.
+- Component `run.id`: returned by `trigger.trigger`; pass it to `getRun`, `refresh`, and `resume`.
+- Remote `run.runId`: available after submission; subscribe to this with Trigger Realtime.
+
+For React, use an application query such as `useQuery(api.jobs.status, { jobId })`.
+Only persist/display results verified by Convex. `getRun` omits stored credentials
+and request payloads, but its output, errors, and metadata can still contain private data.
+Do not expose `listRuns` as a global client-visible feed; use indexed owned jobs and
+bounded lookups instead.
+
+## Apply completion to application state
+
+When an application record must change on completion, extend its schema with the
+task-specific status/result fields, then add an internal mutation with
+`args: { run: vRun }` and `returns: v.null()`. Find its job through the
+`by_componentRunId` index using `run.id`, validate the task's output, and update it.
+Configure the client with `onComplete: internal.jobs.complete`; keep the explicit
+`Trigger` type annotation to avoid circular inference through the generated API.
+
+Keep the callback short and transactional. It runs with the component's terminal
+update; throwing rolls both back and schedules a retry. Do network I/O in separate
+actions, not in the callback mutation. A callback is optional for reactive reads.
+Treat omitted output and expiring output URLs explicitly rather than assuming every
+completed run has an inline result.
+
+## Combine Realtime progress with authoritative Convex state
+
+Install `@trigger.dev/react-hooks` in a React frontend and `@trigger.dev/sdk` in the
+server that mints tokens. These are separate from the component-only polling setup.
+
+Only use the following wrapper if the installed component exposes `refresh()`:
+
+```typescript
+// Add to convex/jobs.ts
+export const refresh = mutation({
+  args: { jobId: v.id("jobs") },
+  returns: v.null(),
+  handler: async (ctx, { jobId }) => {
+    const user = await ctx.auth.getUserIdentity();
+    const job = await ctx.db.get(jobId);
+    if (!user || !job || job.owner !== user.tokenIdentifier) throw new Error("Unauthorized");
+    if (job.componentRunId) await trigger.refresh(ctx, job.componentRunId);
+    return null;
+  },
+});
+```
+
+1. Authenticate a server-side token request and verify the application job's owner.
+   Derive its remote run ID on the server; never grant access to a caller-chosen run.
+2. Mint a short-lived `auth.createPublicToken` scoped to `read: { runs: [runId] }`.
+   Use an SDK-capable server runtime, such as a Convex Node action, and scoped
+   `auth.withAuth` configuration rather than mutating shared global credentials.
+   The SDK spells its API host option `baseURL`, unlike the component's `baseUrl`.
+   Match the key/host environment, bound expiry to the application's access lifetime,
+   and return only the token, remote ID, expiry, and required public connection URL.
+3. Subscribe with `useRealtimeRun` or `runs.subscribeToRun` only after the remote ID
+   exists. Limit the browser to the selected owned run, renew credentials through
+   the authorized endpoint, and clean up on job/session changes. Reject late token
+   responses and metadata for a previous selection.
+4. On completion, including an already-terminal snapshot after reconnecting, call
+   the owned `refresh` mutation. Include failed, canceled, expired, and timed-out
+   runs. Do not refresh on every metadata update or retry a failed effect in a loop.
+5. Observe the Convex query for persisted status/results. A refresh returns `null`
+   after scheduling; it does not wait for completion or return a new run snapshot.
+   Keep scheduled polling/watchdog recovery enabled when the browser goes away.
+
+Refresh hints are coalesced per run, with refresh-driven checks at least five seconds
+after the previous status check. An in-flight hint queues a follow-up without
+invalidating that observation. Pending submissions, paused synchronization, and
+completed records are no-ops; refresh neither submits work nor resumes paused work.
+
+**Token safety:** a run-read token also authorizes REST reads of its payload.
+Realtime `skipColumns: ["payload", "output"]` reduces streamed data; it does not
+restrict REST access. Remove worker keys, upload capabilities, and other credentials
+from token-readable payloads, outputs, metadata, and errors before issuing browser
+tokens. Do not mint tokens for legacy runs that still contain credentials; deploying
+new code or changing column filters does not rewrite old remote payloads. Derive worker authorization server-side or use server-only signing instead.
+Authorize private artifact delivery separately; a public run token is not a file
+access policy. Keep browser run tokens in memory and never log credentials.
+
+Persist the selected application job ID, draft inputs, and unconfirmed request ID
+before sending a request. Restore owned active jobs from Convex after reload;
+otherwise restore only explicit selections, not any old result with matching defaults.
+Use actual task metadata for phase progress, explain disabled submission states,
+and do not publish results solely because Realtime reports completion.
+
+## Troubleshoot without duplicating work
+
+| Symptom | Fix |
+| --- | --- |
+| Duplicate jobs after a lost response | Reuse the logical request ID and query the owned job before enqueueing again. |
+| Wrong run or a null remote ID | Distinguish application/component/remote IDs; wait for confirmed submission before subscribing. |
+| Browser refresh resolves but results lag | Observe Convex; refresh is asynchronous, coalesced, and rate-limited. |
+| Component/validator types are incompatible | Check for duplicate Convex installations or peer contexts; align component/consumer dependencies rather than hiding mismatches with casts. |
+| `refresh` is missing | Check installed declarations; upgrade deliberately or retain polling, not a fabricated API. |
+| `syncStatus === "paused"` | Inspect `syncError`, repair credentials/callbacks, then authorize `resume(ctx, componentId)`. |
+| Old work disappears after reload | Persist selection/inputs/request ID; recover owned active work instead of resetting to defaults. |
+| Token leaks worker access | Remove credentials from all readable run fields; column filtering cannot repair this. |
+| Data from another tenant appears | Authorize every query/mutation/token/artifact request; never trust arbitrary IDs or shared tags. |
+| Successful remote work never commits | Check callback errors and output validation; retries roll back application completion too. |
+| Large or missing results | Use storage references; inspect `outputOmitted`/`outputPresignedUrl` and refresh expired URLs server-side. |
+| Run exists in a different environment | Align API host/key; resume does not migrate remote runs between environments. |
+
+Polling normally backs off from about 15 to 60 seconds. Account for Convex executions
+and Trigger API requests at scale; use Realtime for responsive UI, not rapid polling.
+Payload plus trigger options must fit within 256 KiB, as must each inline output,
+error, and metadata value. Component records are retained; paused requests retain
+credentials and payloads for recovery, so plan application retention separately.
+Remote submission uses a 24-hour idempotency TTL, but automatic submission retries
+stop within one hour. After that window, reconcile remotely before creating new work;
+do not claim unlimited exactly-once execution or blindly retry expensive tasks.
+
+## Verify the integration
+
+Check mutation rollback, duplicate request IDs, cross-owner denial, callback failures,
+and reconnecting to an already-terminal run. Verify that leaving the page does not
+prevent durable completion. If tokens are issued, test cross-run denial and inspect
+the full REST-readable payload for credentials. Add focused integration coverage;
+do not spend on real provider calls or deploy without the user's authorization.
diff --git a/packages/convex/skills/trigger-convex/SOURCES.md b/packages/convex/skills/trigger-convex/SOURCES.md
new file mode 100644
index 00000000000..5de6050043d
--- /dev/null
+++ b/packages/convex/skills/trigger-convex/SOURCES.md
@@ -0,0 +1,43 @@
+# Sources and decisions
+
+Reviewed 2026-10-30. Repository-relative paths refer to the Trigger.dev repository.
+
+## Source inventory
+
+| Source | Trust / confidence | Contribution |
+| --- | --- | --- |
+| [Agent Skills specification](https://agentskills.io/specification) | Official / high | Standard frontmatter, directory naming, portable Markdown, self-contained manual copy. |
+| packages/convex/README.md; src/client/index.ts; src/component/shared.ts | Implementation / high | Configuration, IDs, API methods, callbacks, limits, idempotency, paused recovery. |
+| [Merged refresh PR #1410](https://github.com/triggerdotdev/chonk/pull/1410) and its component tests | Implementation and regression tests / high | Five-second coalescing, in-flight follow-up, asynchronous hint semantics, lifecycle no-ops. |
+| packages/convex/example/convex/realtime.ts; jobs.ts; src/RealtimeJobPanel.tsx; src/editorState.ts | Working integration / high | Owner checks, scoped auth, token expiry, REST-safe worker credentials, selection/request restoration. |
+| packages/cli-v3/skills/trigger-realtime-and-frontend/SKILL.md; packages/trigger-sdk/skills/trigger-realtime-and-frontend/SKILL.md | Existing repository convention / high | Installed version as authority; distinction between installer pointers and full guides. No installer pointer is added here. |
+| packages/convex/README.md; package.json; tsconfig.json | Repository configuration / high | Manual discovery, publication allowlist, library/example isolation. |
+| Example reload and cross-session integration tests | Regression evidence / high | No implicit selection by matching defaults, request ID recovery, owned active jobs. |
+
+Use source contracts rather than copying a generic component-template release process. The code examples are adapted to an owned text-processing job, not a copy of demo-specific capabilities, limits, or project settings.
+
+## Synthesis and precision
+
+- Adopted integration-documentation / inline-guidance: one coherent contract fits a single skill. Runtime references or scripts would add navigation without a separate lookup need.
+- Added with reason: no component-specific skill existed; widening the generic Realtime skill would mix Convex transaction/recovery rules into unrelated frontend work.
+- Kept provenance and maintenance separate from runtime. Publish only the self-contained guide.
+- Reused standard CLI skill documentation conventions but deliberately deferred all CLI registration, per user request.
+- Preferred owned application IDs over browser-supplied remote IDs; tenant/task/request namespacing over unscoped idempotency.
+- Added explicit version gating because older installed components lack refresh.
+- No provider-specific tools, session variables, or machine-specific paths.
+- Retrieval stopped after implementation, merged refresh tests, real example security/recovery paths, repository distribution, and format specification covered the contract. More generic SDK documentation would mostly repeat existing guidance.
+
+## Coverage
+
+| Dimension | Coverage |
+| --- | --- |
+| API / configuration | Installed declaration check, setup, trigger/get/list/refresh/resume, host/key environment. |
+| Downstream uses | Transactional work, reactive reads, callbacks, hybrid progress, reload recovery, synchronization repair. |
+| Failures / workarounds | Twelve symptom/fix cases plus callback, output, idempotency and secret-handling constraints. |
+| Version variance | Missing refresh, explicit upgrades, no arbitrary preview pin, manual copy refresh. |
+| Security | Per-owner wrappers, server-derived run scope, REST payload audit, separate artifact authorization. |
+| Portability / packaging | Standard frontmatter, manual copy, installed-package resolution, npm allowlist without example assets. |
+
+## Gaps
+
+Structural and TypeScript checks are not a model behavior evaluation. The skill intentionally does not choose business-specific auth, file retention, provider spending policy, or analytics infrastructure. It requires installed declarations for version-specific details.
diff --git a/packages/convex/skills/trigger-convex/SPEC.md b/packages/convex/skills/trigger-convex/SPEC.md
new file mode 100644
index 00000000000..4f4d430284e
--- /dev/null
+++ b/packages/convex/skills/trigger-convex/SPEC.md
@@ -0,0 +1,41 @@
+# trigger-convex maintenance contract
+
+## Intent and scope
+
+Teach coding agents to integrate Trigger.dev with Convex using the installed component contract. Cover atomic submission, owned reactive reads, callbacks, hybrid Realtime, reload recovery, and paused synchronization.
+
+Exclude Convex-only development, generic Trigger task authoring, directory submission, and autonomous deployment/provider spending. The skill is portable Markdown with standard Agent Skills frontmatter.
+
+## Layout and distribution
+
+- Class: integration-documentation. Shape: inline-guidance, with no scripts, runtime references, or provider-specific mechanics.
+- Keep runtime instructions in SKILL.md; keep evidence and decisions in SOURCES.md.
+- Publish only SKILL.md. These maintenance files remain repository-only.
+- Do not add a CLI skill pointer or installer registration. Installation is manual, documented in the package README.
+- The installed README and declarations take precedence over copied instructions. Gate refresh on API availability.
+
+## Trigger checks
+
+Should trigger:
+- Trigger a report transactionally from a Convex mutation.
+- Show a Convex job using Trigger Realtime and refresh persisted completion.
+- Restore a background image edit after refreshing the page.
+- Repair paused synchronization without submitting duplicate paid work.
+
+Should not trigger:
+- Build a Convex-only chat app.
+- Write a standalone Trigger task without Convex.
+- Submit a component to the directory.
+- Configure unrelated analytics or deploy infrastructure.
+
+## Validation and acceptance
+
+Validate standard frontmatter, portable paths, and the manually copied standalone file. Typecheck the code examples against real Convex generated builder/model types and compatible installed component declarations. Run package build/tests, formatting/lint, and inspect an actual package tarball: it must contain the skill and still exclude the example and maintenance files.
+
+Review for eight or more concrete failure/repair cases and the six downstream flows identified in SKILL.md. In particular, preserve request idempotency, exact-run token ownership, REST-readable payload safety, asynchronous refresh semantics, and polling recovery.
+
+No LLM behavior benchmark is required for this change. Use the trigger queries above for future skill evaluation. Do not infer behavioral effectiveness from structural validation alone.
+
+## Maintenance
+
+Update the skill when the public API, lifecycle/limits, token semantics, or authentication boundaries change. Recheck SOURCES.md and the installed-package examples. Keep private customer data, credentials, and operator identifiers out of evidence. Re-copy the manual skill after upgrading the component.
diff --git a/packages/convex/vitest.config.ts b/packages/convex/vitest.config.ts
new file mode 100644
index 00000000000..ae847ff6d9c
--- /dev/null
+++ b/packages/convex/vitest.config.ts
@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/**/*.test.ts"],
+  },
+});