Skip to content

The open-source full-stack studio for Opus 5.5 motion video. Reverse engineering for any video. Code video with HTML: recreate, edit and render. BYOA + BYOK · Motion.md · Images, Video, Music & Voice.

7.5 KB
Raw Blame
import { useEffect, useState } from "react";
import { buildProjectHash, parseProjectIdFromHash } from "../utils/projectRouting";
import { useMountEffect } from "./useMountEffect";
import { trackStudioEvent } from "../utils/studioTelemetry";
import { studioApiFetch } from "../utils/studioApiFetch";

interface ServerConnectionState {
  projectId: string | null;
  resolving: boolean;
  waitingForServer: boolean;
}

/**
 * Resolves the active project ID by pinging /api/projects.
 *
 * If the hash contains a project ID the server is still contacted — this
 * ensures a dead server (bookmark-reload case) enters the waiting state
 * rather than mounting the full Studio against a non-responsive API.
 *
 * Polls every 2 s until the server responds, then transitions automatically.
 * Cleans up pending timers on unmount so it is safe under React StrictMode.
 */
/**
 * Whether a hash-supplied project id still names something the server can
 * resolve. Three answers, not two: a failed request must NOT be read as
 * "missing", or one network blip would discard a perfectly good deep link.
 *
 * Resolved through `/api/projects/:id`, which calls the same
 * `adapter.resolveProject` the file routes use. A match against the
 * `/api/projects` list would be wrong twice over: that list omits session ids
 * (which resolve fine) and skips project dirs without an `index.html`.
 */
type ProjectHashVerdict = {
  outcome: "ok" | "missing" | "unknown";
  /** HTTP status when the server answered; absent on a rejected request. */
  status?: number;
};

async function resolveHashProject(id: string): Promise<ProjectHashVerdict> {
  try {
    const res = await studioApiFetch(`/api/projects/${encodeURIComponent(id)}`);
    if (res.ok) return { outcome: "ok", status: res.status };
    return { outcome: res.status === 404 ? "missing" : "unknown", status: res.status };
  } catch {
    return { outcome: "unknown" };
  }
}

/**
 * What the hash validation decided. Without this, a tab that kept a hash
 * because the check itself failed ("unknown") is indistinguishable from one
 * that never ran the check — the two have different fixes and, until this
 * event, no way to tell them apart in production.
 */
/**
 * Rewrite the project hash WITHOUT pushing a history entry.
 *
 * `location.hash =` pushes. That leaves the dead id as the previous entry, so
 * Back returns to it — and now that hashchange validates, Back would re-run the
 * whole fallback and push again, leaving a trail of dead ids the user cannot
 * escape with the Back button.
 */
function replaceProjectHash(projectId: string): void {
  window.history.replaceState(null, "", buildProjectHash(projectId));
}

/**
 * The first project the server offers, for a hash that resolves to nothing.
 *
 * Fetched here rather than cached from mount: the mount fetch is a snapshot,
 * and the scenario this exists for is exactly the one where the project list
 * changed underneath a long-lived tab.
 */
async function firstProjectId(): Promise<string | null> {
  try {
    const res = await studioApiFetch("/api/projects");
    const data = (await res.json()) as { projects?: Array<{ id?: string }> };
    return data.projects?.[0]?.id ?? null;
  } catch {
    return null;
  }
}

function reportHashVerdict(stage: "mount" | "hashchange", verdict: ProjectHashVerdict): void {
  trackStudioEvent("project_hash_validated", {
    stage,
    outcome: verdict.outcome,
    ...(verdict.status === undefined ? {} : { status: verdict.status }),
  });
}

export function useServerConnection(): ServerConnectionState {
  const [projectId, setProjectId] = useState<string | null>(null);
  const [resolving, setResolving] = useState(true);
  const [waitingForServer, setWaitingForServer] = useState(false);

  useMountEffect(() => {
    const hashProjectId = parseProjectIdFromHash(window.location.hash);
    let cancelled = false;
    // Explicitly `number` (the DOM return of window.setTimeout) rather than
    // ReturnType<typeof window.setTimeout> — with @types/node present, that infers
    // NodeJS.Timeout and clashes with the DOM number the call actually returns.
    let retryTimer: number | null = null;

    function scheduleRetry() {
      setWaitingForServer(true);
      retryTimer = window.setTimeout(tryConnect, 2000);
    }

    function tryConnect() {
      studioApiFetch("/api/projects")
        .then((r) => r.json())
        .then(async (data) => {
          if (cancelled) return;
          // A hash project id outlives the project it names — a renamed folder,
          // or a bookmark from a project that is gone. Trusting it blindly made
          // every later /api/projects/<id>/... request 404 for the life of the
          // tab, including the composition read that opens the SDK session, so
          // every edit fell back to the server path with nothing to show why.
          // Telemetry after the read-reason split: 120 http_error/404 reads
          // across 5 users in 24h, ~24 each, never recovering.
          if (hashProjectId) {
            const verdict = await resolveHashProject(hashProjectId);
            if (cancelled) return;
            reportHashVerdict("mount", verdict);
            // "unknown" keeps the old behaviour: a transient failure must not
            // rewrite the user's hash out from under a valid project.
            if (verdict.outcome !== "missing") {
              setProjectId(hashProjectId);
              setWaitingForServer(false);
              return;
            }
          }
          const first = (data.projects ?? [])[0];
          if (first) {
            setProjectId(first.id);
            setWaitingForServer(false);
            replaceProjectHash(first.id);
          } else {
            scheduleRetry();
          }
        })
        .catch(() => {
          if (!cancelled) scheduleRetry();
        })
        .finally(() => {
          if (!cancelled) setResolving(false);
        });
    }

    tryConnect();
    return () => {
      cancelled = true;
      if (retryTimer !== null) clearTimeout(retryTimer);
    };
  });

  // eslint-disable-next-line no-restricted-syntax
  useEffect(() => {
    const onHashChange = () => {
      const next = parseProjectIdFromHash(window.location.hash);
      if (!next || next === projectId) return;
      // Validated, not adopted. The mount path has checked its hash since
      // v0.8.52; this path took any id the URL offered, so changing projects
      // re-armed the same dead-tab failure the mount check exists to prevent.
      void (async () => {
        const verdict = await resolveHashProject(next);
        // Ground truth, not a captured flag. This effect re-registers on every
        // projectId change, so a generation counter in this closure would reset
        // and an in-flight verdict from the previous registration would read as
        // current — adopting a project the user has already navigated away from.
        // The hash itself cannot go stale.
        if (parseProjectIdFromHash(window.location.hash) !== next) return;
        reportHashVerdict("hashchange", verdict);
        if (verdict.outcome !== "missing") {
          setProjectId(next);
          return;
        }
        const fallbackId = await firstProjectId();
        if (parseProjectIdFromHash(window.location.hash) !== next) return;
        if (!fallbackId) return;
        setProjectId(fallbackId);
        replaceProjectHash(fallbackId);
      })();
    };
    window.addEventListener("hashchange", onHashChange);
    return () => window.removeEventListener("hashchange", onHashChange);
  }, [projectId]);

  return { projectId, resolving, waitingForServer };
}