@hyperframes/studio 0.5.0-alpha.8 → 0.5.0

package/src/captions/components/CaptionOverlay.tsx

@@ -1,6 +1,7 @@
 import { memo, useState, useCallback, useRef } from "react";
 import { useCaptionStore } from "../store";
 import { useMountEffect } from "../../hooks/useMountEffect";
+import { shouldHandleCaptionNudgeKey } from "../keyboard";
 
 interface CaptionOverlayProps {
   iframeRef: React.RefObject<HTMLIFrameElement | null>;
@@ -329,7 +330,7 @@ export const CaptionOverlay = memo(function CaptionOverlay({ iframeRef }: Captio
       const { selectedSegmentIds: sel, model: m } = useCaptionStore.getState();
       if (sel.size === 0 || !m) return;
       const arrow = e.key;
-      if (!["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"].includes(arrow)) return;
+      if (!shouldHandleCaptionNudgeKey(e)) return;
 
       e.preventDefault();
       const step = e.shiftKey ? 10 : 1;

package/src/captions/generator.test.ts

@@ -137,6 +137,25 @@ describe("generateCaptionHtml", () => {
       expect(html).toContain('"end": 2.7');
     });
 
+    it("includes stable word ids in the transcript and generated word spans", () => {
+      const transcript: TranscriptWord[] = [
+        { id: "word-a", text: "Hello", start: 0, end: 0.4 },
+        { id: "word-b", text: "world", start: 0.5, end: 1 },
+      ];
+      const model = buildCaptionModel(transcript, {
+        width: 1920,
+        height: 1080,
+        duration: 2,
+      });
+
+      const html = generateCaptionHtml(model);
+
+      expect(html).toContain('"id": "word-a"');
+      expect(html).toContain('"id": "word-b"');
+      expect(html).toContain('w_segment_0.id = "word-a";');
+      expect(html).toContain('w_segment_1.id = "word-b";');
+    });
+
     it("TRANSCRIPT contains all 7 words from the sample", () => {
       const model = buildTestModel();
       const html = generateCaptionHtml(model);

package/src/captions/generator.ts

@@ -261,14 +261,19 @@ function hexToRgba(color: string, opacity: number): string {
 
 function generateJs(model: CaptionModel): string {
   // Collect all segments across all groups in order
-  const allSegments: Array<{ text: string; start: number; end: number }> = [];
+  const allSegments: Array<{ id?: string; text: string; start: number; end: number }> = [];
   for (const groupId of model.groupOrder) {
     const group = model.groups.get(groupId);
     if (!group) continue;
     for (const segId of group.segmentIds) {
       const seg = model.segments.get(segId);
       if (!seg) continue;
-      allSegments.push({ text: seg.text, start: seg.start, end: seg.end });
+      allSegments.push({
+        ...(seg.wordId ? { id: seg.wordId } : {}),
+        text: seg.text,
+        start: seg.start,
+        end: seg.end,
+      });
     }
   }
 
@@ -300,9 +305,11 @@ function generateJs(model: CaptionModel): string {
     const wordLines: string[] = groupSegments.map((seg) => {
       const escaped = seg.text.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
       const segVar = `w_${seg.id.replace(/[^a-zA-Z0-9_]/g, "_")}`;
+      const idLine = seg.wordId ? `\n  ${segVar}.id = ${JSON.stringify(seg.wordId)};` : "";
       return (
         `  const ${segVar} = document.createElement('span');` +
         `\n  ${segVar}.className = 'word clip';` +
+        idLine +
         `\n  ${segVar}.textContent = '${escaped}';` +
         `\n  ${segVar}.dataset.start = '${seg.start}';` +
         `\n  ${segVar}.dataset.end = '${seg.end}';` +

package/src/captions/hooks/useCaptionSync.ts

@@ -124,17 +124,22 @@ export function useCaptionSync(projectId: string | null) {
 
       const model = state.model;
       const allSegIds: string[] = [];
+      const segIdByWordId = new Map<string, string>();
       for (const groupId of model.groupOrder) {
         const group = model.groups.get(groupId);
         if (!group) continue;
         for (const segId of group.segmentIds) {
           allSegIds.push(segId);
+          const seg = model.segments.get(segId);
+          if (seg?.wordId) segIdByWordId.set(seg.wordId, segId);
         }
       }
 
       const newSegments = new Map(model.segments);
       for (const override of overrides) {
-        const segId = allSegIds[override.wordIndex];
+        const segId =
+          (override.wordId ? segIdByWordId.get(override.wordId) : undefined) ??
+          allSegIds[override.wordIndex];
         if (!segId) continue;
         const seg = newSegments.get(segId);
         if (!seg) continue;

package/src/captions/keyboard.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { shouldHandleCaptionNudgeKey } from "./keyboard";
+
+function mockKeyboardEvent(
+  key: string,
+  overrides: Partial<Pick<KeyboardEvent, "altKey" | "ctrlKey" | "metaKey">> = {},
+): Pick<KeyboardEvent, "altKey" | "ctrlKey" | "metaKey" | "key"> {
+  return {
+    altKey: false,
+    ctrlKey: false,
+    metaKey: false,
+    key,
+    ...overrides,
+  };
+}
+
+describe("shouldHandleCaptionNudgeKey", () => {
+  it("handles plain and Shift-modified arrow keys for caption nudging", () => {
+    expect(shouldHandleCaptionNudgeKey(mockKeyboardEvent("ArrowLeft"))).toBe(true);
+    expect(shouldHandleCaptionNudgeKey(mockKeyboardEvent("ArrowRight"))).toBe(true);
+  });
+
+  it("ignores browser and app shortcut chords", () => {
+    expect(shouldHandleCaptionNudgeKey(mockKeyboardEvent("ArrowLeft", { altKey: true }))).toBe(
+      false,
+    );
+    expect(shouldHandleCaptionNudgeKey(mockKeyboardEvent("ArrowRight", { ctrlKey: true }))).toBe(
+      false,
+    );
+    expect(shouldHandleCaptionNudgeKey(mockKeyboardEvent("ArrowRight", { metaKey: true }))).toBe(
+      false,
+    );
+  });
+
+  it("ignores non-arrow keys", () => {
+    expect(shouldHandleCaptionNudgeKey(mockKeyboardEvent("KeyL"))).toBe(false);
+  });
+});

package/src/captions/keyboard.ts

@@ -0,0 +1,8 @@
+const CAPTION_NUDGE_KEYS = new Set(["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"]);
+
+type CaptionNudgeKeyEvent = Pick<KeyboardEvent, "altKey" | "ctrlKey" | "metaKey" | "key">;
+
+export function shouldHandleCaptionNudgeKey(event: CaptionNudgeKeyEvent): boolean {
+  if (event.metaKey || event.ctrlKey || event.altKey) return false;
+  return CAPTION_NUDGE_KEYS.has(event.key);
+}

package/src/captions/parser.test.ts

@@ -102,6 +102,20 @@ describe("extractTranscript", () => {
       expect(words).toHaveLength(1);
       expect(words[0]).toEqual({ text: "Hello", start: 0.0, end: 0.5 });
     });
+
+    it("preserves stable word ids when present", () => {
+      const words = extractTranscript(`
+        const TRANSCRIPT = [
+          { id: "word-a", text: "Hello", start: 0, end: 0.4 },
+          { id: "word-b", text: "world", start: 0.5, end: 1 },
+        ];
+      `);
+
+      expect(words).toEqual([
+        { id: "word-a", text: "Hello", start: 0, end: 0.4 },
+        { id: "word-b", text: "world", start: 0.5, end: 1 },
+      ]);
+    });
   });
 
   describe("script variable name", () => {

package/src/captions/parser.ts

@@ -303,6 +303,7 @@ function parseTranscriptArray(arrayLiteral: string): TranscriptWord[] {
     ) {
       const entry = item as Record<string, unknown>;
       words.push({
+        ...(typeof entry.id === "string" ? { id: entry.id } : {}),
         text: entry.text as string,
         start: entry.start as number,
         end: entry.end as number,

package/src/components/LintModal.tsx

@@ -1,6 +1,5 @@
 import { useState } from "react";
 import { XIcon, WarningIcon, CheckCircleIcon, CaretRightIcon } from "@phosphor-icons/react";
-import { copyTextToClipboard } from "../utils/clipboard";
 
 export interface LintFinding {
   severity: "error" | "warning";
@@ -31,10 +30,12 @@ export function LintModal({
       return line;
     });
     const text = `Fix these HyperFrames lint issues for project "${projectId}":\n\nProject path: ${window.location.href}\n\n${lines.join("\n\n")}`;
-    const copiedText = await copyTextToClipboard(text);
-    if (copiedText) {
+    try {
+      await navigator.clipboard.writeText(text);
       setCopied(true);
       setTimeout(() => setCopied(false), 2000);
+    } catch {
+      // ignore
     }
   };