@hyperframes/studio 0.9.19 → 0.9.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/dist/assets/{hyperframes-player-Dszy0WKm.js → hyperframes-player-ZQZslutT.js} +3 -3
  2. package/dist/assets/index-Bgfyny02.css +1 -0
  3. package/dist/assets/{index-CWYuXWlI.js → index-Bn5atbhb.js} +1 -1
  4. package/dist/assets/{index-BeR5xCi5.js → index-Bz2pYyGM.js} +196 -196
  5. package/dist/index.d.ts +1 -4
  6. package/dist/index.html +2 -2
  7. package/dist/index.js +6571 -5519
  8. package/dist/styles.css +1 -1
  9. package/package.json +8 -8
  10. package/src/components/DesktopGuideCard.tsx +21 -4
  11. package/src/components/EditorShell.tsx +10 -7
  12. package/src/components/OpenInDesktopButton.dom.test.tsx +64 -8
  13. package/src/components/OpenInDesktopButton.tsx +31 -14
  14. package/src/components/editor/DomEditGestureReadout.test.tsx +177 -0
  15. package/src/components/editor/DomEditGestureReadout.tsx +58 -0
  16. package/src/components/editor/DomEditOverlay.tsx +6 -0
  17. package/src/components/editor/domEditGestureReadoutState.ts +55 -0
  18. package/src/components/editor/domEditOverlayGestures.ts +12 -0
  19. package/src/components/editor/domEditOverlayStartGesture.ts +2 -0
  20. package/src/components/editor/useDomEditOverlayGestures.ts +12 -13
  21. package/src/components/nle/NLEPreview.test.ts +72 -0
  22. package/src/components/nle/NLEPreview.tsx +8 -9
  23. package/src/components/nle/PreviewZoomOverlay.tsx +155 -9
  24. package/src/components/nle/previewZoom.test.ts +98 -0
  25. package/src/components/nle/previewZoom.ts +65 -1
  26. package/src/components/panels/MotionBlurPanel.test.tsx +4 -0
  27. package/src/components/panels/MotionBlurPanel.tsx +1 -1
  28. package/src/components/storyboard/ApproveBoardButton.dom.test.tsx +48 -0
  29. package/src/components/storyboard/ApproveBoardButton.tsx +33 -0
  30. package/src/components/storyboard/PreviewStage.dom.test.tsx +114 -0
  31. package/src/components/storyboard/PreviewStage.player.dom.test.tsx +72 -0
  32. package/src/components/storyboard/PreviewStage.tsx +93 -0
  33. package/src/components/storyboard/StoryboardBoardView.tsx +322 -0
  34. package/src/components/storyboard/storyboardBoard.test.ts +183 -0
  35. package/src/components/storyboard/storyboardBoard.ts +148 -0
  36. package/src/components/storyboard/useStoryboardBoard.ts +99 -0
  37. package/src/hooks/elementPickerHoverLabel.browser.test.ts +85 -0
  38. package/src/hooks/elementPickerHoverLabel.test.ts +106 -0
  39. package/src/hooks/elementPickerHoverLabel.ts +173 -0
  40. package/src/hooks/fileChangeFanout.test.ts +20 -0
  41. package/src/hooks/fileChangeFanout.ts +13 -0
  42. package/src/hooks/useElementPicker.test.ts +254 -3
  43. package/src/hooks/useElementPicker.ts +237 -48
  44. package/src/hooks/useExternalFileChangeCoordinator.ts +6 -1
  45. package/src/player/components/timelineProviderStateBuilders.test.ts +3 -6
  46. package/src/player/components/timelineProviderStateBuilders.ts +1 -2
  47. package/src/player/components/timelineShellMeta.tsx +0 -2
  48. package/src/player/components/useTimelineProviderState.tsx +1 -2
  49. package/src/player/components/useTimelineShiftModifier.test.tsx +40 -0
  50. package/src/player/components/useTimelineShiftModifier.ts +7 -7
  51. package/src/styles/theme.css +2 -0
  52. package/dist/assets/index-CNZk2EFC.css +0 -1
@@ -0,0 +1,322 @@
1
+ import { useCallback, useEffect, useState } from "react";
2
+ import { trackStudioEvent } from "../../utils/studioTelemetry";
3
+ import { OpenInDesktopButton } from "../OpenInDesktopButton";
4
+ import { ApproveBoardButton } from "./ApproveBoardButton";
5
+ import { Button, cn } from "../ui";
6
+ import { groupByAct, stillPath, type BoardFrame } from "./storyboardBoard";
7
+ import { projectFileUrl, type StoryboardBoard } from "./useStoryboardBoard";
8
+
9
+ interface Props {
10
+ projectId: string;
11
+ board: StoryboardBoard & { path: string };
12
+ /** Back to the film, at a moment of it. */
13
+ onShowInPreview: (seconds: number | null) => void;
14
+ }
15
+
16
+ /** A frame's start in seconds, from its "a to b" range; null when it has none. */
17
+ export const frameStart = (time: string): number | null => {
18
+ const at = /(\d+(?:\.\d+)?)/.exec(time)?.[1];
19
+ return at === undefined ? null : Number(at);
20
+ };
21
+
22
+ /** What the board area shows: the page as written, a wait, or the frames; and why, when it is not the frames. */
23
+ export function boardMode(
24
+ read: StoryboardBoard["read"],
25
+ asWritten: boolean,
26
+ ): { mode: "page" | "loading" | "frames"; frames: BoardFrame[]; reason: string | null } {
27
+ if (read.state === "failed")
28
+ return { mode: "page", frames: [], reason: "Couldn't read the page, shown as written" };
29
+ if (read.state === "loading") return { mode: "loading", frames: [], reason: null };
30
+ if (!read.frames.length)
31
+ return { mode: "page", frames: [], reason: "No frames found, shown as written" };
32
+ return { mode: asWritten ? "page" : "frames", frames: read.frames, reason: null };
33
+ }
34
+
35
+ /**
36
+ * The storyboard, drawn by Studio from the frames the agent's page holds: a board of stills, and one frame at a time.
37
+ * Notes, drawings and the go are Desktop's (they go to its agent), so the bar hands the project there.
38
+ */
39
+ export function StoryboardBoardView({ projectId, board, onShowInPreview }: Props) {
40
+ const [asWritten, setAsWritten] = useState(false);
41
+ const { mode, frames, reason } = boardMode(board.read, asWritten);
42
+ const still = (frame: BoardFrame): string | null => {
43
+ const path = stillPath(board.path, frame.still);
44
+ return path ? projectFileUrl(projectId, path, board.revision) : null;
45
+ };
46
+
47
+ return (
48
+ <div
49
+ className="flex h-full w-full min-w-0 flex-col bg-neutral-950"
50
+ data-testid="storyboard-board"
51
+ >
52
+ <BoardBar
53
+ path={board.path}
54
+ count={frames.length}
55
+ asWritten={mode === "page"}
56
+ canToggle={reason === null && mode !== "loading"}
57
+ onToggle={() => {
58
+ trackStudioEvent("storyboard_action", { action: asWritten ? "board" : "as_written" });
59
+ setAsWritten((v) => !v);
60
+ }}
61
+ reason={reason}
62
+ />
63
+ <div className="min-h-0 flex-1 overflow-auto">
64
+ {mode === "page" && (
65
+ <PageAsWritten url={projectFileUrl(projectId, board.path, board.revision)} />
66
+ )}
67
+ {mode === "loading" && (
68
+ <p className="p-6 text-step-11 text-text-4">Reading the storyboard…</p>
69
+ )}
70
+ {mode === "frames" && (
71
+ <FramesBody frames={frames} still={still} onShowInPreview={onShowInPreview} />
72
+ )}
73
+ </div>
74
+ </div>
75
+ );
76
+ }
77
+
78
+ /** The board of stills, or one frame of it. */
79
+ function FramesBody({
80
+ frames,
81
+ still,
82
+ onShowInPreview,
83
+ }: {
84
+ frames: BoardFrame[];
85
+ still: (frame: BoardFrame) => string | null;
86
+ onShowInPreview: (seconds: number | null) => void;
87
+ }) {
88
+ const [open, setOpen] = useState<number | null>(null);
89
+ useEffect(() => {
90
+ if (open !== null && open >= frames.length) setOpen(frames.length ? frames.length - 1 : null);
91
+ }, [frames.length, open]);
92
+ const frame = open === null ? undefined : frames[open];
93
+ if (!frame || open === null)
94
+ return (
95
+ <BoardGrid
96
+ frames={frames}
97
+ still={still}
98
+ onOpen={(i) => {
99
+ trackStudioEvent("storyboard_action", { action: "open_frame" });
100
+ setOpen(i);
101
+ }}
102
+ />
103
+ );
104
+ return (
105
+ <OpenFrame
106
+ frame={frame}
107
+ index={open}
108
+ count={frames.length}
109
+ src={still(frame)}
110
+ onStep={(to) => setOpen(Math.max(0, Math.min(frames.length - 1, to)))}
111
+ onClose={() => setOpen(null)}
112
+ onShowInPreview={() => {
113
+ trackStudioEvent("storyboard_action", { action: "show_in_preview" });
114
+ onShowInPreview(frameStart(frame.time));
115
+ }}
116
+ />
117
+ );
118
+ }
119
+
120
+ function BoardBar({
121
+ path,
122
+ count,
123
+ asWritten,
124
+ canToggle,
125
+ onToggle,
126
+ reason,
127
+ }: {
128
+ path: string;
129
+ count: number;
130
+ asWritten: boolean;
131
+ canToggle: boolean;
132
+ onToggle: () => void;
133
+ reason: string | null;
134
+ }) {
135
+ return (
136
+ <div className="flex min-h-10 shrink-0 flex-wrap items-center justify-between gap-x-4 gap-y-1 border-b border-border-strong bg-surface px-3 py-1">
137
+ <div className="flex min-w-0 items-center gap-2 text-step-11">
138
+ <span className="font-semibold text-text-0">Storyboard</span>
139
+ {count > 0 && !asWritten && <span className="text-text-3">{count} frames</span>}
140
+ <span className="truncate text-text-4" title={path}>
141
+ {reason ?? path}
142
+ </span>
143
+ {canToggle && (
144
+ <Button variant="ghost" size="sm" onClick={onToggle}>
145
+ {asWritten ? "Show as board" : "Show page as written"}
146
+ </Button>
147
+ )}
148
+ </div>
149
+ <div className="flex items-center gap-2">
150
+ <span className="text-step-10 text-text-3 max-[1100px]:hidden">
151
+ Approve to have your agent build it. Comments on frames are in the desktop app
152
+ </span>
153
+ <ApproveBoardButton />
154
+ <OpenInDesktopButton placement="storyboard" />
155
+ </div>
156
+ </div>
157
+ );
158
+ }
159
+
160
+ function BoardGrid({
161
+ frames,
162
+ still,
163
+ onOpen,
164
+ }: {
165
+ frames: BoardFrame[];
166
+ still: (frame: BoardFrame) => string | null;
167
+ onOpen: (index: number) => void;
168
+ }) {
169
+ let index = 0;
170
+ return (
171
+ <div className="flex flex-col gap-6 p-4">
172
+ {groupByAct(frames).map((group, g) => (
173
+ <section key={`${g}:${group.act}`} className="flex flex-col gap-3">
174
+ {group.act && (
175
+ <h3 className="text-step-10 font-semibold tracking-wide text-accent uppercase">
176
+ {group.act}
177
+ </h3>
178
+ )}
179
+ <div className="grid gap-3 [grid-template-columns:repeat(auto-fill,minmax(220px,1fr))]">
180
+ {group.frames.map((frame) => {
181
+ const at = index++;
182
+ const src = still(frame);
183
+ return (
184
+ <button
185
+ key={`${at}:${frame.number}`}
186
+ type="button"
187
+ onClick={() => onOpen(at)}
188
+ className="group flex flex-col overflow-hidden rounded-lg border border-border-strong bg-neutral-900 text-left outline-hidden hover:border-accent focus-visible:border-accent"
189
+ aria-label={`Frame ${frame.number}: ${frame.title}`}
190
+ >
191
+ <div className="flex aspect-video w-full items-center justify-center bg-black">
192
+ {src ? (
193
+ <img
194
+ src={src}
195
+ alt=""
196
+ className="h-full w-full object-contain"
197
+ loading="lazy"
198
+ />
199
+ ) : (
200
+ <span className="text-step-11 text-text-4">Not sketched yet</span>
201
+ )}
202
+ </div>
203
+ <div className="flex flex-col gap-0.5 p-2.5">
204
+ <span className="truncate text-step-11 font-semibold text-text-0">
205
+ {frame.number}: {frame.title || "Untitled"}
206
+ </span>
207
+ {frame.time && (
208
+ <span className="text-step-10 tabular-nums text-text-3">{frame.time}</span>
209
+ )}
210
+ {frame.words && (
211
+ <span className="line-clamp-2 text-step-10 text-text-2">{frame.words}</span>
212
+ )}
213
+ </div>
214
+ </button>
215
+ );
216
+ })}
217
+ </div>
218
+ </section>
219
+ ))}
220
+ </div>
221
+ );
222
+ }
223
+
224
+ function OpenFrame({
225
+ frame,
226
+ index,
227
+ count,
228
+ src,
229
+ onStep,
230
+ onClose,
231
+ onShowInPreview,
232
+ }: {
233
+ frame: BoardFrame;
234
+ index: number;
235
+ count: number;
236
+ src: string | null;
237
+ onStep: (to: number) => void;
238
+ onClose: () => void;
239
+ onShowInPreview: () => void;
240
+ }) {
241
+ const onKey = useCallback(
242
+ (e: KeyboardEvent) => {
243
+ const target = e.target as HTMLElement | null;
244
+ if (target?.closest("input, textarea, [contenteditable='true']")) return;
245
+ if (e.key === "ArrowLeft") onStep(index - 1);
246
+ else if (e.key === "ArrowRight") onStep(index + 1);
247
+ else if (e.key === "Escape") onClose();
248
+ else return;
249
+ e.preventDefault();
250
+ e.stopPropagation();
251
+ },
252
+ [index, onStep, onClose],
253
+ );
254
+ useEffect(() => {
255
+ window.addEventListener("keydown", onKey, true);
256
+ return () => window.removeEventListener("keydown", onKey, true);
257
+ }, [onKey]);
258
+
259
+ return (
260
+ <div className="flex h-full min-h-0 flex-col gap-3 p-4">
261
+ <div className="flex items-center justify-between gap-2">
262
+ <Button variant="ghost" size="sm" onClick={onClose}>
263
+ ← Whole board
264
+ </Button>
265
+ <div className="flex items-center gap-1">
266
+ <Button
267
+ variant="ghost"
268
+ size="sm"
269
+ disabled={index === 0}
270
+ onClick={() => onStep(index - 1)}
271
+ >
272
+ Back
273
+ </Button>
274
+ <span className="px-1 text-step-11 tabular-nums text-text-2">
275
+ {index + 1} / {count}
276
+ </span>
277
+ <Button
278
+ variant="ghost"
279
+ size="sm"
280
+ disabled={index >= count - 1}
281
+ onClick={() => onStep(index + 1)}
282
+ >
283
+ Next
284
+ </Button>
285
+ </div>
286
+ <Button variant="ghost" size="sm" onClick={onShowInPreview}>
287
+ Show in preview
288
+ </Button>
289
+ </div>
290
+ <div className="flex min-h-0 flex-1 items-center justify-center rounded-lg bg-black">
291
+ {src ? (
292
+ <img src={src} alt="" className="max-h-full max-w-full object-contain" />
293
+ ) : (
294
+ <span className="text-step-12 text-text-4">Not sketched yet</span>
295
+ )}
296
+ </div>
297
+ <div className="flex flex-col gap-1">
298
+ <span className="text-step-12 font-semibold text-text-0">
299
+ {frame.number}: {frame.title || "Untitled"}
300
+ {frame.time && (
301
+ <span className="ml-2 font-normal tabular-nums text-text-3">{frame.time}</span>
302
+ )}
303
+ </span>
304
+ {frame.words && <p className="text-step-11 text-text-2">{frame.words}</p>}
305
+ </div>
306
+ </div>
307
+ );
308
+ }
309
+
310
+ /** The agent's page itself, its scripts off: what a board Studio cannot read into frames still looks like. */
311
+ function PageAsWritten({ url }: { url: string }) {
312
+ return (
313
+ <iframe
314
+ key={url}
315
+ title="Storyboard page"
316
+ src={url}
317
+ sandbox=""
318
+ referrerPolicy="no-referrer"
319
+ className={cn("h-full w-full border-0 bg-white")}
320
+ />
321
+ );
322
+ }
@@ -0,0 +1,183 @@
1
+ // @vitest-environment happy-dom
2
+
3
+ import { describe, expect, it } from "vitest";
4
+ import {
5
+ findBoardFile,
6
+ groupByAct,
7
+ readBoardFrames,
8
+ stillPath,
9
+ touchesBoard,
10
+ } from "./storyboardBoard";
11
+ import { boardMode, frameStart } from "./StoryboardBoardView";
12
+
13
+ const page = (body: string) => new DOMParser().parseFromString(`<body>${body}</body>`, "text/html");
14
+
15
+ describe("findBoardFile", () => {
16
+ it("finds the board in boards/, whatever its case", () => {
17
+ expect(findBoardFile(["index.html", "boards/StoryBoard.html"])).toBe("boards/StoryBoard.html");
18
+ });
19
+
20
+ it("prefers a root copy over the one in boards/, as Desktop does", () => {
21
+ expect(findBoardFile(["boards/storyboard.html", "storyboard.html"])).toBe("storyboard.html");
22
+ });
23
+
24
+ it("does not take a board from any other folder", () => {
25
+ expect(findBoardFile(["old/boards/storyboard.html", "compositions/storyboard.html"])).toBe(
26
+ null,
27
+ );
28
+ });
29
+ });
30
+
31
+ describe("touchesBoard", () => {
32
+ it("counts the page, a still beside it and the plan, and nothing else", () => {
33
+ const board = "boards/storyboard.html";
34
+ expect(touchesBoard("boards/storyboard.html", board)).toBe(true);
35
+ expect(touchesBoard("boards/stills/frame-03-at-9.4s.png", board)).toBe(true);
36
+ expect(touchesBoard("STORYBOARD.md", board)).toBe(true);
37
+ expect(touchesBoard("index.html", board)).toBe(false);
38
+ expect(touchesBoard("compositions/s1.html", board)).toBe(false);
39
+ });
40
+
41
+ it("does not take every project write as the board's when the board is at the root", () => {
42
+ expect(touchesBoard("index.html", "storyboard.html")).toBe(false);
43
+ });
44
+
45
+ it("counts a still the board draws from outside its own folder: a root board, or ../assets", () => {
46
+ const rootStills = new Set([stillPath("storyboard.html", "stills/frame-01.png")!]);
47
+ expect(touchesBoard("stills/frame-01.png", "storyboard.html", rootStills)).toBe(true);
48
+ expect(touchesBoard("stills/frame-02.png", "storyboard.html", rootStills)).toBe(false);
49
+ expect(touchesBoard("index.html", "storyboard.html", rootStills)).toBe(false);
50
+ const board = "boards/storyboard.html";
51
+ const upStills = new Set([stillPath(board, "../assets/a.png")!]);
52
+ expect(touchesBoard("assets/a.png", board, upStills)).toBe(true);
53
+ expect(touchesBoard("assets/b.png", board, upStills)).toBe(false);
54
+ });
55
+ });
56
+
57
+ describe("stillPath", () => {
58
+ it("resolves a still against the page's own folder", () => {
59
+ expect(stillPath("boards/storyboard.html", "stills/frame-00-at-1.5s.png")).toBe(
60
+ "boards/stills/frame-00-at-1.5s.png",
61
+ );
62
+ expect(stillPath("boards/storyboard.html", "../assets/a%20b.png?v=2")).toBe("assets/a b.png");
63
+ });
64
+
65
+ it("refuses a still outside the project or on another host", () => {
66
+ expect(stillPath("boards/storyboard.html", "../../etc/passwd")).toBe(null);
67
+ expect(stillPath("boards/storyboard.html", "https://example.com/a.png")).toBe(null);
68
+ expect(stillPath("boards/storyboard.html", "data:image/png;base64,AAAA")).toBe(null);
69
+ expect(stillPath("boards/storyboard.html", "")).toBe(null);
70
+ });
71
+ });
72
+
73
+ describe("readBoardFrames", () => {
74
+ it("reads the recipe's page: act, number, title, time, still and words", () => {
75
+ const frames = readBoardFrames(
76
+ page(`
77
+ <section class="act">Act 1: Cold open</section>
78
+ <div class="frame">
79
+ <img src="stills/frame-00-at-1.5s.png" alt="" />
80
+ <div class="title">01: Three exits</div>
81
+ <div class="time">0.0 to 5.6s</div>
82
+ <p class="words">Badges 1, 2, 3 land on the words.</p>
83
+ </div>
84
+ <section class="act">Act 2: The filing</section>
85
+ <div class="frame">
86
+ <img src="stills/frame-01-at-6s.png" alt="" />
87
+ <div class="title">02: One goes to OpenAI</div>
88
+ <div class="time">5.6–9.4s</div>
89
+ </div>`),
90
+ );
91
+ expect(frames).toEqual([
92
+ {
93
+ number: "01",
94
+ title: "Three exits",
95
+ act: "Act 1: Cold open",
96
+ time: "0.0 to 5.6s",
97
+ still: "stills/frame-00-at-1.5s.png",
98
+ words: "Badges 1, 2, 3 land on the words.",
99
+ },
100
+ {
101
+ number: "02",
102
+ title: "One goes to OpenAI",
103
+ act: "Act 2: The filing",
104
+ time: "5.6 to 9.4s",
105
+ still: "stills/frame-01-at-6s.png",
106
+ words: "",
107
+ },
108
+ ]);
109
+ });
110
+
111
+ it("numbers frames by place when the page gives none, and keeps a nested frame inside its parent", () => {
112
+ const frames = readBoardFrames(
113
+ page(`
114
+ <div class="frame"><div class="title">The hook</div><div class="frame"><img src="a.png"></div></div>
115
+ <div class="frame"><div class="title">The turn</div></div>`),
116
+ );
117
+ expect(frames.map((f) => [f.number, f.title])).toEqual([
118
+ ["01", "The hook"],
119
+ ["02", "The turn"],
120
+ ]);
121
+ });
122
+
123
+ it("finds no frames on a page that marks them another way", () => {
124
+ expect(
125
+ readBoardFrames(page(`<div class="cell" id="frame-01"><img src="a.png"></div>`)),
126
+ ).toEqual([]);
127
+ });
128
+ });
129
+
130
+ describe("groupByAct", () => {
131
+ it("keeps film order and starts a group at each act change", () => {
132
+ const frame = (act: string, number: string) => ({
133
+ act,
134
+ number,
135
+ title: "",
136
+ time: "",
137
+ still: "",
138
+ words: "",
139
+ });
140
+ const groups = groupByAct([
141
+ frame("", "01"),
142
+ frame("A", "02"),
143
+ frame("A", "03"),
144
+ frame("B", "04"),
145
+ ]);
146
+ expect(groups.map((g) => [g.act, g.frames.map((f) => f.number)])).toEqual([
147
+ ["", ["01"]],
148
+ ["A", ["02", "03"]],
149
+ ["B", ["04"]],
150
+ ]);
151
+ });
152
+ });
153
+
154
+ describe("frameStart", () => {
155
+ it("reads a frame's start from its range", () => {
156
+ expect(frameStart("9.4 to 15.7s")).toBe(9.4);
157
+ expect(frameStart("")).toBe(null);
158
+ });
159
+ });
160
+
161
+ describe("boardMode", () => {
162
+ const frame = { number: "01", title: "A", act: "", time: "", still: "", words: "" };
163
+
164
+ it("shows the page as written, with the reason, when it holds no frames or cannot be read", () => {
165
+ expect(boardMode({ state: "read", frames: [] }, false)).toMatchObject({
166
+ mode: "page",
167
+ reason: "No frames found, shown as written",
168
+ });
169
+ expect(boardMode({ state: "failed" }, false)).toMatchObject({
170
+ mode: "page",
171
+ reason: "Couldn't read the page, shown as written",
172
+ });
173
+ });
174
+
175
+ it("shows the frames, or the page when the person asks for it", () => {
176
+ expect(boardMode({ state: "read", frames: [frame] }, false)).toEqual({
177
+ mode: "frames",
178
+ frames: [frame],
179
+ reason: null,
180
+ });
181
+ expect(boardMode({ state: "read", frames: [frame] }, true).mode).toBe("page");
182
+ });
183
+ });
@@ -0,0 +1,148 @@
1
+ // Read the way HyperFrames Desktop's Storyboard tab reads the page, so a board one shows is a board the other shows.
2
+
3
+ /** Where the page may sit, in the order a copy wins: the project root, then boards/. */
4
+ const BOARD_DIRS = ["", "boards/"];
5
+ const BOARD_FILE = "storyboard.html";
6
+ const PLAN_FILE = "storyboard.md";
7
+
8
+ export function findBoardFile(files: readonly string[]): string | null {
9
+ for (const dir of BOARD_DIRS) {
10
+ const found = files.find((path) => path.toLowerCase() === dir + BOARD_FILE);
11
+ if (found) return found;
12
+ }
13
+ return null;
14
+ }
15
+
16
+ const folderOf = (path: string): string => path.slice(0, path.lastIndexOf("/") + 1);
17
+
18
+ /** Whether a write to `changed` changes what the board at `board` shows: the page, anything beside it, a still
19
+ * it draws (`stills`, as project paths), or the plan. */
20
+ export function touchesBoard(
21
+ changed: string,
22
+ board: string,
23
+ stills: ReadonlySet<string> = new Set(),
24
+ ): boolean {
25
+ const path = changed.replace(/\\/g, "/").replace(/^\.\//, "");
26
+ if (path === board || path.toLowerCase() === PLAN_FILE || stills.has(path)) return true;
27
+ const folder = folderOf(board);
28
+ return folder !== "" && path.startsWith(folder);
29
+ }
30
+
31
+ /** A still's project path, from its `src` as the page wrote it; null for one that is not a project file. */
32
+ export function stillPath(board: string, src: string): string | null {
33
+ if (!src || /^[a-z][a-z0-9+.-]*:/i.test(src) || src.startsWith("//")) return null;
34
+ const clean = src.split(/[?#]/)[0] ?? "";
35
+ const parts = (clean.startsWith("/") ? clean.slice(1) : folderOf(board) + clean).split("/");
36
+ const out: string[] = [];
37
+ for (const part of parts) {
38
+ if (part === "" || part === ".") continue;
39
+ if (part === "..") {
40
+ if (!out.length) return null;
41
+ out.pop();
42
+ } else out.push(part);
43
+ }
44
+ return out.length ? out.map(safeDecode).join("/") : null;
45
+ }
46
+
47
+ const safeDecode = (part: string): string => {
48
+ try {
49
+ return decodeURIComponent(part);
50
+ } catch {
51
+ return part;
52
+ }
53
+ };
54
+
55
+ export interface BoardFrame {
56
+ number: string;
57
+ title: string;
58
+ act: string;
59
+ /** Its range as "a to b" ("0.0 to 3.0s"), or "". */
60
+ time: string;
61
+ still: string;
62
+ words: string;
63
+ }
64
+
65
+ const TIME = /\d+(?:[.:]\d+)?\s*s?\s*[–-]\s*\d+(?:[.:]\d+)?\s*s?/;
66
+ // "01 — The dial", "00a · Cold open — the line": a frame's number, then its name.
67
+ const NUMBERED = /^\s*(\d{1,3}[a-z]?)\s*[—–·.:-]\s*(.+)$/;
68
+ const NOTE_PLACES = [".desc", ".description", ".caption", ".note", ".words", "p"];
69
+
70
+ const text = (el: Element | null | undefined): string =>
71
+ (el?.textContent ?? "").replace(/\s+/g, " ").trim();
72
+ const tidy = (words: string): string =>
73
+ words
74
+ .replace(TIME, "")
75
+ .replace(/[\s·—–:-]+$/, "")
76
+ .trim();
77
+ const pad = (n: number): string => String(n).padStart(2, "0");
78
+
79
+ /** The `class="frame"` boxes the page draws, in order; a frame nested in another is part of it. */
80
+ export function readBoardFrames(doc: Document): BoardFrame[] {
81
+ const boxes = [...doc.querySelectorAll<HTMLElement>(".frame")].filter(
82
+ (el) => !el.parentElement?.closest(".frame"),
83
+ );
84
+ return boxes.map((el, i) => frameInfo(doc, el, i));
85
+ }
86
+
87
+ /** The frame's own box: its highest ancestor holding no other frame (a scene card, a contact-sheet cell). */
88
+ function ownBox(el: HTMLElement): HTMLElement {
89
+ let box = el;
90
+ while (box.parentElement && box.parentElement !== el.ownerDocument.body) {
91
+ if (box.parentElement.querySelectorAll(".frame").length > 1) break;
92
+ box = box.parentElement;
93
+ }
94
+ return box;
95
+ }
96
+
97
+ function frameInfo(doc: Document, el: HTMLElement, i: number): BoardFrame {
98
+ const box = ownBox(el);
99
+ const heading = box.querySelector(".scene-title, .label, [class*='title']");
100
+ const first = heading?.firstElementChild ? text(heading.firstElementChild) : text(heading);
101
+ const named = NUMBERED.exec(tidy(first));
102
+ return {
103
+ number: named?.[1] ?? badgeNumber(box) ?? pad(i + 1),
104
+ title: named?.[2]?.trim() ?? tidy(first),
105
+ act: actBefore(doc, el),
106
+ time: timeOf(box, heading),
107
+ still: el.querySelector("img")?.getAttribute("src") ?? "",
108
+ // First by this order, not the page's: a .words box can hold the title and time before its .note.
109
+ words: text(NOTE_PLACES.map((place) => box.querySelector(place)).find(Boolean)),
110
+ };
111
+ }
112
+
113
+ function timeOf(box: HTMLElement, heading: Element | null): string {
114
+ const raw = text(box.querySelector(".time")) || (text(heading).match(TIME)?.[0] ?? "");
115
+ return raw.replace(/\s*[\u2013-]\s*/, " to ");
116
+ }
117
+
118
+ function badgeNumber(box: HTMLElement): string | undefined {
119
+ const badge = /\d+/.exec(text(box.querySelector(".scene-badge")))?.[0];
120
+ return badge === undefined ? undefined : pad(Number(badge));
121
+ }
122
+
123
+ /** The act heading last before the frame, by its own words (not the times beside them). */
124
+ function actBefore(doc: Document, el: HTMLElement): string {
125
+ const acts = [...doc.querySelectorAll(".actbar, .act, [class*='act-bar']")].filter(
126
+ (act) => act.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_FOLLOWING,
127
+ );
128
+ const act = acts.at(-1);
129
+ if (!act) return "";
130
+ const own = [...act.childNodes]
131
+ .filter((node) => node.nodeType === Node.TEXT_NODE)
132
+ .map((node) => node.textContent)
133
+ .join(" ")
134
+ .replace(/\s+/g, " ")
135
+ .trim();
136
+ return tidy(own || text(act));
137
+ }
138
+
139
+ /** The frames in their acts, in film order; frames before any act heading share one untitled group. */
140
+ export function groupByAct(frames: readonly BoardFrame[]): { act: string; frames: BoardFrame[] }[] {
141
+ const groups: { act: string; frames: BoardFrame[] }[] = [];
142
+ for (const frame of frames) {
143
+ const last = groups.at(-1);
144
+ if (last && last.act === frame.act) last.frames.push(frame);
145
+ else groups.push({ act: frame.act, frames: [frame] });
146
+ }
147
+ return groups;
148
+ }