@anthusai/papyrus 1.0.0-next.4 → 1.0.0-next.40

package/components/presentation-rhythm-hrule.tsx

@@ -0,0 +1,17 @@
+type PresentationRhythmHRuleProps = {
+  /** Hide in wide 2-column secondary pairs (items 1+2 side-by-side). */
+  hideInSecondaryPair?: boolean;
+};
+
+export function PresentationRhythmHRule({ hideInSecondaryPair = false }: PresentationRhythmHRuleProps) {
+  return (
+    <div
+      aria-hidden="true"
+      className="presentation-rhythm-hrule"
+      data-hide-in-secondary-pair={hideInSecondaryPair ? "true" : undefined}
+      role="presentation"
+    >
+      <div className="presentation-rhythm-hrule__line" />
+    </div>
+  );
+}

package/components/reference-cyclotron-status.tsx

@@ -0,0 +1,109 @@
+"use client";
+
+import { useState } from "react";
+import { CyclotronStatusView } from "cyclotron/components/cyclotron-status";
+import type { CyclotronStatus } from "cyclotron/cyclotron-status";
+
+const RATE_CHOICES = [1, 0.5, 0.25, 0.1, 0];
+const DAY_CHOICES = [1, 7, 14, 30];
+
+export type ReviewRateChoice = { rate: number; days: number } | { clear: true };
+
+/**
+ * The relevance cyclotron's status above the References list: a strip, the
+ * detail card on demand, and, for editors who may change it, a form that asks
+ * the next sweep for a manual review rate.
+ */
+export function ReferenceCyclotronStatus({
+  onRequestRate,
+  status,
+  staleAfterHours = 24,
+  now = new Date(),
+}: {
+  onRequestRate?: (choice: ReviewRateChoice) => Promise<void> | void;
+  status: CyclotronStatus;
+  staleAfterHours?: number;
+  now?: Date;
+}) {
+  const [open, setOpen] = useState(false);
+  const [rate, setRate] = useState(0.5);
+  const [days, setDays] = useState(7);
+  const [message, setMessage] = useState<string | null>(null);
+  const ageHours = Math.max(0, (now.getTime() - Date.parse(status.asOf)) / 3_600_000);
+  const stale = Number.isFinite(ageHours) && ageHours > staleAfterHours;
+  const override = status.reviewRate.override;
+
+  async function submit(choice: ReviewRateChoice) {
+    if (!onRequestRate) return;
+    setMessage("Sending…");
+    try {
+      await onRequestRate(choice);
+      setMessage("The next sweep applies it and the status will show who set it.");
+    } catch (error) {
+      setMessage(error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  return (
+    <section aria-label="Relevance cyclotron" className="space-y-2" data-reference-cyclotron-status>
+      <CyclotronStatusView status={status} />
+      {stale ? (
+        <p className="text-xs text-muted-foreground" data-reference-cyclotron-status-stale>
+          <span aria-hidden="true">⚠ </span>
+          Snapshot from {Math.round(ageHours)} hours ago; the next sweep refreshes it.
+        </p>
+      ) : null}
+      <button
+        aria-expanded={open}
+        className="text-xs text-muted-foreground underline underline-offset-4"
+        onClick={() => setOpen((value) => !value)}
+        type="button"
+      >
+        {open ? "Hide what the cyclotron is doing" : "What the cyclotron is doing"}
+      </button>
+      {open ? (
+        <div className="space-y-3">
+          <CyclotronStatusView classifierName="Relevant to this publication" status={status} variant="card" />
+          {onRequestRate ? (
+            <form
+              aria-label="Manual review rate"
+              className="flex flex-wrap items-end gap-3 text-sm"
+              data-reference-review-rate-form
+              onSubmit={(event) => {
+                event.preventDefault();
+                void submit({ rate, days });
+              }}
+            >
+              <label className="flex flex-col gap-1">
+                <span className="text-xs text-muted-foreground">Review rate for confident decisions</span>
+                <select aria-label="Manual review rate" onChange={(event) => setRate(Number(event.target.value))} value={rate}>
+                  {RATE_CHOICES.map((choice) => (
+                    <option key={choice} value={choice}>{Math.round(choice * 100)}%</option>
+                  ))}
+                </select>
+              </label>
+              <label className="flex flex-col gap-1">
+                <span className="text-xs text-muted-foreground">For</span>
+                <select aria-label="How long the manual rate lasts" onChange={(event) => setDays(Number(event.target.value))} value={days}>
+                  {DAY_CHOICES.map((choice) => (
+                    <option key={choice} value={choice}>{choice} day{choice === 1 ? "" : "s"}</option>
+                  ))}
+                </select>
+              </label>
+              <button className="cyclotron-review-secondary" type="submit">Set manual rate</button>
+              {override ? (
+                <button className="cyclotron-review-secondary" onClick={() => void submit({ clear: true })} type="button">
+                  Clear manual rate
+                </button>
+              ) : null}
+              <p className="basis-full text-xs text-muted-foreground">
+                Low-confidence decisions and the random audit share are always reviewed.
+              </p>
+              {message ? <p className="basis-full text-xs" role="status">{message}</p> : null}
+            </form>
+          ) : null}
+        </div>
+      ) : null}
+    </section>
+  );
+}

package/components/reference-relevance-review.tsx

@@ -0,0 +1,75 @@
+"use client";
+
+import { useState } from "react";
+import { ReviewControl, type ReviewReason } from "cyclotron/components/review-control";
+import { isScopeTrainingNegativeReason, REFERENCE_REJECTION_REASON_CODES } from "../lib/reference-policy";
+import {
+  curationForRelevanceReview,
+  type RelevanceCuration,
+  type RelevanceDecisionView,
+} from "../lib/relevance-decisions";
+
+/**
+ * Papyrus's existing rejection reasons, unchanged. Reasons that are not about
+ * relevance (a duplicate, an unavailable source) close the review without
+ * teaching the cyclotron.
+ */
+export const RELEVANCE_REVIEW_REASONS: ReviewReason[] = REFERENCE_REJECTION_REASON_CODES.map((code) => ({
+  code,
+  text: code.charAt(0).toUpperCase() + code.slice(1).replaceAll("_", " "),
+  ...(isScopeTrainingNegativeReason(code) ? {} : { noLabel: true }),
+}));
+
+export function ReferenceRelevanceReview({
+  disabled,
+  decision,
+  onCurate,
+  referenceLineageId,
+}: {
+  disabled?: boolean;
+  decision: RelevanceDecisionView;
+  onCurate: (curation: RelevanceCuration) => void;
+  referenceLineageId: string;
+}) {
+  const [shareable, setShareable] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const classes = decision.classes.length ? decision.classes : [decision.label];
+  return (
+    <section aria-label="Relevance review" className="space-y-2" data-reference-relevance-review={referenceLineageId}>
+      <ReviewControl
+        decision={{
+          decisionId: decision.decisionId,
+          label: decision.label,
+          confidence: decision.confidence,
+          classes,
+          version: decision.version ?? undefined,
+        }}
+        disabled={disabled}
+        itemId={referenceLineageId}
+        mode={decision.reviewControl === "thumbs" && classes.length === 2 ? "thumbs" : "labels"}
+        onReview={(review) => {
+          try {
+            setError(null);
+            onCurate(curationForRelevanceReview(decision, { ...review, shareable }));
+          } catch (failure) {
+            setError(failure instanceof Error ? failure.message : String(failure));
+          }
+        }}
+        positiveLabel={decision.positiveLabel ?? undefined}
+        question={decision.question ?? undefined}
+        reasons={RELEVANCE_REVIEW_REASONS}
+        reviewReason={decision.reviewRecommended ? decision.reviewDetail ?? undefined : undefined}
+      />
+      <label className="flex items-center gap-2 text-xs text-muted-foreground">
+        <input
+          checked={shareable}
+          disabled={disabled}
+          onChange={(event) => setShareable(event.target.checked)}
+          type="checkbox"
+        />
+        My explanation may be quoted publicly (for the Cyclotron example page)
+      </label>
+      {error ? <p className="text-xs text-destructive" role="alert">{error}</p> : null}
+    </section>
+  );
+}

package/components/settings-page.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { toPublicReaderPath } from "../lib/reader-base-path";
 import { signOut } from "aws-amplify/auth";
 import Link from "next/link";
 import { useCallback, useEffect, useRef, useState } from "react";
@@ -114,7 +115,7 @@ export function SettingsPage() {
   return (
     <main className="settings-page">
       <nav className="edition-progress edition-progress--newsroom settings-progress" aria-label="Settings navigation">
-        <Link className="edition-progress__button edition-progress__button--previous" href="/">
+        <Link className="edition-progress__button edition-progress__button--previous" href={toPublicReaderPath("/")}>
           <svg aria-hidden="true" className="edition-progress__icon" focusable="false" viewBox="0 0 10 10">
             <path d="M7.5 1 2.5 5 7.5 9Z" fill="currentColor" />
           </svg>

package/components/topic-steering-workspace.tsx

@@ -53,6 +53,8 @@ import {
   type ForumThreadWithMessages,
   type KnowledgeQueryResponse,
   type NewsroomRecordPage,
+  loadCyclotronStatus,
+  requestCyclotronReviewRate,
 } from "./news-desk-taxonomy-client";
 import { listConsoleThreads } from "../lib/console-chat-client";
 import {
@@ -76,12 +78,13 @@ import { buildNewsroomKnowledgeQueryInput, type NewsroomKnowledgeQueryAnchor as
 import { NewsroomConsoleProgressToggle, PapyrusConsoleChatIcon, usePapyrusConsole } from "./papyrus-console-shell";
 import { useResolvedPapyrusTheme } from "./use-resolved-papyrus-theme";
 import { SITE_BRAND } from "../lib/site-brand";
+import { browserPathToInternalNewsroomPath, toPublicNewsroomPath } from "../lib/newsroom-base-path";
 import { getNewsroomNavHref } from "../lib/newsroom-nav";
 import { cn } from "../lib/utils";
 import { useOptionalNewsDeskClient } from "./news-desk-client-provider";
 import { ReferenceSourcePreview } from "./reference-source-preview";
 import type { ReaderAuthSnapshot } from "./reader-auth-state";
-import { ReaderAuthControl } from "./reader-auth-control";
+import { NewsDeskAccessGate } from "./newsroom-access-gate";
 import { NewsroomOpsOverview } from "./newsroom-ops-overview";
 import { NewsroomReferencesView } from "./newsroom-references-view";
 import { NewsroomAssignmentsView } from "./newsroom-assignments-view";
@@ -150,9 +153,13 @@ import {
   type SemanticObjectSummary,
 } from "../lib/semantic-graph";
 import {
+  normalizeReferenceRejectionReasonCode,
   REFERENCE_REJECTION_REASON_CODES,
   referenceCurationStatusForAction,
 } from "../lib/reference-policy";
+import { currentRelevanceDecisions } from "../lib/relevance-decisions";
+import { buildReviewRateRequest, DEMO_CYCLOTRON_STATUS } from "../lib/relevance-status";
+import type { CyclotronStatus } from "cyclotron/cyclotron-status";
 import {
   referenceDisplaySummary,
   referenceMetadataField,
@@ -169,7 +176,6 @@ import {
   uniqueNeighborGroupsForCategoryContext,
   type CategoryDrilldownContext,
 } from "../lib/newsroom-category-drilldown";
-import type { NewsDeskShellState } from "../lib/news-desk-session";
 import {
   resolveNewsroomCardTemplate,
   type NewsroomCardSpan,
@@ -776,6 +782,24 @@ function NewsDeskDashboard({
   const [referenceAttachments, setReferenceAttachments] = useState(dashboard.referenceAttachments);
   const [messages, setMessages] = useState(dashboard.messages);
   const [semanticRelations, setSemanticRelations] = useState(dashboard.semanticRelations);
+  const relevanceDecisions = useMemo(() => currentRelevanceDecisions(semanticRelations), [semanticRelations]);
+  const relevanceCyclotronId = useMemo(
+    () => [...relevanceDecisions.values()].find((decision) => decision.cyclotronId)?.cyclotronId ?? null,
+    [relevanceDecisions],
+  );
+  const [cyclotronStatus, setCyclotronStatus] = useState<CyclotronStatus | null>(null);
+  useEffect(() => {
+    if (!relevanceCyclotronId) return;
+    if (dashboard.isDemo) {
+      setCyclotronStatus(DEMO_CYCLOTRON_STATUS);
+      return;
+    }
+    let cancelled = false;
+    loadCyclotronStatus(relevanceCyclotronId)
+      .then((status) => { if (!cancelled) setCyclotronStatus(status); })
+      .catch(() => { if (!cancelled) setCyclotronStatus(null); });
+    return () => { cancelled = true; };
+  }, [dashboard.isDemo, relevanceCyclotronId]);
   const [semanticNodes, setSemanticNodes] = useState(dashboard.semanticNodes);
   const [assignments, setAssignments] = useState(dashboard.assignments);
   const [assignmentEvents, setAssignmentEvents] = useState(dashboard.assignmentEvents);
@@ -1507,7 +1531,13 @@ function NewsDeskDashboard({
     });
   }
 
-  function runReferenceCurationAction(reference: ReferenceRecord, action: ReferenceCurationAction, note?: string, reasonCode?: ReferenceRejectionReasonCode | null) {
+  function runReferenceCurationAction(
+    reference: ReferenceRecord,
+    action: ReferenceCurationAction,
+    note?: string,
+    reasonCode?: ReferenceRejectionReasonCode | null,
+    relevance?: { decisionRelationId: string; shareable: boolean },
+  ) {
     const nextStatus = referenceCurationStatusForAction(action);
     setActionState({ id: reference.id, message: `${action} pending`, tone: "pending" });
     if (dashboard.isDemo) {
@@ -1535,6 +1565,7 @@ function NewsDeskDashboard({
           action,
           curationStatus: nextStatus,
           reasonCode: action === "reject" ? reasonCode ?? null : null,
+          ...(relevance ? { decisionRelationId: relevance.decisionRelationId, shareable: relevance.shareable } : {}),
         },
       }, ...current]);
       setSemanticRelations((current) => [{
@@ -1575,6 +1606,8 @@ function NewsDeskDashboard({
               actorLabel: authState.label,
               note: note?.trim() || undefined,
               reasonCode: action === "reject" ? reasonCode ?? undefined : undefined,
+              decisionRelationId: relevance?.decisionRelationId,
+              shareable: relevance ? relevance.shareable : undefined,
             },
             { authMode: USER_POOL_AUTH_MODE },
           );
@@ -3153,6 +3186,20 @@ function NewsDeskDashboard({
             demo={Boolean(dashboard.isDemo)}
             disabled={controlsDisabled}
             initialReferenceLineageId={initialSelection.reference ?? pathnameReferenceLineageId}
+            cyclotronStatus={cyclotronStatus}
+            decisions={relevanceDecisions}
+            onRequestReviewRate={relevanceCyclotronId ? async (choice) => {
+              const request = buildReviewRateRequest(choice, authState.label);
+              if (dashboard.isDemo) return;
+              await requestCyclotronReviewRate(relevanceCyclotronId, request);
+            } : undefined}
+            onRelevanceReview={(reference, curation) => runReferenceCurationAction(
+              reference,
+              curation.action,
+              curation.note ?? undefined,
+              normalizeReferenceRejectionReasonCode(curation.reasonCode),
+              { decisionRelationId: curation.decisionRelationId, shareable: curation.shareable },
+            )}
             onReview={(reference, action) => runReferenceCurationAction(reference, action)}
             referenceAttachments={referenceAttachments}
             references={references}
@@ -15188,14 +15235,14 @@ function normalizeKnowledgeQueryAnchorKind(value: string | null | undefined): Kn
 
 function normalizeNewsroomFromHref(value: string | null | undefined): string | null {
   if (!value) return null;
-  const trimmed = value.trim();
+  const trimmed = browserPathToInternalNewsroomPath(value.trim());
   if (!trimmed.startsWith("/newsroom")) return null;
-  return trimmed;
+  return toPublicNewsroomPath(trimmed);
 }
 
 function currentNewsroomOriginHref(fallback: string | null): string | null {
   if (typeof window === "undefined") return fallback;
-  const current = `${window.location.pathname}${window.location.search}`;
+  const current = browserPathToInternalNewsroomPath(`${window.location.pathname}${window.location.search}`);
   return current.startsWith("/newsroom/search") ? fallback : normalizeNewsroomFromHref(current);
 }
 
@@ -15229,7 +15276,7 @@ function buildNewsroomSearchHref(request: NewsroomSearchRequest, demo?: boolean)
   if (request.from) params.set("from", request.from);
   if (demo) params.set("demo", "1");
   const queryString = params.toString();
-  return queryString ? `/newsroom/search?${queryString}` : "/newsroom/search";
+  return toPublicNewsroomPath(queryString ? `/newsroom/search?${queryString}` : "/newsroom/search");
 }
 
 function focusNewsroomSearchForm() {
@@ -15399,63 +15446,6 @@ function readTextClaim(value: unknown): string | null {
   return typeof value === "string" && value.trim() ? value.trim() : null;
 }
 
-function NewsDeskAccessGate({ shell, showSectionTabs = false }: { shell: NewsDeskShellState | null; showSectionTabs?: boolean }) {
-  const accessPhase = shell?.phase ?? "checkingAccess";
-
-  return (
-    <NewsroomOpsShell
-      activeTab="overview"
-      appTitle={SITE_BRAND.appTitle}
-      backHref="/"
-      backLabel={SITE_BRAND.backToHomeLabel}
-      headerActions={(
-        <Link className={cn(buttonVariants({ variant: "ghost", size: "sm" }))} href="/settings">Settings</Link>
-      )}
-      pageTitle="Newsroom"
-      showNavigation={showSectionTabs}
-    >
-      <section aria-live="polite" data-news-desk-access={accessPhase} data-news-desk-access-phase={accessPhase}>
-        <div className="space-y-3 rounded-xl border border-border bg-card p-6">
-          <p className="m-0 text-[0.7rem] font-semibold uppercase tracking-[0.08em] text-muted-foreground">Access</p>
-          <h2 className="m-0 font-sans text-xl font-semibold tracking-tight">{formatAccessTitle(shell)}</h2>
-          <p className="m-0 text-sm text-muted-foreground">{formatAccessDetail(shell)}</p>
-          {shell?.error ? <p className="text-sm text-destructive">{shell.error}</p> : null}
-          <p className="m-0 text-sm text-foreground">{formatAccessActionDetail(shell)}</p>
-          {shell?.phase === "signedOut" || shell?.phase === "error" ? (
-            <div className="news-desk-access-panel__auth">
-              <ReaderAuthControl postAuthPath="/newsroom" showIdentity />
-            </div>
-          ) : null}
-        </div>
-      </section>
-    </NewsroomOpsShell>
-  );
-}
-
-function formatAccessTitle(state: NewsDeskShellState | null): string {
-  if (!state || state.phase === "checkingAccess") return "Checking Desk Credentials";
-  if (state.phase === "loadingDesk") return "Loading Newsroom Records";
-  if (state.phase === "forbidden") return "Editor Role Required";
-  if (state.phase === "error") return "Newsroom Unavailable";
-  return "Editor Sign-In Required";
-}
-
-function formatAccessDetail(state: NewsDeskShellState | null): string {
-  if (!state || state.phase === "checkingAccess") return `${SITE_BRAND.appTitle} is checking the current browser session before loading steering state.`;
-  if (state.phase === "loadingDesk") return `${SITE_BRAND.appTitle} verified the browser session and is loading private Newsroom records.`;
-  if (state.phase === "forbidden") return "This account is signed in, but the Cognito session does not include the editor or admin group.";
-  if (state.phase === "error") return `${SITE_BRAND.appTitle} could not verify this editor session or load the private Newsroom data.`;
-  return "Sign in with an editor or admin account to inspect category, category tree, ontology, and graph steering.";
-}
-
-function formatAccessActionDetail(state: NewsDeskShellState | null): string {
-  if (!state || state.phase === "checkingAccess") return "This should only take a moment. If it hangs, reload the page.";
-  if (state.phase === "loadingDesk") return "Private records are loading from GraphQL. Large reference queues may take several seconds.";
-  if (state.phase === "forbidden") return "Ask an admin to add this account to the editor or admin group, then sign out and back in.";
-  if (state.phase === "error") return "Reload the page or check the local development console for the GraphQL error.";
-  return "Use the login button above to authenticate with an editor or admin account.";
-}
-
 function SectionHeader({ title, detail }: { title: string; detail: string }) {
   const id = title.toLowerCase().replace(/[^a-z0-9]+/g, "-");
   return (

package/components/use-blog-header-obstacles.ts

@@ -0,0 +1,81 @@
+"use client";
+
+import { useEffect, useState, type RefObject } from "react";
+import type { BlogHeaderObstacle } from "./blog-page-background";
+
+const HEADER_OBSTACLE_SELECTORS = [
+  ".presentation-header__eyebrow",
+  ".presentation-header__word",
+  ".presentation-header__meta",
+  ".presentation-header__subtitle",
+  ".presentation-header__date",
+  ".presentation-header__tagline",
+  ".presentation-section-nav a",
+];
+
+function measureObstacleRect(element: HTMLElement): DOMRect {
+  const range = document.createRange();
+  range.selectNodeContents(element);
+  const contentRect = range.getBoundingClientRect();
+  range.detach();
+  if (contentRect.width > 0 && contentRect.height > 0) return contentRect;
+  return element.getBoundingClientRect();
+}
+
+/**
+ * Measures the rendered header text (eyebrow, masthead words, meta, tagline,
+ * section links) as rectangles in the coordinates of `.blog-page-background`,
+ * so a brand's background artwork can keep clear of them. Block-level header
+ * elements span the full page width even when their text ends mid-line, so
+ * the text range is measured instead of the element box.
+ */
+export function useBlogHeaderObstacles(
+  pageRef: RefObject<HTMLElement | null>,
+  paintBuffer: number,
+): BlogHeaderObstacle[] {
+  const [obstacles, setObstacles] = useState<BlogHeaderObstacle[]>([]);
+
+  useEffect(() => {
+    const page = pageRef.current;
+    if (!page) return;
+
+    const update = () => {
+      const background = page.querySelector<HTMLElement>(".blog-page-background");
+      const backgroundRect = background?.getBoundingClientRect();
+      if (!backgroundRect) return;
+
+      const next: BlogHeaderObstacle[] = [];
+      for (const selector of HEADER_OBSTACLE_SELECTORS) {
+        for (const element of Array.from(page.querySelectorAll<HTMLElement>(selector))) {
+          const rect = measureObstacleRect(element);
+          const intersectionTop = Math.max(rect.top, backgroundRect.top);
+          const intersectionBottom = Math.min(rect.bottom, backgroundRect.bottom);
+          const intersectionLeft = Math.max(rect.left, backgroundRect.left);
+          const intersectionRight = Math.min(rect.right, backgroundRect.right);
+          const width = intersectionRight - intersectionLeft;
+          const height = intersectionBottom - intersectionTop;
+          if (width <= 0 || height <= 0) continue;
+          next.push({
+            x: intersectionLeft - backgroundRect.left,
+            y: intersectionTop - backgroundRect.top,
+            width,
+            height: height + paintBuffer * 2,
+          });
+        }
+      }
+      setObstacles(next);
+    };
+
+    update();
+    const observer = new ResizeObserver(update);
+    observer.observe(page);
+    window.addEventListener("resize", update);
+    void document.fonts?.ready.then(update);
+    return () => {
+      observer.disconnect();
+      window.removeEventListener("resize", update);
+    };
+  }, [pageRef, paintBuffer]);
+
+  return obstacles;
+}

package/components/use-brand-fonts-ready.ts

@@ -0,0 +1,28 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { listBrandFontFamilies } from "../lib/brand-fonts";
+import { watchBrandFontsLoaded } from "../lib/brand-fonts-watch";
+import { clearPretextMeasurementCache } from "../lib/pretext-layout";
+import { SITE_BRAND } from "../lib/site-brand";
+
+/**
+ * Returns a number that increments each time the brand's declared font
+ * families finish loading. Pretext's width cache is cleared first, so
+ * measurements taken with fallback metrics are re-run with the real glyph
+ * widths. Stays 0 for brands without a font slot, and on the server.
+ */
+export function useBrandFontsReadyVersion(): number {
+  const [version, setVersion] = useState(0);
+
+  useEffect(() => {
+    return watchBrandFontsLoaded({
+      fontFaceSet: typeof document === "undefined" ? undefined : document.fonts,
+      families: listBrandFontFamilies(SITE_BRAND.fonts),
+      clearMeasurementCaches: clearPretextMeasurementCache,
+      onFontsSettled: () => setVersion((current) => current + 1),
+    });
+  }, []);
+
+  return version;
+}

package/components/use-rhythm-overlay.ts

@@ -0,0 +1,29 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+export function useRhythmOverlay(): boolean {
+  const [showRhythmOverlay, setShowRhythmOverlay] = useState(false);
+
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (isEditableEventTarget(event.target)) return;
+      if ((event.key === "=" || event.code === "Equal") && event.ctrlKey && !event.metaKey && !event.altKey) {
+        event.preventDefault();
+        setShowRhythmOverlay((current) => !current);
+      }
+    };
+
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, []);
+
+  return showRhythmOverlay;
+}
+
+function isEditableEventTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  const tagName = target.tagName.toLowerCase();
+  if (tagName === "input" || tagName === "textarea" || tagName === "select") return true;
+  return target.isContentEditable || target.closest("[contenteditable='true']") !== null;
+}