Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

17.6 KB
Raw Blame
"use client";

import { readingCollectionRoute, readingSessionRoute } from "@/lib/learning-routes";

import { useRouter } from "next/navigation";
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { useTranslation } from "react-i18next";

import { useReading } from "@/context/ReadingContext";
import { useChatStateAdapter } from "@/features/chat/ChatStateAdapter";
import {
  addBookmark,
  deleteBookmark,
  getReadingTranscript,
  listBookmarks,
  type ReadingBookmark,
} from "@/lib/reading-api";
import {
  READER_ACTION_EVENT,
  type ReaderActionPayload,
} from "@/lib/reading-reader-action";
import { setReadingWorkspace } from "@/lib/reading-turn-state";
import { READING_WORKSPACE_MODE } from "@/lib/workspace-mode";
import {
  activateReadingMaterial,
  generateMasteryPathFromReading,
  getReadingWorkspace,
  listReadingConversations,
  organizeReadingNotes,
  removeReadingWorkspaceMaterial,
  updateReadingWorkspace,
  type OrganizedReadingNotes,
  type ReadingConversation,
  type ReadingLibraryMaterial,
  type ReadingWorkspace,
} from "@/lib/reading-workspace-api";
import type { TranscriptRow } from "./types";

/**
 * Everything the reading workspace needs from the network, in one place.
 *
 * The page component owns only what the reader touches directly — selection,
 * composer text, which panels are open. Hydration, polling, conversation
 * bootstrapping and the source lifecycle live here so the view stays readable
 * and each effect has one obvious owner.
 */
/** Stable empty list, so a material with no bookmarks is not a new array
 *  identity on every render. */
const NO_BOOKMARKS: ReadingBookmark[] = [];

export function useReadingWorkspace(
  workspaceId: string,
  sessionIdParam: string | null,
) {
  const router = useRouter();
  const { t } = useTranslation();
  const { material, annotations, openMaterial, closeMaterial, reportViewport } =
    useReading();
  const {
    state,
    configureSession,
    loadSession,
    newSession,
  } = useChatStateAdapter();

  const [workspace, setWorkspace] = useState<ReadingWorkspace | null>(null);
  const [conversations, setConversations] = useState<ReadingConversation[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState("");
  const [notice, setNotice] = useState("");
  const [activeLocator, setActiveLocator] = useState(1);
  const [transcript, setTranscript] = useState<TranscriptRow[]>([]);
  const [organizedNotes, setOrganizedNotes] =
    useState<OrganizedReadingNotes | null>(null);
  const sessionBootRef = useRef("");
  const transcriptRequestRef = useRef(0);

  const refreshConversations = useCallback(async () => {
    const result = await listReadingConversations(workspaceId);
    setConversations(result);
    return result;
  }, [workspaceId]);

  const refresh = useCallback(async () => {
    const result = await getReadingWorkspace(workspaceId);
    const sessionRows = await refreshConversations();
    setWorkspace(result.workspace);
    setConversations(sessionRows);
    return { workspace: result.workspace, sessions: sessionRows };
  }, [workspaceId, refreshConversations]);

  useEffect(() => {
    let cancelled = false;
    // The async refresh owns the initial network hydration for this route.
    // eslint-disable-next-line react-hooks/set-state-in-effect
    void refresh()
      .catch((caught) => {
        if (!cancelled)
          setError(
            caught instanceof Error
              ? caught.message
              : t("This collection could not be opened."),
          );
      })
      .finally(() => {
        if (!cancelled) setLoading(false);
      });
    return () => {
      cancelled = true;
    };
  }, [refresh, t]);

  useEffect(() => {
    setReadingWorkspace(workspaceId);
    return () => {
      setReadingWorkspace(null);
      closeMaterial();
    };
  }, [closeMaterial, workspaceId]);

  const sessionConfiguration = useMemo(
    () => ({ workspaceMode: READING_WORKSPACE_MODE }),
    [],
  );

  const activeTab = useMemo(
    () =>
      workspace?.tabs.find(
        (tab) => tab.material.material_id === workspace.active_material_id,
      ) ??
      workspace?.tabs[0] ??
      null,
    [workspace],
  );

  useEffect(() => {
    const active = activeTab?.material;
    if (!active || active.status !== "ready") {
      closeMaterial();
      return;
    }
    // Let ReadingContext own the request from its first tick. Prefetching the
    // detail here left `loading` false until that fetch completed, so the
    // reader briefly rendered its unavailable state between workspace and
    // material hydration (most visibly in Safari).
    void openMaterial(active.material_id);
  }, [activeTab?.material, closeMaterial, openMaterial]);

  // Poll while anything is still being processed, backing off as the wait
  // grows. A flat 2.5s forever means a source wedged in "processing" quietly
  // hammers the API for as long as the tab stays open.
  useEffect(() => {
    if (
      !workspace?.tabs.some(
        (tab) =>
          tab.material.status === "processing" ||
          tab.material.status === "queued",
      )
    )
      return;
    let attempt = 0;
    let timer = 0;
    const tick = () => {
      attempt += 1;
      void refresh().finally(() => {
        timer = window.setTimeout(
          tick,
          Math.min(2500 * 2 ** Math.floor(attempt / 4), 30_000),
        );
      });
    };
    timer = window.setTimeout(tick, 2500);
    return () => window.clearTimeout(timer);
  }, [refresh, workspace]);

  useEffect(() => {
    if (!workspace || loading) return;
    const bootKey = `${workspaceId}:${sessionIdParam ?? "new"}`;
    if (sessionBootRef.current === bootKey) return;
    sessionBootRef.current = bootKey;

    // The URL catching up with the session the first turn just created is not
    // a request to open a different conversation — the transcript on screen
    // already IS that conversation. Reloading it here would swap a streaming
    // answer for whatever partial row the backend has written so far.
    if (sessionIdParam && sessionIdParam === state.sessionId) return;

    void (async () => {
      try {
        // The URL is the truth about which conversation is open, the same
        // rule /chat follows: `/reading/<ws>/sessions/<id>` opens that conversation,
        // `/reading/<ws>` is a *new* one. This used to reopen the most recent
        // conversation instead, so arriving from the library — which links to
        // the bare collection URL — dropped the reader into an old transcript
        // they had not asked for.
        //
        // A conversation with nothing in it is a local draft, never a row:
        // the backend attaches the session to this workspace when the first
        // turn runs (see `turn_runtime`), so opening a collection and walking
        // away no longer litters it with empty conversations.
        if (sessionIdParam) {
          await loadSession(sessionIdParam);
          configureSession(sessionConfiguration, sessionIdParam);
        } else {
          newSession({ ...sessionConfiguration, capability: null });
        }
      } catch (caught) {
        setError(
          caught instanceof Error
            ? caught.message
            : t("The reading conversation could not be loaded."),
        );
      }
    })();
  }, [
    configureSession,
    loadSession,
    loading,
    newSession,
    sessionIdParam,
    sessionConfiguration,
    state.sessionId,
    t,
    workspace,
    workspaceId,
  ]);

  useEffect(() => {
    if (!material || material.unit !== "segment") return;
    const requestId = ++transcriptRequestRef.current;
    // One request for the whole transcript. Segments follow the speaker's
    // sentences, so a lecture has hundreds of them and fetching each on its own
    // meant hundreds of round trips before the panel could draw anything.
    void getReadingTranscript(material.material_id)
      .then((payload) => {
        if (transcriptRequestRef.current !== requestId) return;
        const rows: TranscriptRow[] = payload.segments
          .filter(
            (row) => row.text !== "[Transcript unavailable for this video.]",
          )
          .map((row) => ({
            locator: row.locator,
            title: row.title || `${row.locator}`,
            text: row.text,
            sourceHref: row.source_href,
          }));
        setTranscript(rows);
      })
      .catch(() => {
        if (transcriptRequestRef.current !== requestId) return;
        setTranscript([]);
        setNotice(t("This transcript could not be loaded."));
      });
  }, [material, t]);

  const activeConversation = useMemo(
    () =>
      conversations.find((row) => row.session_id === state.sessionId) ??
      conversations.find((row) => row.session_id === sessionIdParam) ??
      null,
    [conversations, sessionIdParam, state.sessionId],
  );

  const linkedSessionIds = useMemo(
    () => activeConversation?.linked_session_ids ?? [],
    [activeConversation],
  );

  /* ── Bookmarks ────────────────────────────────────────────────────────
     Kept here rather than inside the reader because two surfaces read them:
     the reader's own toolbar (is *this* page kept?) and the outline panel
     (the list, and jumping to one). Two copies would drift the moment either
     one added a bookmark. */
  const materialId = material?.material_id ?? "";
  const [loadedBookmarks, setLoadedBookmarks] = useState<{
    materialId: string;
    rows: ReadingBookmark[];
  }>({ materialId: "", rows: [] });
  // Derived rather than stored: switching material has to drop the previous
  // one's bookmarks in the same render it switches, and an effect that called
  // setState to clear them would both show the wrong list for a frame and
  // trip the compiler's set-state-in-effect rule.
  const bookmarks =
    loadedBookmarks.materialId === materialId
      ? loadedBookmarks.rows
      : NO_BOOKMARKS;

  useEffect(() => {
    if (!materialId) return;
    let cancelled = false;
    void listBookmarks(materialId)
      .then((rows) => {
        if (!cancelled) setLoadedBookmarks({ materialId, rows });
      })
      .catch(() => {
        if (!cancelled) setLoadedBookmarks({ materialId, rows: [] });
      });
    return () => {
      cancelled = true;
    };
  }, [materialId]);

  // One control, both directions: the toolbar button reads "is this page
  // kept?" off the same list it writes to, so pressing it again removes what
  // the last press added.
  const toggleBookmark = useCallback(
    async (locator: number, label = "") => {
      if (!materialId) return;
      const existing = bookmarks.find((row) => row.locator === locator);
      try {
        if (existing) {
          await deleteBookmark(materialId, existing.bookmark_id);
        } else {
          await addBookmark(materialId, locator, label);
        }
        setLoadedBookmarks({
          materialId,
          rows: await listBookmarks(materialId),
        });
      } catch (caught) {
        setNotice(
          caught instanceof Error
            ? caught.message
            : t("That bookmark could not be saved."),
        );
      }
    },
    [bookmarks, materialId, t],
  );

  const removeBookmark = useCallback(
    async (bookmarkId: string) => {
      if (!materialId) return;
      try {
        await deleteBookmark(materialId, bookmarkId);
        setLoadedBookmarks({
          materialId,
          rows: await listBookmarks(materialId),
        });
      } catch (caught) {
        setNotice(
          caught instanceof Error
            ? caught.message
            : t("That bookmark could not be removed."),
        );
      }
    },
    [materialId, t],
  );

  const switchMaterial = useCallback(
    async (candidate: ReadingLibraryMaterial) => {
      if (!workspace || candidate.material_id === workspace.active_material_id)
        return;
      try {
        const updated = await activateReadingMaterial(
          workspace.workspace_id,
          candidate.material_id,
        );
        setWorkspace(updated);
        setActiveLocator(1);
        reportViewport({ locator: 1, selection: "" });
      } catch (caught) {
        // Without this the tab click is a no-op with no explanation, which is
        // indistinguishable from the click not registering at all.
        setNotice(
          caught instanceof Error
            ? caught.message
            : t("This material could not be opened."),
        );
      }
    },
    [reportViewport, t, workspace],
  );

  useEffect(() => {
    const onReaderAction = (event: Event) => {
      const detail = (event as CustomEvent<ReaderActionPayload>).detail;
      if (detail?.reader_action !== "switch_tab" || !detail.material_id) return;
      const candidate = workspace?.tabs.find(
        (tab) => tab.material.material_id === detail.material_id,
      )?.material;
      if (candidate) void switchMaterial(candidate);
    };
    window.addEventListener(READER_ACTION_EVENT, onReaderAction);
    return () =>
      window.removeEventListener(READER_ACTION_EVENT, onReaderAction);
  }, [switchMaterial, workspace?.tabs]);

  const removeMaterial = useCallback(
    async (candidate: ReadingLibraryMaterial) => {
      if (!workspace) return;
      setWorkspace(
        await removeReadingWorkspaceMaterial(
          workspace.workspace_id,
          candidate.material_id,
        ),
      );
    },
    [workspace],
  );

  // The same gesture /chat's "new chat" makes: reset to a local draft and
  // navigate to the URL that *means* "new". No row is written until the
  // learner actually says something, and the title is then the one the model
  // writes from that first turn rather than a placeholder every conversation
  // shares.
  //
  // Deliberately does not cancel the streaming turn. It used to, copying
  // /chat — and copying its bug: the turn being cancelled belongs to the
  // conversation being navigated *away* from, so starting a new one killed
  // the previous answer mid-flight.
  const newConversation = useCallback(() => {
    if (!workspace) return;
    newSession({ ...sessionConfiguration, capability: null });
    router.push(readingCollectionRoute(workspace.workspace_id));
  }, [
    newSession,
    router,
    sessionConfiguration,
    workspace,
  ]);

  // When the first turn assigns a session id, put it in the URL and let the
  // conversation menu see the row the backend just attached. Without it a
  // draft conversation would stay on the bare collection URL and a refresh
  // would silently start over.
  //
  // The URL is written with the native history API rather than `router.replace`
  // on purpose. `/reading/<ws>` and `/reading/<ws>/sessions/<id>` are different
  // route matches, and App Router treats moving between them — even within one
  // catch-all segment, which was tried — as a navigation: it unmounted the
  // whole workspace and mounted it again mid-answer. Measured, that meant the
  // reader's subtree left the DOM, "Opening collection…" painted for a frame,
  // the material was re-fetched and the page the learner was on reset to 1.
  // Asking the first question of a conversation blinked the entire screen.
  //
  // Nothing about that navigation was real: the learner stayed exactly where
  // they were and the conversation they are watching stream is the one being
  // named. So the address bar is corrected in place and `usePathname` — which
  // does follow the native API — keeps `sessionIdParam` honest for refreshes,
  // links and the back button.
  useEffect(() => {
    if (!state.sessionId || sessionIdParam) return;
    window.history.replaceState(
      null,
      "",
      readingSessionRoute(workspaceId, state.sessionId),
    );
    void listReadingConversations(workspaceId)
      .then(setConversations)
      .catch(() => {});
  }, [sessionIdParam, state.sessionId, workspaceId]);

  const organizeNotes = useCallback(async () => {
    if (!workspace) return;
    try {
      setNotice(t("Organizing notes…"));
      const notes = await organizeReadingNotes(workspace.workspace_id);
      setOrganizedNotes(notes);
      setNotice(t("Notes organized, each one citing where it came from."));
    } catch (caught) {
      setNotice(
        caught instanceof Error
          ? caught.message
          : t("Could not organize notes."),
      );
    }
  }, [t, workspace]);

  const buildMasteryPath = useCallback(
    async (bookId: string) => {
      if (!workspace) return;
      try {
        setNotice(t("Building Mastery Path…"));
        await generateMasteryPathFromReading(
          workspace.workspace_id,
          bookId.trim(),
        );
        setNotice(t("Mastery Path created. Open Learning Space to begin."));
      } catch (caught) {
        setNotice(
          caught instanceof Error
            ? caught.message
            : t("Mastery Path creation failed."),
        );
        throw caught;
      }
    },
    [t, workspace],
  );

  const renameWorkspace = useCallback(
    async (title: string) => {
      if (!workspace) return;
      if (!title?.trim() || title.trim() === workspace.title) return;
      setWorkspace(
        await updateReadingWorkspace(workspace.workspace_id, {
          title: title.trim(),
        }),
      );
    },
    [workspace],
  );

  return {
    workspace,
    setWorkspace,
    conversations,
    setConversations,
    loading,
    error,
    notice,
    refreshConversations,
    setNotice,
    material,
    annotations,
    activeTab,
    activeConversation,
    linkedSessionIds,
    activeLocator,
    setActiveLocator,
    bookmarks,
    toggleBookmark,
    removeBookmark,
    transcript,
    organizedNotes,
    setOrganizedNotes,
    refresh,
    switchMaterial,
    removeMaterial,
    newConversation,
    organizeNotes,
    buildMasteryPath,
    renameWorkspace,
    reportViewport,
  };
}