@hyperframes/studio 0.7.106 → 0.7.107

package/src/components/feedback/feedbackTrigger.ts

@@ -0,0 +1,269 @@
+// ---------------------------------------------------------------------------
+// Single owner of "should Studio ask for feedback right now, and about what".
+//
+// The prompt used to fire on a session counter (every 10th tab). That collected
+// 5 responses in three months, because it asked at an arbitrary moment with no
+// subject. It now fires on a render outcome — the moment the user has just
+// formed an opinion — which is the same moment the CLI asks.
+//
+// Producers call `requestStudioFeedback`; the card subscribes. Eligibility
+// lives here and nowhere else, so no caller has to know the cooldown rules.
+// ---------------------------------------------------------------------------
+
+import { browserTelemetryAllowed } from "../../telemetry/policy";
+
+export type FeedbackReason = "render_complete" | "render_failed" | "crash";
+
+/**
+ * Everything except a finished render is a problem report: no 0-10 score (you
+ * cannot rate an export you never got, and a fabricated rating poisons the
+ * average) and the card wears its error styling.
+ */
+export function isProblemReason(reason: FeedbackReason): boolean {
+  return reason !== "render_complete";
+}
+
+/**
+ * A one-tap answer. `label` has to stand on its own — a chip that only makes
+ * sense once you hover it is a badly named chip, and most people never hover.
+ * `hint` carries the nuance a two-word label cannot, for the people who do.
+ */
+export interface FollowUpPreset {
+  label: string;
+  hint: string;
+}
+
+/**
+ * The follow-up asked after a score. One question per person, rotated across
+ * people: a corner card that asks three things gets answered by nobody, but the
+ * same card asking one thing of every third user covers the same ground.
+ */
+export interface FollowUpQuestion {
+  /** Sent with the response, so answers stay separable instead of collapsing
+   *  into one undifferentiated comment field. */
+  id: string;
+  prompt: string;
+  placeholder: string;
+  /**
+   * Typing into a corner card is a cost most people decline, so the common
+   * answers are buttons and the field is the escape hatch. Keep these mutually
+   * distinct: two chips a user could reasonably read the same way collect a
+   * number that means nothing.
+   */
+  presets: readonly FollowUpPreset[];
+}
+
+// The options below are not invented, and none of them is a brand.
+//
+// `fix` mirrors the themes that actually dominate written feedback: audio and
+// encoding first by a wide margin, then media and fonts, then export-versus-
+// preview mismatches, then render time. `workaround` mirrors the steps people
+// report finishing in other tools. `remove` offers the surfaces that see the
+// least real use, so the question contains genuine deletion candidates instead
+// of a list nobody would pick from. `detractor` mirrors the failures Studio
+// actually emits.
+//
+// Seven is the ceiling, not a target: past that the chips stop being scannable
+// in a corner card and start being a form. Re-derive all of these when the
+// shape of the feedback changes, because a stale option list quietly steers
+// every answer it collects.
+const FOLLOW_UPS: readonly FollowUpQuestion[] = [
+  {
+    id: "remove",
+    prompt: "What would you cut from Studio?",
+    placeholder: "The part you never use",
+    presets: [
+      { label: "Layers panel", hint: "The layer tree on the right" },
+      { label: "Variables panel", hint: "Composition variables on the right" },
+      { label: "Blocks browser", hint: "The block library in the sidebar" },
+      { label: "Storyboard mode", hint: "The storyboard view next to Preview" },
+      { label: "Caption editing", hint: "Editing caption words and presets in Studio" },
+      { label: "Render history", hint: "The list of past exports" },
+      { label: "Nothing", hint: "It all earns its place" },
+    ],
+  },
+  {
+    // Replaces an earlier "which editor gets this right?". Brand names are a
+    // popularity vote, not an instruction: "CapCut" does not say what to build.
+    // What someone had to leave HyperFrames to do names the missing feature
+    // exactly, and written feedback is full of these workarounds already.
+    //
+    // Every option here is a step Studio genuinely cannot do today. Offering
+    // one it CAN do (trimming, voiceover, ducking, compositing, grading) would
+    // collect taps that mean "I could not find it", and there is no way to tell
+    // those apart from "it does not exist" afterwards. Check before adding.
+    id: "workaround",
+    prompt: "What did you have to do outside Studio?",
+    placeholder: "The step you finished somewhere else",
+    presets: [
+      { label: "Fix the exported file", hint: "Remuxing or re-encoding the output by hand" },
+      { label: "Convert source media", hint: "Re-encoding footage before it would import cleanly" },
+      { label: "Match loudness", hint: "Normalising levels across the finished audio" },
+      { label: "Make images or graphics", hint: "Creating visual assets in another tool" },
+      { label: "Record footage", hint: "Capturing screen or camera video" },
+      { label: "Nothing, it was all here", hint: "No outside tools needed" },
+    ],
+  },
+  {
+    id: "fix",
+    prompt: "What should we fix first?",
+    placeholder: "The thing that slowed you down",
+    presets: [
+      { label: "Audio mixing", hint: "Levels, ducking or the balance in the exported mix" },
+      { label: "Export encoding", hint: "The render fails, or the finished file is wrong" },
+      { label: "Export matches preview", hint: "The exported video differs from the preview" },
+      { label: "Media and fonts", hint: "Adding video, images or fonts to a project" },
+      { label: "Render speed", hint: "Exports take too long to finish" },
+      { label: "Re-rendering everything", hint: "A small change means rendering the whole thing" },
+      {
+        label: "Checks and warnings",
+        hint: "Lint flags things that are fine, or misses real ones",
+      },
+    ],
+  },
+];
+
+/** Detractors are not asked a rotated question; the complaint is the answer. */
+const DETRACTOR_FOLLOW_UP: FollowUpQuestion = {
+  id: "detractor",
+  prompt: "What went wrong?",
+  placeholder: "The thing that made that a low score",
+  presets: [
+    { label: "Export failed", hint: "The render did not finish" },
+    { label: "Output looked wrong", hint: "It rendered, but not the way I built it" },
+    { label: "Crashed or froze", hint: "The editor stopped responding" },
+    { label: "Lost my edits", hint: "Changes did not save, or came back changed" },
+    { label: "Too slow", hint: "Waiting on renders, or the editor itself lagging" },
+    { label: "Could not figure it out", hint: "Could not find or understand something" },
+  ],
+};
+
+const DETRACTOR_MAX_RATING = 6;
+
+export function followUpFor(rating: number): FollowUpQuestion {
+  if (rating <= DETRACTOR_MAX_RATING) return DETRACTOR_FOLLOW_UP;
+  // Rotation only has to spread across users, not be unguessable, so any
+  // per-prompt jitter works. Studio's determinism rules cover rendered
+  // compositions, not the editor chrome.
+  return FOLLOW_UPS[Math.floor(Math.random() * FOLLOW_UPS.length)];
+}
+
+/**
+ * Facts about the moment being reported on, sent with the response so a
+ * complaint arrives with the conditions that produced it instead of needing a
+ * round trip to ask. Producers fill this; the trigger never inspects it.
+ *
+ * Names and enums only, no free text: this rides to the same place the comment
+ * does, and the user consented to a comment, not to their project's contents.
+ */
+export interface FeedbackContext {
+  [key: string]: string | number | boolean | undefined;
+}
+
+export interface FeedbackRequest {
+  reason: FeedbackReason;
+  /** Render job the prompt is about — joins the response to the render event. */
+  renderId?: string;
+  /** Failure text shown to the user, sent verbatim so reports are actionable. */
+  detail?: string;
+  /** Reproduction context: settings, counts, outcomes. See FeedbackContext. */
+  context?: FeedbackContext;
+}
+
+const STORAGE_KEYS = {
+  /** Epoch ms of the last prompt the user dismissed or ignored. */
+  dismissedAt: "hyperframes-studio:feedbackDismissedAt",
+  /** Epoch ms of the last prompt the user actually answered. */
+  answeredAt: "hyperframes-studio:feedbackAnsweredAt",
+} as const;
+
+/** One prompt per tab, so a batch of renders can't turn into a batch of asks. */
+const SESSION_ASKED_KEY = "hyperframes-studio:feedbackAskedThisSession";
+
+const DAY_MS = 86_400_000;
+const ANSWERED_COOLDOWN_MS = 30 * DAY_MS;
+const DISMISSED_COOLDOWN_MS = 7 * DAY_MS;
+
+type Listener = (request: FeedbackRequest) => void;
+
+let listener: Listener | null = null;
+
+function isDisabled(): boolean {
+  try {
+    return import.meta.env.VITE_HYPERFRAMES_NO_FEEDBACK === "1";
+  } catch {
+    return false;
+  }
+}
+
+function readTimestamp(key: string): number {
+  try {
+    return parseInt(window.localStorage.getItem(key) || "0", 10) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+function writeTimestamp(key: string, now: number): void {
+  try {
+    window.localStorage.setItem(key, String(now));
+  } catch {
+    /* localStorage may be unavailable or full */
+  }
+}
+
+function askedThisSession(): boolean {
+  try {
+    return window.sessionStorage.getItem(SESSION_ASKED_KEY) === "1";
+  } catch {
+    // Without sessionStorage there is no way to bound the asks, so don't ask.
+    return true;
+  }
+}
+
+function markAskedThisSession(): void {
+  try {
+    window.sessionStorage.setItem(SESSION_ASKED_KEY, "1");
+  } catch {
+    /* sessionStorage may be unavailable */
+  }
+}
+
+function isEligible(now: number): boolean {
+  if (isDisabled()) return false;
+  // Prompting a user whose telemetry is off would collect a response we then
+  // drop on the floor. Ask only the people we can actually hear.
+  if (!browserTelemetryAllowed()) return false;
+  if (askedThisSession()) return false;
+  if (now - readTimestamp(STORAGE_KEYS.answeredAt) < ANSWERED_COOLDOWN_MS) return false;
+  if (now - readTimestamp(STORAGE_KEYS.dismissedAt) < DISMISSED_COOLDOWN_MS) return false;
+  return true;
+}
+
+/**
+ * Ask for feedback about `request` if the user is due. Safe to call on every
+ * render outcome: ineligible calls are dropped without touching any state, so
+ * a user who just answered stays quiet rather than burning their next window.
+ */
+export function requestStudioFeedback(request: FeedbackRequest): void {
+  if (!listener) return;
+  if (!isEligible(Date.now())) return;
+  markAskedThisSession();
+  listener(request);
+}
+
+/** Subscribe the card. Single-subscriber by design — there is one card. */
+export function subscribeToFeedbackRequests(next: Listener): () => void {
+  listener = next;
+  return () => {
+    if (listener === next) listener = null;
+  };
+}
+
+export function markFeedbackAnswered(): void {
+  writeTimestamp(STORAGE_KEYS.answeredAt, Date.now());
+}
+
+export function markFeedbackDismissed(): void {
+  writeTimestamp(STORAGE_KEYS.dismissedAt, Date.now());
+}

package/src/components/feedback/projectProvenance.test.ts

@@ -0,0 +1,120 @@
+// @vitest-environment happy-dom
+
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import {
+  captureProjectProvenance,
+  projectProvenance,
+  resetProjectProvenance,
+} from "./projectProvenance";
+
+const CONFIG = "hyperframes.json";
+
+/**
+ * The real `/files/*` route answers with an envelope, not the file. Mocking the
+ * raw config here instead let a broken parse pass the suite and fail live, so
+ * this helper is deliberately shaped like the server's actual response.
+ */
+function mockConfigResponse(fileContent: string, ok = true) {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async () => ({
+      ok,
+      json: async () => ({ filename: CONFIG, content: fileContent, version: "abc" }),
+    })),
+  );
+}
+
+beforeEach(() => {
+  resetProjectProvenance();
+  vi.unstubAllGlobals();
+});
+
+describe("captureProjectProvenance", () => {
+  it("reads the authoring workflow that built the project", async () => {
+    mockConfigResponse(JSON.stringify({ authoringSkill: "faceless-explainer" }));
+    await captureProjectProvenance("p1", [CONFIG, "index.html"], ["index.html"]);
+    expect(projectProvenance()).toMatchObject({
+      project_scaffolded: true,
+      project_authoring_skill: "faceless-explainer",
+    });
+  });
+
+  it("counts compositions and media, which is what actually reproduces a bug", async () => {
+    mockConfigResponse("{}");
+    await captureProjectProvenance(
+      "p1",
+      [CONFIG, "index.html", "a.html", "assets/clip.mp4", "assets/vo.wav", "assets/logo.png"],
+      ["index.html", "a.html"],
+    );
+    expect(projectProvenance()).toMatchObject({
+      project_composition_count: 2,
+      project_media_count: 3,
+      project_file_count: 6,
+    });
+  });
+
+  it("flags a project that init never scaffolded, and skips the config fetch", async () => {
+    const fetchSpy = vi.fn();
+    vi.stubGlobal("fetch", fetchSpy);
+    await captureProjectProvenance("p1", ["index.html"], ["index.html"]);
+    expect(projectProvenance().project_scaffolded).toBe(false);
+    expect(projectProvenance().project_authoring_skill).toBeUndefined();
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  // Every way the config can fail to yield a skill must still leave the counts
+  // behind: a partial report beats no report.
+  it.each([
+    ["the config is corrupt", () => mockConfigResponse("{ not json")],
+    [
+      "the envelope has no content field",
+      () =>
+        vi.stubGlobal(
+          "fetch",
+          vi.fn(async () => ({ ok: true, json: async () => ({ error: "not found" }) })),
+        ),
+    ],
+    [
+      "the fetch fails outright",
+      () =>
+        vi.stubGlobal(
+          "fetch",
+          vi.fn(async () => {
+            throw new Error("offline");
+          }),
+        ),
+    ],
+    ["the route answers non-ok", () => mockConfigResponse("{}", false)],
+  ])("keeps the counts when %s", async (_case, arrange) => {
+    arrange();
+    await expect(
+      captureProjectProvenance("p1", [CONFIG, "index.html"], ["index.html"]),
+    ).resolves.toBeUndefined();
+    expect(projectProvenance().project_scaffolded).toBe(true);
+    expect(projectProvenance().project_composition_count).toBe(1);
+    expect(projectProvenance().project_authoring_skill).toBeUndefined();
+  });
+
+  describe("privacy", () => {
+    it("drops a hand-edited skill that is not a slug, so no free text escapes", async () => {
+      mockConfigResponse(
+        JSON.stringify({ authoringSkill: "my client's secret campaign /Users/me/x" }),
+      );
+      await captureProjectProvenance("p1", [CONFIG], []);
+      expect(projectProvenance().project_authoring_skill).toBeUndefined();
+    });
+
+    it("never copies file names, paths or the project title", async () => {
+      mockConfigResponse(JSON.stringify({ authoringSkill: "slideshow", title: "Secret Launch" }));
+      await captureProjectProvenance(
+        "p1",
+        [CONFIG, "assets/unreleased-product-hero.mp4"],
+        ["index.html"],
+      );
+      const flat = JSON.stringify(projectProvenance());
+      expect(flat).not.toContain("unreleased");
+      expect(flat).not.toContain("Secret");
+      expect(flat).not.toContain("assets/");
+    });
+  });
+});

package/src/components/feedback/projectProvenance.ts

@@ -0,0 +1,83 @@
+// ---------------------------------------------------------------------------
+// How this project came to exist, and roughly what shape it is.
+//
+// A crash report says what broke. It does not say what the user was working ON,
+// and "a project made by /faceless-explainer with 14 compositions and 60 assets"
+// reproduces a crash that "Cannot read properties of undefined" never will.
+//
+// Held at module scope on purpose: a crash unmounts the React tree, so anything
+// living in component state is gone by the time the crash prompt renders. This
+// survives, because it was captured when the project loaded.
+//
+// PRIVACY: counts, a skill slug, and booleans. No file names, no paths, no
+// project title. The user consented to a comment, not to an inventory of their
+// work.
+// ---------------------------------------------------------------------------
+
+import type { FeedbackContext } from "./feedbackTrigger";
+
+/** Written by `hyperframes init`; absent in a hand-made or copied project. */
+const CONFIG_FILE = "hyperframes.json";
+
+/** Matches the CLI's own slug gate, so a hand-edited value cannot leak text. */
+const SKILL_SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+const MEDIA_EXTENSIONS = /\.(mp4|mov|webm|m4v|mp3|wav|m4a|aac|ogg|png|jpe?g|gif|webp|svg|avif)$/i;
+
+let snapshot: FeedbackContext = {};
+
+function countMedia(files: string[]): number {
+  return files.filter((f) => MEDIA_EXTENSIONS.test(f)).length;
+}
+
+/**
+ * Record what we can see from the project listing, then fill in the authoring
+ * skill from `hyperframes.json` if the project has one. Failure is silent and
+ * partial: a report with the counts but no skill still beats no report.
+ */
+export async function captureProjectProvenance(
+  projectId: string,
+  files: string[],
+  compositions: string[],
+): Promise<void> {
+  const scaffolded = files.includes(CONFIG_FILE);
+  snapshot = {
+    // False means the project was copied, hand-written, or predates init.
+    // Those reproduce differently from a scaffolded one, so the flag matters
+    // even when the skill below is missing.
+    project_scaffolded: scaffolded,
+    project_composition_count: compositions.length,
+    project_file_count: files.length,
+    project_media_count: countMedia(files),
+  };
+  if (!scaffolded) return;
+
+  try {
+    const res = await fetch(`/api/projects/${projectId}/files/${encodeURIComponent(CONFIG_FILE)}`);
+    if (!res.ok) return;
+    // The route answers with an envelope, not the file: {filename, content,
+    // version}. The config is the `content` string inside it.
+    const envelope: unknown = await res.json();
+    const raw = (envelope as { content?: unknown }).content;
+    if (typeof raw !== "string") return;
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null) return;
+    const skill = (parsed as { authoringSkill?: unknown }).authoringSkill;
+    // The workflow that built this project: which of the creation skills the
+    // agent ran. This is the closest thing to "how was it made" we can get.
+    if (typeof skill === "string" && SKILL_SLUG.test(skill)) {
+      snapshot.project_authoring_skill = skill;
+    }
+  } catch {
+    // Missing, unreadable or corrupt config: keep the counts, drop the skill.
+  }
+}
+
+export function projectProvenance(): FeedbackContext {
+  return snapshot;
+}
+
+/** Test seam. */
+export function resetProjectProvenance(): void {
+  snapshot = {};
+}

package/src/components/renders/useRenderQueue.ts

@@ -4,6 +4,7 @@ import { trackStudioRenderStart } from "../../telemetry/events";
 import { getAnonymousId } from "../../telemetry/config";
 import { browserTelemetryAllowed } from "../../telemetry/policy";
 import { generateId } from "../../utils/generateId";
+import { requestStudioFeedback, type FeedbackContext } from "../feedback/feedbackTrigger";
 
 export interface RenderJob {
   id: string;
@@ -72,6 +73,23 @@ export function useRenderQueue(projectId: string | null) {
   const [actionError, setActionError] = useState<string | null>(null);
   const eventSourceRef = useRef<EventSource | null>(null);
   const activeJobRef = useRef<string | null>(null);
+  // Renders started in THIS tab, mapped to the settings they ran with.
+  // `loadRenders` also injects finished jobs from disk history, and those must
+  // never trigger a feedback prompt — the user did not just watch them happen.
+  const sessionJobs = useRef(new Map<string, FeedbackContext>());
+  const promptedJobIds = useRef(new Set<string>());
+
+  /**
+   * The one way a render started here enters the list. Every start path — the
+   * happy one and all three failure shortcuts — goes through here, so both
+   * "this render belongs to this session" and "these are the settings it ran
+   * with" have a single owner. A report about a render is only actionable if
+   * it arrives with the settings that produced it.
+   */
+  const addSessionJob = useCallback((job: RenderJob, settings: FeedbackContext) => {
+    sessionJobs.current.set(job.id, settings);
+    setJobs((prev) => [...prev, job]);
+  }, []);
 
   const closeActiveEventSource = useCallback((jobId?: string) => {
     if (jobId && activeJobRef.current !== jobId) return;
@@ -148,6 +166,16 @@ export function useRenderQueue(projectId: string | null) {
       });
 
       const startTime = Date.now();
+      // Travels with any feedback about this render. Settings only: the
+      // composition path is a name the user chose, not file contents.
+      const settings: FeedbackContext = {
+        render_format: format,
+        render_quality: quality,
+        render_fps: fps,
+        render_resolution: resolution ?? "auto",
+        render_composition: composition ?? "index.html",
+        render_has_variables: Boolean(opts.variables && Object.keys(opts.variables).length > 0),
+      };
       // "auto" / undefined means "render at the composition's authored size".
       // Omit the field entirely — sending "auto" would trip the route's
       // enum validation set.
@@ -201,7 +229,7 @@ export function useRenderQueue(projectId: string | null) {
           filename: "Export failed",
           createdAt: startTime,
         };
-        setJobs((prev) => [...prev, failedJob]);
+        addSessionJob(failedJob, settings);
         return;
       }
       if (!res.ok) {
@@ -213,7 +241,7 @@ export function useRenderQueue(projectId: string | null) {
           filename: "Export failed",
           createdAt: startTime,
         };
-        setJobs((prev) => [...prev, failedJob]);
+        addSessionJob(failedJob, settings);
         return;
       }
       const { jobId } = await res.json();
@@ -227,7 +255,7 @@ export function useRenderQueue(projectId: string | null) {
         filename: `${jobId}${ext}`,
         createdAt: startTime,
       };
-      setJobs((prev) => [...prev, job]);
+      addSessionJob(job, settings);
       activeJobRef.current = jobId;
 
       // Track progress via SSE
@@ -279,7 +307,7 @@ export function useRenderQueue(projectId: string | null) {
 
       return jobId;
     },
-    [projectId, closeActiveEventSource],
+    [projectId, closeActiveEventSource, addSessionJob],
   );
 
   // Cancel an in-flight render. The job row stays (as "cancelled") so the
@@ -352,6 +380,36 @@ export function useRenderQueue(projectId: string | null) {
 
   const dismissActionError = useCallback(() => setActionError(null), []);
 
+  // Ask for feedback the moment a render this tab started reaches its outcome.
+  // Watching the list (rather than each of the four places a job can finish)
+  // keeps one trigger for every path, including SSE drops and cancels-that-
+  // finished-anyway. `requestStudioFeedback` decides whether to actually ask.
+  useEffect(() => {
+    for (const job of jobs) {
+      if (job.status === "rendering" || job.status === "cancelled") continue;
+      const settings = sessionJobs.current.get(job.id);
+      if (!settings || promptedJobIds.current.has(job.id)) continue;
+      promptedJobIds.current.add(job.id);
+      requestStudioFeedback({
+        reason: job.status === "complete" ? "render_complete" : "render_failed",
+        renderId: job.id,
+        detail: job.error,
+        context: {
+          ...settings,
+          // How far it got and how long it took separate "died on frame one"
+          // from "died during encode", which need different fixes.
+          render_progress: job.progress,
+          render_duration_ms: job.durationMs ?? Date.now() - job.createdAt,
+          render_stage: job.stage,
+          render_error: job.error,
+          // Earlier renders this session: a first-render failure and a
+          // failure after nine successes are different bugs.
+          renders_this_session: sessionJobs.current.size,
+        },
+      });
+    }
+  }, [jobs]);
+
   // Clean up EventSource on unmount or projectId change
   useEffect(() => {
     return () => {

package/src/components/storyboard/StoryboardFrameFocus.tsx

@@ -11,6 +11,7 @@ import {
 } from "./AgentChatMessageButton";
 import { FRAME_STATUS_META } from "./frameStatus";
 import type { CommentsSubmitState } from "./useFrameComments";
+import { isTypingTarget } from "../../utils/typingTarget";
 
 export interface StoryboardFrameFocusProps {
   projectId: string;
@@ -140,8 +141,7 @@ export function StoryboardFrameFocus({
   useEffect(() => {
     // fallow-ignore-next-line complexity
     const onKey = (e: KeyboardEvent) => {
-      const el = document.activeElement;
-      if (el instanceof HTMLTextAreaElement || el instanceof HTMLInputElement) return;
+      if (isTypingTarget(document.activeElement)) return;
       if (e.key === "Escape") handleBack();
       else if (e.key === "ArrowLeft" && frame.index > 1) handleNavigate(-1);
       else if (e.key === "ArrowRight" && frame.index < frameCount) handleNavigate(1);

package/src/components/storyboard/StoryboardViewModeGuard.test.tsx

@@ -26,6 +26,7 @@ vi.mock("./FramePoster", () => ({
 }));
 
 const onSelectComposition = vi.fn();
+const onNavigate = vi.fn();
 
 function TestApp() {
   const viewMode = useViewModeState();
@@ -48,9 +49,9 @@ function TestApp() {
             narrative: "",
             extra: {},
           }}
-          frameCount={1}
+          frameCount={2}
           onBack={vi.fn()}
-          onNavigate={vi.fn()}
+          onNavigate={onNavigate}
           onSaved={vi.fn()}
           onSelectComposition={onSelectComposition}
           scriptExists={false}
@@ -109,6 +110,7 @@ beforeEach(() => {
   window.history.replaceState({ entry: "timeline" }, "", "/");
   window.history.pushState({ entry: "storyboard" }, "", "/?view=storyboard");
   onSelectComposition.mockReset();
+  onNavigate.mockReset();
 });
 
 afterEach(() => {
@@ -168,3 +170,18 @@ describe("dirty storyboard voiceover view-mode guard", () => {
     act(() => root.unmount());
   });
 });
+
+describe("storyboard frame keyboard navigation", () => {
+  it("leaves arrow keys with contenteditable text", () => {
+    const { host, root } = renderApp();
+    const editor = document.createElement("div");
+    editor.contentEditable = "true";
+    host.append(editor);
+    editor.focus();
+
+    act(() => window.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowRight" })));
+
+    expect(onNavigate).not.toHaveBeenCalled();
+    act(() => root.unmount());
+  });
+});