@hyperframes/studio 0.8.50 → 0.8.53-desktop.0

package/src/hooks/useProjectSignaturePoll.test.tsx

@@ -1,135 +0,0 @@
-// @vitest-environment happy-dom
-
-import React, { act } from "react";
-import { createRoot, type Root } from "react-dom/client";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { useProjectSignaturePoll } from "./useProjectSignaturePoll";
-
-Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
-
-function HookHost({
-  signature,
-  onChange,
-}: {
-  signature: string | undefined;
-  onChange: () => void;
-}) {
-  useProjectSignaturePoll("demo", signature, onChange);
-  return null;
-}
-
-let root: Root | null = null;
-let container: HTMLElement | null = null;
-
-function mount(signature: string | undefined, onChange: () => void): void {
-  act(() => {
-    if (!root) {
-      container = document.createElement("div");
-      document.body.appendChild(container);
-      root = createRoot(container);
-    }
-    root.render(<HookHost signature={signature} onChange={onChange} />);
-  });
-}
-
-function unmount(): void {
-  if (root) {
-    act(() => root?.unmount());
-    root = null;
-  }
-  container?.remove();
-  container = null;
-}
-
-function mockSignatureResponse(signature: string): ReturnType<typeof vi.fn> {
-  const fetchMock = vi.fn(async () => ({ ok: true, json: async () => ({ signature }) }));
-  vi.stubGlobal("fetch", fetchMock);
-  return fetchMock;
-}
-
-describe("useProjectSignaturePoll", () => {
-  beforeEach(() => {
-    vi.useFakeTimers();
-  });
-
-  afterEach(() => {
-    unmount();
-    vi.useRealTimers();
-    vi.unstubAllGlobals();
-    vi.restoreAllMocks();
-  });
-
-  it("fires onChange when the polled signature moves past the loaded one", async () => {
-    const fetchMock = mockSignatureResponse("sig-b");
-    const onChange = vi.fn();
-    mount("sig-a", onChange);
-
-    await vi.advanceTimersByTimeAsync(2000);
-    expect(fetchMock).toHaveBeenCalledWith("/api/projects/demo/signature");
-    expect(onChange).toHaveBeenCalledTimes(1);
-  });
-
-  it("stays quiet while the polled signature matches", async () => {
-    mockSignatureResponse("sig-a");
-    const onChange = vi.fn();
-    mount("sig-a", onChange);
-
-    await vi.advanceTimersByTimeAsync(6000);
-    expect(onChange).not.toHaveBeenCalled();
-  });
-
-  it("does not poll before a baseline signature exists", async () => {
-    const fetchMock = mockSignatureResponse("sig-a");
-    const onChange = vi.fn();
-    mount(undefined, onChange);
-
-    await vi.advanceTimersByTimeAsync(6000);
-    expect(fetchMock).not.toHaveBeenCalled();
-    expect(onChange).not.toHaveBeenCalled();
-  });
-
-  it("re-arms against the caller's refreshed signature without re-mounting", async () => {
-    mockSignatureResponse("sig-b");
-    const onChange = vi.fn();
-    mount("sig-a", onChange);
-
-    await vi.advanceTimersByTimeAsync(2000);
-    expect(onChange).toHaveBeenCalledTimes(1);
-
-    // The caller refetched and now holds the polled signature — no more firing.
-    mount("sig-b", onChange);
-    await vi.advanceTimersByTimeAsync(6000);
-    expect(onChange).toHaveBeenCalledTimes(1);
-  });
-
-  it("skips ticks while the tab is hidden and re-checks on visibility", async () => {
-    const fetchMock = mockSignatureResponse("sig-b");
-    const onChange = vi.fn();
-    let hidden = true;
-    vi.spyOn(document, "hidden", "get").mockImplementation(() => hidden);
-    mount("sig-a", onChange);
-
-    await vi.advanceTimersByTimeAsync(6000);
-    expect(fetchMock).not.toHaveBeenCalled();
-
-    hidden = false;
-    await act(async () => {
-      document.dispatchEvent(new Event("visibilitychange"));
-      await vi.advanceTimersByTimeAsync(0);
-    });
-    expect(onChange).toHaveBeenCalledTimes(1);
-  });
-
-  it("stops polling after unmount", async () => {
-    mockSignatureResponse("sig-b");
-    const onChange = vi.fn();
-    mount("sig-a", onChange);
-
-    await vi.advanceTimersByTimeAsync(2000);
-    expect(onChange).toHaveBeenCalledTimes(1);
-
-    unmount();
-    await vi.advanceTimersByTimeAsync(10_000);
-    expect(onChange).toHaveBeenCalledTimes(1);
-  });
-});

package/src/hooks/useProjectSignaturePoll.ts

@@ -1,68 +0,0 @@
-import { useEffect, useRef } from "react";
-import { buildProjectApiPath } from "../utils/projectRouting";
-
-const POLL_INTERVAL_MS = 2000;
-
-/** One poll: the current signature, or null on any failure (skip this tick). */
-async function fetchProjectSignature(projectId: string): Promise<string | null> {
-  try {
-    const res = await fetch(buildProjectApiPath(projectId, "/signature"));
-    if (!res.ok) return null;
-    const body = (await res.json()) as { signature?: string };
-    return typeof body.signature === "string" ? body.signature : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Poll the project's content signature and fire `onChange` when it no longer
- * matches `currentSignature` — the storyboard board uses this to refresh itself
- * while an agent writes sketch frames to disk.
- *
- * The comparison baseline is the signature the caller's data was loaded with,
- * so a refetch triggered by `onChange` naturally re-arms the poll with the new
- * value. Ticks are skipped while the tab is hidden (a visibility flip re-checks
- * immediately) and while a previous request is still in flight; request
- * failures are ignored — polling degrades to today's manual-reload behavior.
- */
-export function useProjectSignaturePoll(
-  projectId: string | null,
-  currentSignature: string | undefined,
-  onChange: () => void,
-): void {
-  const signatureRef = useRef(currentSignature);
-  const onChangeRef = useRef(onChange);
-  signatureRef.current = currentSignature;
-  onChangeRef.current = onChange;
-
-  useEffect(() => {
-    if (!projectId) return;
-    let disposed = false;
-    let inFlight = false;
-
-    const tick = async () => {
-      if (disposed || inFlight || document.hidden) return;
-      // No baseline yet (initial storyboard fetch still loading, or an older
-      // server without the signature field) — nothing to compare against.
-      if (signatureRef.current === undefined) return;
-      inFlight = true;
-      const latest = await fetchProjectSignature(projectId);
-      inFlight = false;
-      if (disposed || latest === null) return;
-      if (latest !== signatureRef.current) onChangeRef.current();
-    };
-
-    const interval = window.setInterval(() => void tick(), POLL_INTERVAL_MS);
-    const onVisibilityChange = () => {
-      if (!document.hidden) void tick();
-    };
-    document.addEventListener("visibilitychange", onVisibilityChange);
-
-    return () => {
-      disposed = true;
-      window.clearInterval(interval);
-      document.removeEventListener("visibilitychange", onVisibilityChange);
-    };
-  }, [projectId]);
-}

package/src/hooks/useStoryboard.ts

@@ -1,99 +0,0 @@
-import { useCallback, useEffect, useRef, useState } from "react";
-import type {
-  StoryboardFrame,
-  StoryboardGlobals,
-  StoryboardWarning,
-} from "@hyperframes/core/storyboard";
-import { buildProjectApiPath } from "../utils/projectRouting";
-
-/** A frame as returned by the API: parsed frame + disk-resolution info. */
-export interface StoryboardFrameView extends StoryboardFrame {
-  /** Whether `src` resolves to an existing file inside the project. */
-  srcExists: boolean;
-}
-
-/** The companion narration script (SCRIPT.md), when present alongside the storyboard. */
-export interface StoryboardScript {
-  exists: boolean;
-  path: string;
-  content: string;
-}
-
-/** Shape of `GET /api/projects/:id/storyboard`. */
-export interface StoryboardResponse {
-  exists: boolean;
-  path: string;
-  globals: StoryboardGlobals;
-  frames: StoryboardFrameView[];
-  warnings: StoryboardWarning[];
-  script?: StoryboardScript;
-  /** Project content signature this payload was derived from (poster cache-bust + change poll). */
-  signature?: string;
-}
-
-export interface UseStoryboardResult {
-  data: StoryboardResponse | null;
-  loading: boolean;
-  error: string | null;
-  reload: () => void;
-}
-
-/**
- * Load the parsed storyboard manifest for a project. Markdown stays canonical on
- * disk; this fetches the server-derived JSON the storyboard view renders.
- *
- * `reload()` refetches in place: the blocking spinner only shows on first load
- * and project switches, so background refreshes (file-change polling, post-save
- * reloads) swap data without flashing the board.
- */
-export function useStoryboard(projectId: string | null): UseStoryboardResult {
-  const [data, setData] = useState<StoryboardResponse | null>(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-  const [reloadKey, setReloadKey] = useState(0);
-  const hasDataRef = useRef(false);
-  const lastProjectRef = useRef<string | null>(null);
-
-  const reload = useCallback(() => setReloadKey((k) => k + 1), []);
-
-  useEffect(() => {
-    if (!projectId) return;
-    let cancelled = false;
-    if (lastProjectRef.current !== projectId) {
-      lastProjectRef.current = projectId;
-      hasDataRef.current = false;
-      setData(null);
-    }
-    if (!hasDataRef.current) setLoading(true);
-    setError(null);
-
-    // Route through buildProjectApiPath so the (URL-derived) projectId is encoded
-    // into the path rather than interpolated raw (CodeQL js/client-side-request-forgery).
-    fetch(buildProjectApiPath(projectId, "/storyboard"))
-      .then((res) => {
-        if (!res.ok) throw new Error(`storyboard request failed: ${res.status}`);
-        return res.json() as Promise<StoryboardResponse>;
-      })
-      .then((json) => {
-        if (cancelled) return;
-        hasDataRef.current = true;
-        setData(json);
-      })
-      .catch((err: unknown) => {
-        if (cancelled) return;
-        // A failed background refresh keeps the last good board on screen;
-        // the blocking error state is only for loads with nothing to show.
-        if (hasDataRef.current) return;
-        setError(err instanceof Error ? err.message : "failed to load storyboard");
-      })
-      .finally(() => {
-        if (!cancelled) setLoading(false);
-      });
-
-    return () => {
-      cancelled = true;
-    };
-  }, [projectId, reloadKey]);
-
-  return { data, loading, error, reload };
-}

package/src/utils/fitPanels.test.ts

@@ -1,164 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  MIN_PREVIEW_H,
-  MIN_PREVIEW_W,
-  MIN_TIMELINE_H,
-  RAIL_W,
-  defaultPanelWidths,
-  fitPanelWidths,
-  fitTimelineHeight,
-} from "./fitPanels";
-
-function fitAt(viewportWidth: number) {
-  return fitPanelWidths(viewportWidth, defaultPanelWidths(viewportWidth));
-}
-
-describe("defaultPanelWidths", () => {
-  // Frozen literals, deliberately NOT compared against the live hook: the hook
-  // now delegates here, so asserting against it would be circular and would
-  // silently stop guarding the "wide windows are untouched" promise.
-  it.each([
-    [1680, 384, 424],
-    [1512, 384, 424],
-    [1280, 329, 364],
-  ])("keeps %ipx identical to the pre-change defaults", (vw, left, right) => {
-    expect(defaultPanelWidths(vw)).toEqual({ left, right });
-  });
-});
-
-describe("fitPanelWidths", () => {
-  it.each([1680, 1512, 1280])("leaves %ipx untouched by reconciliation", (vw) => {
-    const preferred = defaultPanelWidths(vw);
-    const fitted = fitPanelWidths(vw, preferred);
-    expect(fitted.left).toBe(preferred.left);
-    expect(fitted.right).toBe(preferred.right);
-    expect(fitted.autoCollapseLeft).toBe(false);
-    expect(fitted.autoCollapseRight).toBe(false);
-  });
-
-  it.each([1680, 1512, 1280, 1100, 960, 860, 760, 640, 560, 480])(
-    "never starves the preview at %ipx",
-    (vw) => {
-      expect(fitAt(vw).preview).toBeGreaterThanOrEqual(MIN_PREVIEW_W);
-    },
-  );
-
-  it("matches the projected preview widths from the plan", () => {
-    const projected: Array<[number, number]> = [
-      [1680, 866],
-      [1512, 698],
-      [1280, 581],
-      [1100, 499],
-      [960, 427],
-      [860, 360],
-      [760, 432],
-      [640, 592],
-      [560, 512],
-      [480, 432],
-    ];
-    for (const [vw, preview] of projected) {
-      expect({ vw, preview: fitAt(vw).preview }).toEqual({ vw, preview });
-    }
-  });
-
-  it("fits everything at its minimum at exactly 860, the derived threshold", () => {
-    const fitted = fitAt(860);
-    expect(fitted).toMatchObject({
-      left: 214,
-      right: 280,
-      preview: MIN_PREVIEW_W,
-      autoCollapseLeft: false,
-    });
-  });
-
-  it("rails the sidebar one pixel below the threshold", () => {
-    expect(fitAt(860).autoCollapseLeft).toBe(false);
-    expect(fitAt(859).autoCollapseLeft).toBe(true);
-    expect(fitAt(859).left).toBe(RAIL_W);
-  });
-
-  it("hides the inspector one pixel below its own threshold", () => {
-    expect(fitAt(700).autoCollapseRight).toBe(false);
-    expect(fitAt(700).right).toBeGreaterThan(0);
-    expect(fitAt(699).autoCollapseRight).toBe(true);
-    expect(fitAt(699).right).toBe(0);
-  });
-
-  it("never drives an EXPANDED sidebar below its usable minimum", () => {
-    // Guards the leftFloor/rightFloor split: the squeeze fallback may only reach
-    // the rail width when the panel is actually railed.
-    const fitted = fitPanelWidths(900, { left: 600, right: 600 });
-    expect(fitted.left).toBeGreaterThanOrEqual(200);
-    expect(fitted.right).toBeGreaterThanOrEqual(280);
-  });
-
-  it("caps a single panel at 40% of the window", () => {
-    expect(fitPanelWidths(1600, { left: 900, right: 280 }).left).toBe(640);
-  });
-
-  it("lets the preview floor win when the cap alone is not enough", () => {
-    // 40% of 1000 is 400, but 400 + 280 + 6 leaves the preview at 314.
-    const fitted = fitPanelWidths(1000, { left: 900, right: 280 });
-    expect(fitted.left).toBe(354);
-    expect(fitted.preview).toBe(MIN_PREVIEW_W);
-  });
-
-  it("survives a viewport narrower than the preview floor alone", () => {
-    const fitted = fitAt(300);
-    expect(fitted.preview).toBeGreaterThanOrEqual(0);
-    expect(Number.isNaN(fitted.preview)).toBe(false);
-    expect(fitted.left).toBe(RAIL_W);
-  });
-
-  it("returns preferences untouched before the shell is measured", () => {
-    const preferred = { left: 320, right: 400 };
-    expect(fitPanelWidths(0, preferred)).toMatchObject({ ...preferred, preview: 0 });
-    expect(fitPanelWidths(Number.NaN, preferred)).toMatchObject(preferred);
-  });
-
-  it("is idempotent, so a resize loop cannot oscillate", () => {
-    for (const vw of [1512, 1100, 860, 760, 560]) {
-      const once = fitPanelWidths(vw, defaultPanelWidths(vw));
-      const twice = fitPanelWidths(vw, once);
-      expect(twice).toEqual(once);
-    }
-  });
-});
-
-describe("fitTimelineHeight", () => {
-  it("keeps a height that fits", () => {
-    expect(fitTimelineHeight(717, 429)).toBe(429);
-  });
-
-  it("reclaims height for the preview when the shell shrinks", () => {
-    // The measured bug: mounted at 760 tall, dragged to 520. Preview was 47px.
-    expect(fitTimelineHeight(477, 429)).toBe(477 - MIN_PREVIEW_H);
-    expect(477 - fitTimelineHeight(477, 429)).toBeGreaterThanOrEqual(MIN_PREVIEW_H);
-  });
-
-  it("raises a too-small preference to the timeline minimum", () => {
-    expect(fitTimelineHeight(717, 10)).toBe(MIN_TIMELINE_H);
-  });
-
-  it("keeps the timeline usable when the shell is shorter than both minimums", () => {
-    expect(fitTimelineHeight(120, 429)).toBe(MIN_TIMELINE_H);
-  });
-
-  it("returns the preference before the shell is measured", () => {
-    expect(fitTimelineHeight(0, 429)).toBe(429);
-  });
-
-  it("is idempotent", () => {
-    const once = fitTimelineHeight(477, 429);
-    expect(fitTimelineHeight(477, once)).toBe(once);
-  });
-
-  it("would return the preferred height if callers kept one", () => {
-    // The helper is preference-preserving; the vertical CALLER still stores the
-    // clamped value, so a shrink-then-grow does not restore the old height the
-    // way panel widths do. Tracked as a known asymmetry, not fixed here.
-    const preferred = 429;
-    expect(fitTimelineHeight(477, preferred)).toBe(277);
-    expect(fitTimelineHeight(717, preferred)).toBe(429);
-  });
-});

package/src/utils/fitPanels.ts

@@ -1,151 +0,0 @@
-/**
- * Panel reconciliation for the Studio shell.
- *
- * The shell is `[sidebar | preview | inspector]` over a full-width timeline.
- * Only the preview is flexible (`flex-1 min-w-0`), so without an explicit floor
- * it absorbs every squeeze: at a 560px window the old 240/320 panel floors alone
- * overflowed the viewport and the preview rendered at 2px, on a *fresh* load.
- * The same held vertically once the window was resized after mount.
- *
- * Every caller (mount, resize, drag, keyboard nudge, preference restore) routes
- * through {@link fitPanelWidths} / {@link fitTimelineHeight} so exactly one place
- * decides who yields. The rule is: the preview gets its floor first, panels
- * shrink toward their minimums, then collapse to rails.
- */
-
-/** Smallest preview box worth editing in. Chosen, not derived — see the plan. */
-export const MIN_PREVIEW_W = 360;
-export const MIN_PREVIEW_H = 200;
-
-const MIN_LEFT = 200;
-const MIN_RIGHT = 280;
-/**
- * Collapsed sidebar rail, as a layout FOOTPRINT: the `w-10` box (40) plus the
- * `mr-0.5` gap (2) it contributes to the flex row. Measured in the browser at a
- * 760px window: rail box 40, margin-right 2, preview starts at x=43.
- */
-export const RAIL_W = 42;
-export const MIN_TIMELINE_H = 100;
-
-/** The two 3px resize seams between the three top-row panels. */
-const PANEL_SEAM_W = 6;
-
-/** No single panel may claim more than this share of the window. */
-const PANEL_MAX_RATIO = 0.4;
-
-/*
- * Thresholds below are DERIVED from the minimums above, not chosen:
- *
- *   MIN_LEFT 200 + MIN_RIGHT 280 + MIN_PREVIEW_W 360 + PANEL_SEAM_W 6 = 846
- *     -> below ~860 the sidebar can no longer fit at its minimum.
- *   RAIL_W  40 + MIN_RIGHT 280 + MIN_PREVIEW_W 360 + PANEL_SEAM_W 6 = 686
- *     -> below ~700 the inspector can no longer fit either.
- *
- * Change a minimum and move the matching threshold with it.
- */
-const RAIL_LEFT_BELOW = 860;
-const RAIL_RIGHT_BELOW = 700;
-
-/**
- * True when the window is narrow enough to force at least one panel to a rail.
- * The sidebar threshold is the wider of the two, so it is the whole condition.
- */
-export function railsEngaged(viewportWidth: number): boolean {
-  return viewportWidth < RAIL_LEFT_BELOW;
-}
-
-export interface PanelWidths {
-  left: number;
-  right: number;
-}
-
-export interface FittedPanelWidths extends PanelWidths {
-  preview: number;
-  /**
-   * Width-driven collapse. Derived per render; NEVER persisted and never written
-   * back to the user's own collapse preference — `leftCollapsed` lives in
-   * localStorage and `rightCollapsed` is synced into the shareable Studio URL,
-   * so a ten-second window drag must not rewrite either.
-   */
-  autoCollapseLeft: boolean;
-  autoCollapseRight: boolean;
-}
-
-function clamp(value: number, min: number, max: number): number {
-  return Math.max(min, Math.min(max, value));
-}
-
-/**
- * The width each panel wants on a given viewport, before reconciliation.
- * Upper bounds (384 / 424) are unchanged from the original implementation, which
- * is what keeps windows at or above 1280px byte-identical to before.
- */
-export function defaultPanelWidths(viewportWidth: number): PanelWidths {
-  return {
-    left: Math.max(MIN_LEFT, Math.min(384, Math.round(viewportWidth * 0.257))),
-    right: Math.max(MIN_RIGHT, Math.min(424, Math.round(viewportWidth * 0.284))),
-  };
-}
-
-/**
- * Resolve preferred panel widths against the viewport, reserving the preview.
- *
- * Order of yielding: window-relative cap, then the inspector shrinks toward its
- * minimum, then the sidebar, then rails. A viewport of 0 (element not measured
- * yet) returns the preferences untouched so a pre-measurement frame cannot
- * clobber a real preference.
- */
-// fallow-ignore-next-line complexity
-export function fitPanelWidths(
-  viewportWidth: number,
-  preferred: PanelWidths,
-  /**
-   * Sides the user explicitly reopened while the window was narrow. A side
-   * listed here keeps its real width instead of the rail: without this the
-   * panel would render expanded at 42px and squash its own content.
-   */
-  reopened: { left: boolean; right: boolean } = { left: false, right: false },
-): FittedPanelWidths {
-  const vw = Number.isFinite(viewportWidth) ? Math.max(0, viewportWidth) : 0;
-  if (vw <= 0) {
-    return { ...preferred, preview: 0, autoCollapseLeft: false, autoCollapseRight: false };
-  }
-
-  const autoCollapseLeft = vw < RAIL_LEFT_BELOW && !reopened.left;
-  const autoCollapseRight = vw < RAIL_RIGHT_BELOW && !reopened.right;
-  const cap = Math.floor(vw * PANEL_MAX_RATIO);
-
-  // A railed panel's floor is its rail width; an open panel's floor is its
-  // minimum usable width. Without this split the squeeze fallback below would
-  // drive an *expanded* sidebar down to 40px and render its content unusable.
-  const leftFloor = autoCollapseLeft ? RAIL_W : MIN_LEFT;
-  const rightFloor = autoCollapseRight ? 0 : MIN_RIGHT;
-
-  let left = autoCollapseLeft ? RAIL_W : clamp(preferred.left, MIN_LEFT, Math.max(MIN_LEFT, cap));
-  let right = autoCollapseRight ? 0 : clamp(preferred.right, MIN_RIGHT, Math.max(MIN_RIGHT, cap));
-
-  const budget = vw - MIN_PREVIEW_W - PANEL_SEAM_W;
-  if (left + right > budget) right = Math.max(rightFloor, budget - left);
-  if (left + right > budget) left = Math.max(leftFloor, budget - right);
-
-  return {
-    left,
-    right,
-    preview: Math.max(0, vw - left - right - PANEL_SEAM_W),
-    autoCollapseLeft,
-    autoCollapseRight,
-  };
-}
-
-/**
- * Resolve a preferred timeline height against the shell's measured height.
- *
- * Subsumes the clamping that used to be inlined in TimelineResizeDivider's
- * pointer and keyboard handlers and duplicated (mount-only) in NLEContext.
- */
-export function fitTimelineHeight(containerHeight: number, preferred: number): number {
-  const h = Number.isFinite(containerHeight) ? containerHeight : 0;
-  const wanted = Number.isFinite(preferred) ? preferred : MIN_TIMELINE_H;
-  if (h <= 0) return Math.max(MIN_TIMELINE_H, wanted);
-  return clamp(wanted, MIN_TIMELINE_H, Math.max(MIN_TIMELINE_H, h - MIN_PREVIEW_H));
-}