@hyperframes/studio 0.7.37 → 0.7.39

package/src/components/storyboard/StoryboardFrameFocus.tsx

@@ -3,6 +3,7 @@ import { setFrameStatus, setFrameVoiceover, type FrameStatus } from "@hyperframe
 import type { StoryboardFrameView } from "../../hooks/useStoryboard";
 import { useFileManagerContext } from "../../contexts/FileManagerContext";
 import { useViewMode } from "../../contexts/ViewModeContext";
+import { Button } from "../ui/Button";
 import { FramePoster, posterTime } from "./FramePoster";
 import { FRAME_STATUS_META, FRAME_STATUS_ORDER } from "./frameStatus";
 
@@ -67,7 +68,25 @@ export function StoryboardFrameFocus({
   const dirty = draft !== (frame.voiceover ?? "");
   const canOpenPreview = frame.srcExists && Boolean(frame.src);
 
-  // Leaving the frame drops the in-memory voiceover draft; confirm when it's dirty.
+  const saveVoiceover = useCallback(() => {
+    return applyEdit((src) => setFrameVoiceover(src, frame.index, draft));
+  }, [applyEdit, frame.index, draft]);
+
+  // Closing the tab with a dirty voiceover would lose it silently — same
+  // guard the sibling markdown editor registers for the same class of loss.
+  useEffect(() => {
+    if (!dirty) return;
+    const onBeforeUnload = (e: BeforeUnloadEvent) => {
+      e.preventDefault();
+    };
+    window.addEventListener("beforeunload", onBeforeUnload);
+    return () => window.removeEventListener("beforeunload", onBeforeUnload);
+  }, [dirty]);
+
+  // Leaving the frame drops the in-memory voiceover draft; confirm while it's
+  // dirty. An in-flight save does NOT count as safe: if it fails after unmount
+  // the error lands on an unmounted component and the draft is silently lost,
+  // so keep confirming until the save actually lands (dirty clears on success).
   const confirmLeave = () => !dirty || window.confirm("Discard unsaved voiceover changes?");
   const handleBack = () => {
     if (confirmLeave()) onBack();
@@ -158,18 +177,27 @@ export function StoryboardFrameFocus({
               <h3 className="text-xs font-semibold uppercase tracking-wider text-neutral-400">
                 🎙 Voiceover <span className="font-normal normal-case text-neutral-600">guide</span>
               </h3>
-              <button
-                type="button"
-                onClick={() => applyEdit((src) => setFrameVoiceover(src, frame.index, draft))}
-                disabled={!dirty || busy}
-                className="rounded bg-emerald-600 px-2.5 py-1 text-xs font-medium text-white disabled:opacity-40"
+              <Button
+                size="sm"
+                variant="primary"
+                onClick={saveVoiceover}
+                disabled={!dirty}
+                loading={busy}
+                className="bg-emerald-600 text-white enabled:hover:bg-emerald-500 shadow-none"
               >
-                Save
-              </button>
+                {busy ? "Saving…" : "Save"}
+              </Button>
             </div>
             <textarea
               value={draft}
               onChange={(e) => setDraft(e.target.value)}
+              onBlur={() => {
+                // Same autosave paradigm as the status row above — mixed save
+                // models inside one panel taught users the panel autosaves,
+                // then lost their voiceover. Explicit Save stays as the
+                // affordance; blur is the safety net.
+                if (dirty && !busy) void saveVoiceover();
+              }}
               rows={3}
               placeholder="What the narrator says over this frame…"
               className="w-full resize-y rounded border border-neutral-800 bg-neutral-900 p-2 text-sm text-neutral-200 outline-none focus:border-neutral-600"
@@ -189,14 +217,9 @@ export function StoryboardFrameFocus({
             </section>
           )}
 
-          <button
-            type="button"
-            onClick={openInPreview}
-            disabled={!canOpenPreview}
-            className="rounded border border-neutral-700 px-3 py-1.5 text-xs font-medium text-neutral-200 hover:bg-neutral-800 disabled:opacity-40"
-          >
+          <Button size="sm" variant="secondary" onClick={openInPreview} disabled={!canOpenPreview}>
             Open in Preview →
-          </button>
+          </Button>
         </div>
       </div>
     </div>
@@ -217,7 +240,7 @@ function NavButton({
       type="button"
       onClick={onClick}
       disabled={disabled}
-      className="rounded px-2 py-1 text-xs font-medium text-neutral-300 hover:bg-neutral-800 disabled:opacity-30"
+      className="rounded px-2 py-1 text-xs font-medium text-neutral-300 hover:bg-neutral-800 enabled:active:scale-[0.98] transition-transform disabled:opacity-30"
     >
       {label}
     </button>

package/src/components/storyboard/StoryboardLoaded.tsx

@@ -113,16 +113,33 @@ const SUB_VIEWS: Array<{ value: SubView; label: string }> = [
 ];
 
 function SubViewToggle({ value, onChange }: { value: SubView; onChange: (next: SubView) => void }) {
+  // Complete tabs contract: roving tabIndex + arrow-key navigation (the roles
+  // alone promised keyboard behavior the buttons didn't have).
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key !== "ArrowLeft" && e.key !== "ArrowRight") return;
+    e.preventDefault();
+    const currentIndex = SUB_VIEWS.findIndex((v) => v.value === value);
+    const delta = e.key === "ArrowRight" ? 1 : -1;
+    const next = SUB_VIEWS[(currentIndex + delta + SUB_VIEWS.length) % SUB_VIEWS.length];
+    if (next) onChange(next.value);
+  };
+
   return (
-    <div className="flex items-center gap-0.5 rounded-md bg-neutral-900 p-0.5" role="tablist">
+    <div
+      className="flex items-center gap-0.5 rounded-md bg-neutral-900 p-0.5"
+      role="tablist"
+      aria-label="Storyboard view"
+      onKeyDown={handleKeyDown}
+    >
       {SUB_VIEWS.map((option) => (
         <button
           key={option.value}
           type="button"
           role="tab"
           aria-selected={value === option.value}
+          tabIndex={value === option.value ? 0 : -1}
           onClick={() => onChange(option.value)}
-          className={`rounded px-3 py-1 text-xs font-medium transition-colors ${
+          className={`rounded px-3 py-1 text-xs font-medium transition-colors active:scale-[0.98] outline-none focus-visible:outline focus-visible:outline-2 focus-visible:outline-studio-accent ${
             value === option.value
               ? "bg-neutral-700 text-neutral-100"
               : "text-neutral-400 hover:text-neutral-200"

package/src/components/storyboard/StoryboardView.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import { useStoryboard } from "../../hooks/useStoryboard";
+import { Button } from "../ui/Button";
 import { StoryboardLoaded } from "./StoryboardLoaded";
 
 export interface StoryboardViewProps {
@@ -22,6 +23,11 @@ export function StoryboardView({ projectId, onSelectComposition }: StoryboardVie
     return (
       <StoryboardFrame>
         <Message tone="error">Couldn’t load the storyboard: {error}</Message>
+        <div className="flex justify-center">
+          <Button size="sm" variant="secondary" onClick={reload}>
+            Retry
+          </Button>
+        </div>
       </StoryboardFrame>
     );
   }

package/src/components/studioColorGradingScope.ts

@@ -0,0 +1,124 @@
+import type { MutableRefObject } from "react";
+import type { EditHistoryKind } from "../utils/editHistory";
+import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
+import { patchMediaColorGradingInHtml } from "./editor/colorGradingScopePatch";
+import { hasRelativeLutSource } from "./studioMediaJobs";
+
+export type ColorGradingScope = "source-file" | "project";
+export type ColorGradingScopeResult = { changedFiles: number; changedElements: number };
+
+type ProjectFileReader = (path: string) => Promise<string>;
+type ProjectFileWriter = (path: string, content: string) => Promise<void>;
+type ShowToast = (message: string, tone?: "error" | "info") => void;
+type RecordEdit = (entry: {
+  label: string;
+  kind: EditHistoryKind;
+  files: Record<string, { before: string; after: string }>;
+}) => Promise<void>;
+
+export const EMPTY_COLOR_GRADING_SCOPE_RESULT: ColorGradingScopeResult = {
+  changedFiles: 0,
+  changedElements: 0,
+};
+
+interface ApplyColorGradingScopeOptions {
+  scope: ColorGradingScope;
+  value: string | null;
+  selectedSourceFile: string;
+  fileTree: string[];
+  projectId: string;
+  domEditSaveTimestampRef: MutableRefObject<number>;
+  waitForPendingDomEditSaves: () => Promise<void>;
+  readProjectFile: ProjectFileReader;
+  writeProjectFile: ProjectFileWriter;
+  recordEdit: RecordEdit;
+  reloadPreview: () => void;
+  showToast: ShowToast;
+}
+
+function colorGradingScopePaths(
+  scope: ColorGradingScope,
+  selectedSourceFile: string,
+  fileTree: string[],
+): string[] {
+  return scope === "source-file"
+    ? [selectedSourceFile]
+    : fileTree.filter((path) => /\.html?$/i.test(path));
+}
+
+async function patchColorGradingScopeFiles(
+  paths: string[],
+  value: string | null,
+  readProjectFile: ProjectFileReader,
+): Promise<{ files: Record<string, string>; changedElements: number }> {
+  const snapshots = await Promise.all(
+    Array.from(new Set(paths)).map(async (path) => ({
+      path,
+      before: await readProjectFile(path),
+    })),
+  );
+  const files: Record<string, string> = {};
+  let changedElements = 0;
+
+  for (const { path, before } of snapshots) {
+    const result = patchMediaColorGradingInHtml(before, value);
+    if (result.html !== before) {
+      files[path] = result.html;
+      changedElements += result.count;
+    }
+  }
+
+  return { files, changedElements };
+}
+
+// fallow-ignore-next-line complexity
+export async function applyColorGradingScopeUpdate({
+  scope,
+  value,
+  selectedSourceFile,
+  fileTree,
+  projectId,
+  domEditSaveTimestampRef,
+  waitForPendingDomEditSaves,
+  readProjectFile,
+  writeProjectFile,
+  recordEdit,
+  reloadPreview,
+  showToast,
+}: ApplyColorGradingScopeOptions): Promise<ColorGradingScopeResult> {
+  await waitForPendingDomEditSaves();
+  if (scope === "project" && hasRelativeLutSource(value)) {
+    showToast(
+      "Project-wide color grading cannot copy relative LUT paths. Apply to this file or use a URL/data LUT.",
+      "error",
+    );
+    return EMPTY_COLOR_GRADING_SCOPE_RESULT;
+  }
+
+  const { files, changedElements } = await patchColorGradingScopeFiles(
+    colorGradingScopePaths(scope, selectedSourceFile, fileTree),
+    value,
+    readProjectFile,
+  );
+  if (Object.keys(files).length === 0) {
+    showToast("No color grading changed", "info");
+    return EMPTY_COLOR_GRADING_SCOPE_RESULT;
+  }
+
+  domEditSaveTimestampRef.current = Date.now();
+  const changedPaths = await saveProjectFilesWithHistory({
+    projectId,
+    label: value ? "Apply color grading" : "Clear color grading",
+    kind: "manual",
+    files,
+    readFile: readProjectFile,
+    writeFile: writeProjectFile,
+    recordEdit,
+  });
+  reloadPreview();
+  showToast(
+    `${value ? "Applied" : "Cleared"} color grading on ${changedElements} media item${changedElements === 1 ? "" : "s"}`,
+    "info",
+  );
+  return { changedFiles: changedPaths.length, changedElements };
+}

package/src/components/studioMediaJobs.ts

@@ -0,0 +1,123 @@
+import type {
+  BackgroundRemovalProgress,
+  BackgroundRemovalResult,
+} from "./editor/propertyPanelTypes";
+
+const MEDIA_JOB_RECONNECT_TIMEOUT_MS = 15_000;
+const ABSOLUTE_OR_ROOT_SOURCE_RE = /^(?:[a-z][a-z0-9+.-]*:|\/)/i;
+
+function parseSerializedColorGrading(value: string): { lut?: { src?: unknown } } | null {
+  try {
+    return JSON.parse(value) as { lut?: { src?: unknown } } | null;
+  } catch {
+    return null;
+  }
+}
+
+function readLutSource(value: string | null): string {
+  const src = value ? parseSerializedColorGrading(value)?.lut?.src : null;
+  return typeof src === "string" ? src.trim() : "";
+}
+
+export function hasRelativeLutSource(value: string | null): boolean {
+  const src = readLutSource(value);
+  return src !== "" && !ABSOLUTE_OR_ROOT_SOURCE_RE.test(src);
+}
+
+function parseProgressEvent(event: Event): BackgroundRemovalProgress | Error {
+  try {
+    return JSON.parse((event as MessageEvent).data) as BackgroundRemovalProgress;
+  } catch {
+    return new Error("Invalid background-removal progress event");
+  }
+}
+
+function getCompleteProgressResult(
+  progress: BackgroundRemovalProgress,
+): BackgroundRemovalResult | Error {
+  if (!progress.outputPath) return new Error("Background removal finished without an output path");
+  return {
+    outputPath: progress.outputPath,
+    backgroundOutputPath: progress.backgroundOutputPath,
+    provider: progress.provider,
+  };
+}
+
+function getTerminalProgressResult(
+  progress: BackgroundRemovalProgress,
+): BackgroundRemovalResult | Error | null {
+  switch (progress.status) {
+    case "complete":
+      return getCompleteProgressResult(progress);
+    case "failed":
+      return new Error(progress.error || "Background removal failed");
+    default:
+      return null;
+  }
+}
+
+export function waitForMediaJob(
+  jobId: string,
+  onProgress?: (progress: BackgroundRemovalProgress) => void,
+  signal?: AbortSignal,
+): Promise<BackgroundRemovalResult> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new DOMException("Background removal was cancelled", "AbortError"));
+      return;
+    }
+    const events = new EventSource(`/api/media-jobs/${encodeURIComponent(jobId)}/progress`);
+    let settled = false;
+    let reconnectTimer: number | null = null;
+
+    const clearReconnectTimer = () => {
+      if (reconnectTimer === null) return;
+      window.clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    };
+    const finish = (callback: () => void) => {
+      if (settled) return;
+      settled = true;
+      clearReconnectTimer();
+      signal?.removeEventListener("abort", handleAbort);
+      events.close();
+      callback();
+    };
+    const finishReject = (error: Error) => finish(() => reject(error));
+    const finishResolve = (result: BackgroundRemovalResult) => finish(() => resolve(result));
+    const handleAbort = () => {
+      finishReject(new DOMException("Background removal was cancelled", "AbortError"));
+    };
+    signal?.addEventListener("abort", handleAbort, { once: true });
+
+    // fallow-ignore-next-line complexity
+    events.addEventListener("progress", (event) => {
+      const progress = parseProgressEvent(event);
+      if (progress instanceof Error) {
+        finishReject(progress);
+        return;
+      }
+      clearReconnectTimer();
+      onProgress?.(progress);
+      const terminalResult = getTerminalProgressResult(progress);
+      if (!terminalResult) return;
+      if (terminalResult instanceof Error) {
+        finishReject(terminalResult);
+      } else {
+        finishResolve(terminalResult);
+      }
+    });
+    events.onopen = clearReconnectTimer;
+    events.onerror = () => {
+      if (events.readyState === EventSource.CLOSED) {
+        finishReject(new Error("Lost connection to background-removal job"));
+        return;
+      }
+      if (reconnectTimer === null) {
+        reconnectTimer = window.setTimeout(() => {
+          finishReject(new Error("Lost connection to background-removal job"));
+        }, MEDIA_JOB_RECONNECT_TIMEOUT_MS);
+      }
+    };
+  });
+}

package/src/components/ui/Button.tsx

@@ -30,22 +30,24 @@ const variantStyles: Record<ButtonVariant, string> = {
   primary: [
     "bg-white text-neutral-950 font-medium",
     "shadow-btn-primary",
-    "hover:bg-neutral-200",
-    "active:scale-[0.97]",
+    "enabled:hover:bg-neutral-200",
+    "enabled:active:scale-[0.97]",
   ].join(" "),
   secondary: [
     "bg-transparent text-neutral-300 font-medium",
     "border border-border",
-    "hover:bg-surface-hover hover:text-white hover:border-border-strong",
-    "active:scale-[0.98]",
+    "enabled:hover:bg-surface-hover enabled:hover:text-white enabled:hover:border-border-strong",
+    "enabled:active:scale-[0.98]",
+  ].join(" "),
+  danger: [
+    "bg-accent-red text-white font-medium",
+    "enabled:hover:bg-red-600",
+    "enabled:active:scale-[0.97]",
   ].join(" "),
-  danger: ["bg-accent-red text-white font-medium", "hover:bg-red-600", "active:scale-[0.97]"].join(
-    " ",
-  ),
   ghost: [
     "bg-transparent text-neutral-400",
-    "hover:bg-surface-hover hover:text-white",
-    "active:scale-[0.98]",
+    "enabled:hover:bg-surface-hover enabled:hover:text-white",
+    "enabled:active:scale-[0.98]",
   ].join(" "),
 };
 
@@ -55,6 +57,8 @@ const sizeStyles: Record<ButtonSize, string> = {
   lg: "h-9 px-4 text-base gap-2 rounded-button",
 };
 
+// Imported by the shell/renders PRs later in this stack.
+// fallow-ignore-next-line unused-export
 export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
   (
     {
@@ -76,8 +80,11 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
         className={[
           "inline-flex items-center justify-center",
           "transition-all duration-press ease-standard",
-          "disabled:opacity-40 disabled:pointer-events-none",
+          // No pointer-events-none: disabled buttons must still receive hover
+          // so a wrapping Tooltip can explain WHY they're disabled (A5).
+          "disabled:opacity-40 disabled:cursor-not-allowed",
           "select-none cursor-pointer",
+          "outline-none focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-studio-accent",
           variantStyles[variant],
           sizeStyles[size],
           className,
@@ -126,6 +133,7 @@ const iconSizeStyles: Record<ButtonSize, string> = {
   lg: "min-w-9 min-h-9 rounded-button", // 36px
 };
 
+// fallow-ignore-next-line unused-export
 export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(
   ({ icon, size = "md", variant = "ghost", className = "", ...props }, ref) => {
     return (
@@ -134,8 +142,9 @@ export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(
         className={[
           "inline-flex items-center justify-center",
           "transition-all duration-press ease-standard",
-          "disabled:opacity-40 disabled:pointer-events-none",
+          "disabled:opacity-40 disabled:cursor-not-allowed",
           "select-none cursor-pointer",
+          "outline-none focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-studio-accent",
           variantStyles[variant],
           iconSizeStyles[size],
           className,

package/src/components/ui/HyperframesLoader.tsx

@@ -25,7 +25,7 @@ export function HyperframesLoader({
   const markFrameSize = Math.round(size * 1.16);
 
   return (
-    <div className="hf-loader" draggable={false}>
+    <div className="hf-loader" role="status" draggable={false}>
       <div
         className="hf-loader-mark-frame"
         style={{ width: markFrameSize, height: markFrameSize }}
@@ -83,7 +83,13 @@ export function HyperframesLoader({
       <div className="hf-loader-title">{title}</div>
       {detail && <div className="hf-loader-detail">{detail}</div>}
       {boundedProgress !== undefined && (
-        <div className="hf-loader-progress" aria-hidden="true">
+        <div
+          className="hf-loader-progress"
+          role="progressbar"
+          aria-valuemin={0}
+          aria-valuemax={100}
+          aria-valuenow={Math.round(boundedProgress * 100)}
+        >
           <div
             className="hf-loader-progress__fill"
             style={{ transform: `scaleX(${boundedProgress})` }}
@@ -95,6 +101,7 @@ export function HyperframesLoader({
   );
 }
 
+// fallow-ignore-next-line unused-export
 export function StatusFrame(props: HyperframesLoaderProps) {
   return (
     <div className="hf-frame">

package/src/components/ui/SearchInput.tsx

@@ -0,0 +1,53 @@
+// fallow-ignore-file unused-file
+// (consumers land in the sidebar/panels PR later in this stack)
+import { type InputHTMLAttributes } from "react";
+
+interface SearchInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type"> {
+  /** Accessible name — placeholder alone is not one. */
+  "aria-label": string;
+}
+
+/**
+ * Shared search input — one visual system (panel-input tokens) for every
+ * panel search box, with a required accessible name.
+ */
+export function SearchInput({ className = "", ...props }: SearchInputProps) {
+  return (
+    <div
+      className={`flex items-center gap-1.5 rounded-md bg-panel-input px-2.5 py-[5px] ${className}`}
+    >
+      <svg
+        width="12"
+        height="12"
+        viewBox="0 0 256 256"
+        fill="none"
+        className="flex-shrink-0"
+        aria-hidden="true"
+      >
+        <circle
+          cx="116"
+          cy="116"
+          r="76"
+          stroke="currentColor"
+          strokeWidth="22"
+          className="text-panel-text-5"
+        />
+        <line
+          x1="170"
+          y1="170"
+          x2="232"
+          y2="232"
+          stroke="currentColor"
+          strokeWidth="22"
+          strokeLinecap="round"
+          className="text-panel-text-5"
+        />
+      </svg>
+      <input
+        type="text"
+        className="min-w-0 w-full bg-transparent text-[11px] text-panel-text-1 outline-none placeholder:text-panel-text-5"
+        {...props}
+      />
+    </div>
+  );
+}

package/src/components/ui/Tooltip.tsx

@@ -1,4 +1,4 @@
-import { useState, useRef, useCallback, type ReactNode } from "react";
+import { useState, useRef, useCallback, useEffect, useId, type ReactNode } from "react";
 import { createPortal } from "react-dom";
 
 interface TooltipProps {
@@ -8,22 +8,46 @@ interface TooltipProps {
   side?: "top" | "bottom";
 }
 
+// Rough bubble height (padding + one text line) used to decide flipping
+// before the bubble has rendered; exact height isn't needed for the guard.
+const APPROX_BUBBLE_H = 28;
+const VIEWPORT_MARGIN = 8;
+
 export function Tooltip({ label, children, delay = 400, side = "top" }: TooltipProps) {
   const [visible, setVisible] = useState(false);
   const [pos, setPos] = useState({ x: 0, y: 0 });
+  const [resolvedSide, setResolvedSide] = useState<"top" | "bottom">(side);
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const triggerRef = useRef<HTMLSpanElement>(null);
+  // WCAG 4.1.2: programmatically associate the bubble with its trigger.
+  const tooltipId = useId();
 
   const show = useCallback(() => {
+    if (timerRef.current) clearTimeout(timerRef.current);
     timerRef.current = setTimeout(() => {
       const el = triggerRef.current;
       if (!el) return;
       const child = el.firstElementChild as HTMLElement | null;
       const rect = (child ?? el).getBoundingClientRect();
       if (rect.width === 0 && rect.height === 0) return;
+      // Flip when the preferred side would clip the viewport edge.
+      let nextSide = side;
+      if (side === "top" && rect.top - APPROX_BUBBLE_H - 6 < VIEWPORT_MARGIN) {
+        nextSide = "bottom";
+      } else if (
+        side === "bottom" &&
+        rect.bottom + APPROX_BUBBLE_H + 6 > window.innerHeight - VIEWPORT_MARGIN
+      ) {
+        nextSide = "top";
+      }
+      const x = Math.min(
+        Math.max(rect.left + rect.width / 2, VIEWPORT_MARGIN),
+        window.innerWidth - VIEWPORT_MARGIN,
+      );
+      setResolvedSide(nextSide);
       setPos({
-        x: rect.left + rect.width / 2,
-        y: side === "top" ? rect.top - 6 : rect.bottom + 6,
+        x,
+        y: nextSide === "top" ? rect.top - 6 : rect.bottom + 6,
       });
       setVisible(true);
     }, delay);
@@ -37,9 +61,27 @@ export function Tooltip({ label, children, delay = 400, side = "top" }: TooltipP
     setVisible(false);
   }, []);
 
+  // WCAG 1.4.13: tooltip content must be dismissible with Escape.
+  useEffect(() => {
+    if (!visible) return;
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") hide();
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [visible, hide]);
+
   return (
     <>
-      <span ref={triggerRef} onPointerEnter={show} onPointerLeave={hide} className="contents">
+      <span
+        ref={triggerRef}
+        onPointerEnter={show}
+        onPointerLeave={hide}
+        onFocus={show}
+        onBlur={hide}
+        aria-describedby={visible ? tooltipId : undefined}
+        className="contents"
+      >
         {children}
       </span>
       {visible &&
@@ -49,10 +91,14 @@ export function Tooltip({ label, children, delay = 400, side = "top" }: TooltipP
             style={{
               left: pos.x,
               top: pos.y,
-              transform: side === "top" ? "translate(-50%, -100%)" : "translate(-50%, 0)",
+              transform: resolvedSide === "top" ? "translate(-50%, -100%)" : "translate(-50%, 0)",
             }}
           >
-            <div className="px-2 py-1 rounded-md bg-neutral-800 border border-neutral-700/50 text-[10px] font-medium text-neutral-200 whitespace-nowrap shadow-lg">
+            <div
+              role="tooltip"
+              id={tooltipId}
+              className="px-2 py-1 rounded-md bg-neutral-800 border border-neutral-700/50 text-[10px] font-medium text-neutral-200 whitespace-nowrap shadow-lg"
+            >
               {label}
             </div>
           </div>,