konpeki 0.3.0 → 0.3.1

package/src/components/RightPanel.tsx

@@ -5,6 +5,7 @@ import type {
 } from "../../composition/types.ts";
 import { componentInstanceLabel, type Draft } from "../lib/model.ts";
 import { InspectorPanel } from "./InspectorPanel.tsx";
+import { VectorOverflowWarning } from "./VectorOverflowWarning.tsx";
 
 export type RightPanelView = "settings" | "layers";
 
@@ -20,6 +21,7 @@ function LayersPanel({
   onReorderPaintOrder: (ids: string[]) => void;
 }) {
   const [dragging, setDragging] = useState<string>();
+  const [dropIndex, setDropIndex] = useState<number>();
   const layers = [...slide.paintOrder].reverse();
   function moveLayer(id: string, toIndex: number) {
     const next = layers.filter((item) => item !== id);
@@ -33,7 +35,36 @@ function LayersPanel({
         <span>Front to back</span>
       </div>
       {layers.length ? (
-        <div className="layer-list">
+        <div className="layer-list"
+          onDragOver={(event) => {
+            if (!dragging) return;
+            event.preventDefault();
+            const rows = [...event.currentTarget.querySelectorAll<HTMLElement>(".layer-row")];
+            const next = rows.findIndex((row) => {
+              const rect = row.getBoundingClientRect();
+              return event.clientY < rect.top + rect.height / 2;
+            });
+            const boundary = next < 0 ? layers.length : next;
+            const sourceIndex = layers.indexOf(dragging);
+            const unchanged = boundary === sourceIndex || boundary === sourceIndex + 1;
+            event.dataTransfer.dropEffect = unchanged ? "none" : "move";
+            setDropIndex(unchanged ? undefined : boundary);
+          }}
+          onDragLeave={(event) => {
+            if (!event.currentTarget.contains(event.relatedTarget as Node | null)) {
+              setDropIndex(undefined);
+            }
+          }}
+          onDrop={(event) => {
+            if (!dragging) return;
+            event.preventDefault();
+            if (dropIndex !== undefined) {
+              moveLayer(dragging, dropIndex > layers.indexOf(dragging) ? dropIndex - 1 : dropIndex);
+            }
+            setDragging(undefined);
+            setDropIndex(undefined);
+          }}
+        >
           {layers.map((id, index) => {
             const component = slide.components.find((item) => item.id === id)!;
             const groups = slide.groups
@@ -44,23 +75,18 @@ function LayersPanel({
               <div
                 key={id}
                 data-layer={id}
+                data-drop-edge={dropIndex === index ? "before" : dropIndex === layers.length && index === layers.length - 1 ? "after" : undefined}
                 className={`layer-row ${selectedComponentId === id ? "selected" : ""} ${dragging === id ? "dragging" : ""}`}
                 draggable
                 onDragStart={(event) => {
                   setDragging(id);
+                  setDropIndex(undefined);
                   event.dataTransfer.effectAllowed = "move";
                   event.dataTransfer.setData("text/plain", id);
                 }}
-                onDragEnd={() => setDragging(undefined)}
-                onDragOver={(event) => {
-                  event.preventDefault();
-                  event.dataTransfer.dropEffect = "move";
-                }}
-                onDrop={(event) => {
-                  event.preventDefault();
-                  const source = dragging || event.dataTransfer.getData("text/plain");
-                  if (source && source !== id) moveLayer(source, index);
+                onDragEnd={() => {
                   setDragging(undefined);
+                  setDropIndex(undefined);
                 }}
               >
                 <span className="layer-drag" aria-hidden="true">⠿</span>
@@ -112,6 +138,7 @@ export function RightPanel({
   onSelectSlide,
   onSelectComponent,
   onSelectVectorElement,
+  onSelectOverflow,
   onReorderPaintOrder,
   onComponent,
   onSlide,
@@ -132,6 +159,7 @@ export function RightPanel({
   onSelectSlide: () => void;
   onSelectComponent: (id: string) => void;
   onSelectVectorElement: (id?: string) => void;
+  onSelectOverflow: (componentId: string, elementId?: string) => void;
   onReorderPaintOrder: (ids: string[]) => void;
   onComponent: (component: CompositionComponent, mergeKey?: string) => void;
   onSlide: (slide: CompositionSlide, mergeKey?: string) => void;
@@ -154,6 +182,9 @@ export function RightPanel({
             </button>
           ))}
         </div>
+        <div className="overflow-control" inert={collapsed}>
+          <VectorOverflowWarning slide={slide} theme={draft.theme} onSelect={onSelectOverflow} />
+        </div>
         <button
           type="button"
           className="panel-toggle"
@@ -174,6 +205,7 @@ export function RightPanel({
       <div className="right-panel-body" inert={collapsed}>
       {view === "settings" ? (
         <InspectorPanel
+          key={component?.id ?? slide.id}
           component={component}
           componentLabel={componentLabel}
           slide={slide}

package/src/components/VectorOverflowWarning.tsx

@@ -1,22 +1,31 @@
-import { useEffect, useState } from "react";
+import { useEffect, useId, useRef, useState } from "react";
 import type { CompositionSlide, CompositionDocument } from "../../composition/types.ts";
+import { componentInstanceLabel } from "../lib/model.ts";
 
 /** Measure rendered text, including nested SVG transforms, after fonts settle. */
-export function VectorOverflowWarning({ slide, theme }: {
+export function VectorOverflowWarning({ slide, theme, onSelect }: {
   slide: CompositionSlide;
   theme: CompositionDocument["theme"];
+  onSelect: (componentId: string, elementId?: string) => void;
 }) {
-  const [count, setCount] = useState(0);
+  const [issues, setIssues] = useState<{ componentId: string; elementId?: string; text: string }[]>([]);
+  const id = useId();
+  const popover = useRef<HTMLDivElement>(null);
+  useEffect(() => { popover.current?.hidePopover(); }, [slide.id]);
   useEffect(() => {
     let cancelled = false;
     let frame = 0;
     function measure() {
       frame = requestAnimationFrame(() => {
         if (cancelled) return;
-        let overflow = 0;
+        const overflow: typeof issues = [];
+        function add(text: Element) {
+          const componentId = text.closest<HTMLElement>("[data-component]")?.dataset.component;
+          if (componentId) overflow.push({ componentId, elementId: text.getAttribute("data-vector-element") ?? undefined, text: text.textContent?.trim().slice(0, 80) ?? "Text" });
+        }
         document.querySelectorAll<HTMLElement>(".stage .text-block-content").forEach((text) => {
           const surface = text.parentElement;
-          if (surface && (text.scrollHeight > surface.clientHeight + 1 || text.scrollWidth > surface.clientWidth + 1)) overflow++;
+          if (surface && (text.scrollHeight > surface.clientHeight + 1 || text.scrollWidth > surface.clientWidth + 1)) add(text);
         });
         document.querySelectorAll<SVGSVGElement>(".stage .custom-vector-art").forEach((svg) => {
           const root = svg.getScreenCTM();
@@ -32,15 +41,33 @@ export function VectorOverflowWarning({ slide, theme }: {
             if (corners.some(([x, y]) => {
               const p = new DOMPoint(x, y).matrixTransform(transform);
               return p.x < view.x - 1 || p.y < view.y - 1 || p.x > view.x + view.width + 1 || p.y > view.y + view.height + 1;
-            })) overflow++;
+            })) add(text);
           });
         });
-        setCount(overflow);
+        setIssues(overflow);
+        if (!overflow.length) popover.current?.hidePopover();
       });
     }
     void document.fonts.ready.then(measure);
     document.fonts.addEventListener("loadingdone", measure);
     return () => { cancelled = true; cancelAnimationFrame(frame); document.fonts.removeEventListener("loadingdone", measure); };
   }, [slide, theme]);
-  return count ? <p role="status" className="field-error">{count} text {count === 1 ? "element exceeds" : "elements exceed"} its component viewport on this slide. Revise the text or geometry; nothing was resized.</p> : null;
+  return <>
+    <span className="sr-only" role="status">{issues.length ? `${issues.length} text overflow ${issues.length === 1 ? "warning" : "warnings"} on this page` : ""}</span>
+    <button type="button" className="overflow-trigger" popoverTarget={id} disabled={!issues.length}
+      aria-label={`${issues.length} text overflow warnings`} title="Text overflow warnings">
+      <svg viewBox="0 0 20 20" aria-hidden="true"><path d="M10 3 18 17H2ZM10 8v4m0 2v.5" /></svg>
+      <span>{issues.length}</span>
+    </button>
+    <div id={id} ref={popover} popover="auto" className="overflow-popover">
+      <strong>Text outside its frame</strong>
+      <p>Select an item to revise its text or size. Nothing was resized automatically.</p>
+      <ul>{issues.map(issue => <li key={`${issue.componentId}:${issue.elementId ?? "native"}`}>
+        <button type="button" onClick={() => { popover.current?.hidePopover(); onSelect(issue.componentId, issue.elementId); }}>
+          <strong>{componentInstanceLabel(slide.components, issue.componentId)}{issue.elementId ? ` · ${issue.elementId}` : ""}</strong>
+          <span>{issue.text}</span>
+        </button>
+      </li>)}</ul>
+    </div>
+  </>;
 }

package/src/components/WorkspaceChrome.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useRef, type ReactNode, type RefObject } from "react";
+import { useEffect, useRef, useState, type ReactNode, type RefObject } from "react";
 import type { CompositionComponent } from "../../composition/types.ts";
 import { componentLabels } from "../lib/model.ts";
 import mark from "../assets/konpeki-mark.png";
@@ -103,13 +103,30 @@ export function WorkspaceChrome({
   onComponentTool: (kind: CompositionComponent["kind"]) => void;
 }) {
   const browserMenu = useRef<HTMLDetailsElement>(null);
+  const [browserMenuOpen, setBrowserMenuOpen] = useState(false);
   const importInput = useRef<HTMLInputElement>(null);
-  function closeBrowserMenu() {
-    if (browserMenu.current) browserMenu.current.open = false;
+  function closeBrowserMenu(restoreFocus = true) {
+    const menu = browserMenu.current;
+    if (!menu?.open) return;
+    setBrowserMenuOpen(false);
+    if (restoreFocus) menu.querySelector("summary")?.focus();
   }
   useEffect(() => {
-    if (leftCollapsed) closeBrowserMenu();
+    if (leftCollapsed) closeBrowserMenu(false);
   }, [leftCollapsed]);
+  useEffect(() => {
+    function dismissOutside(event: Event) {
+      if (event.target instanceof Node && !browserMenu.current?.contains(event.target)) {
+        closeBrowserMenu(false);
+      }
+    }
+    document.addEventListener("pointerdown", dismissOutside);
+    document.addEventListener("focusin", dismissOutside);
+    return () => {
+      document.removeEventListener("pointerdown", dismissOutside);
+      document.removeEventListener("focusin", dismissOutside);
+    };
+  }, []);
   return (
     <>
       <div className={`left-sidebar${leftCollapsed ? " collapsed" : ""}`}>
@@ -134,18 +151,16 @@ export function WorkspaceChrome({
             Enter a title.
           </span>
         )}
-        {fileStatus && fileStatus !== "saved" && (
+        {fileStatus && (
           <span
-            className={`file-status ${fileStatus}${leftCollapsed ? " sr-only" : ""}`}
+            className={`file-status ${fileStatus}`}
             role="status"
             aria-live="polite"
-            title={fileStatus === "conflict"
-              ? "The file changed elsewhere while this browser has edits."
-              : undefined}
+            title={fileStatus === "saved" ? "Saved to file" : fileStatus === "saving" ? "Saving to file" : fileStatus === "loading" ? "Opening file" : "Changes are not saved — see the recovery notice"}
           >
-            {fileStatus === "loading" ? "Opening"
+            <span className="sr-only">{fileStatus === "saved" ? "Saved" : fileStatus === "loading" ? "Opening"
               : fileStatus === "saving" ? "Saving"
-              : fileStatus === "conflict" ? "Conflict" : "Save error"}
+              : fileStatus === "conflict" ? "Conflict" : "Save error"}</span>
           </span>
         )}
         <button type="button" className="panel-toggle"
@@ -184,17 +199,31 @@ export function WorkspaceChrome({
           </svg>
         </button>
         {browserTools && (
-          <details className="browser-menu" ref={browserMenu}>
-            <summary>Browser</summary>
-            <div className="browser-menu-popover">
-              <strong>Browser playground</strong>
-              <p role="status">
-                {browserTools.saveMessage}
-                {" "}Nothing syncs automatically.
-              </p>
+          <details className="browser-menu" ref={browserMenu} open={browserMenuOpen} onKeyDown={(event) => {
+            if (event.key === "Escape" && browserMenu.current?.open) {
+              event.preventDefault();
+              event.stopPropagation();
+              closeBrowserMenu();
+            }
+          }}>
+            <summary onClick={(event) => {
+              event.preventDefault();
+              setBrowserMenuOpen(open => !open);
+            }}>
+              Demo Mode
+              <svg viewBox="0 0 16 16" aria-hidden="true"><path d="m4 10 4-4 4 4" /></svg>
+            </summary>
+            <div className="browser-menu-popover" role="region" aria-label="Demo Mode" inert={!browserMenuOpen}>
+              <div className="browser-menu-intro">
+                <strong>Demo Mode</strong>
+                <p>
+                  Explore the canvas here. No agent connection or file sync.{" "}
+                  <span role="status">{browserTools.saveMessage}</span>
+                </p>
+              </div>
               <div className="browser-menu-actions">
                 <button type="button" onClick={() => importInput.current?.click()}>
-                  Import JSON
+                  Import
                 </button>
                 <input
                   ref={importInput}
@@ -214,33 +243,32 @@ export function WorkspaceChrome({
                   closeBrowserMenu();
                   browserTools.onDownloadJSON();
                 }}>
-                  Download JSON
+                  Export
                 </button>
-                <button type="button" onClick={() => {
+                <button type="button" className="secondary" onClick={() => {
                   closeBrowserMenu();
                   browserTools.onStartBlank();
                 }}>
                   Start blank
                 </button>
-                <button type="button" onClick={() => {
+                <button type="button" className="secondary" onClick={() => {
                   closeBrowserMenu();
                   browserTools.onReset();
                 }}>
                   {browserTools.example ? "Reset example" : "Reset local draft"}
                 </button>
               </div>
-              <p className="browser-agent-handoff">
-                To continue with a coding agent, download the editable JSON and
-                follow the{" "}
+              <div className="browser-agent-handoff">
+                <strong>Continue with an agent</strong>
+                <p>Export the JSON file, then ask your coding agent to open it with Konpeki.</p>
                 <a
                   href="https://github.com/vcfgdev/konpeki/blob/main/SETUP.md"
                   target="_blank"
                   rel="noreferrer"
                 >
-                  setup guidance
+                  Setup guide
                 </a>
-                .
-              </p>
+              </div>
             </div>
           </details>
         )}

package/src/components/ui.tsx

@@ -1,4 +1,98 @@
-import { useId, type ReactNode } from "react";
+import { useEffect, useId, useLayoutEffect, useRef, useState, type ReactNode } from "react";
+import { createPortal } from "react-dom";
+
+/** Retain the last content while CSS transitions out; hidden notices are inert. */
+export function FeedbackNotice({ kind, children, tone = "neutral", onDismiss, onPauseChange }: {
+  kind: "toast" | "recovery";
+  children: ReactNode;
+  tone?: "neutral" | "error";
+  onDismiss?: () => void;
+  onPauseChange?: (paused: boolean) => void;
+}) {
+  const visible = Boolean(children);
+  const [last, setLast] = useState({ children, tone });
+  if (visible && (children !== last.children || tone !== last.tone)) setLast({ children, tone });
+  return <div className={`feedback-notice ${kind}${visible ? " visible" : ""}${last.tone === "error" ? " error" : ""}`}
+    inert={!visible} aria-hidden={!visible} role={kind === "recovery" && visible ? "alert" : undefined}
+    onMouseEnter={() => onPauseChange?.(true)} onMouseLeave={() => onPauseChange?.(false)}
+    onFocus={() => onPauseChange?.(true)} onBlur={event => { if (!event.currentTarget.contains(event.relatedTarget)) onPauseChange?.(false); }}>
+    {kind === "toast" ? <span role={visible ? last.tone === "error" ? "alert" : "status" : undefined}
+      aria-live={visible ? last.tone === "error" ? "assertive" : "polite" : "off"}>{last.children}</span> : last.children}
+    {onDismiss && last.children && <button type="button" className="toast-dismiss" aria-label="Dismiss notification" onClick={onDismiss}>×</button>}
+  </div>;
+}
+
+/** Keep incomplete input out of the document, without silently correcting it. */
+export function NumberField({ label, name, value, min, max, step = 1, unit, onCommit, onEditEnd }: {
+  label: string;
+  name?: string;
+  value: number;
+  min: number;
+  max: number;
+  step?: number;
+  unit?: string;
+  onCommit: (value: number) => void;
+  onEditEnd: () => void;
+}) {
+  const [text, setText] = useState(String(value));
+  const [error, setError] = useState("");
+  const [showError, setShowError] = useState(false);
+  const [position, setPosition] = useState({ top: 0, left: 0 });
+  const input = useRef<HTMLInputElement>(null);
+  const id = useId();
+  useEffect(() => { setText(String(value)); setError(""); }, [value]);
+  useLayoutEffect(() => {
+    if (!error || !showError) return;
+    function place() {
+      const rect = input.current!.getBoundingClientRect();
+      const panel = input.current!.closest(".right-panel")!.getBoundingClientRect();
+      const beside = panel.left >= 276;
+      setPosition({ top: Math.max(8, Math.min(beside ? rect.top : rect.bottom + 6, window.innerHeight - 80)), left: beside ? panel.left - 268 : Math.max(8, Math.min(rect.left, window.innerWidth - 268)) });
+      if (rect.bottom < panel.top + 58 || rect.top > panel.bottom) setShowError(false);
+    }
+    function focus(event: FocusEvent) {
+      if (event.target !== input.current) setShowError(false);
+    }
+    place();
+    window.addEventListener("resize", place);
+    window.addEventListener("scroll", place, true);
+    document.addEventListener("focusin", focus);
+    return () => {
+      window.removeEventListener("resize", place);
+      window.removeEventListener("scroll", place, true);
+      document.removeEventListener("focusin", focus);
+    };
+  }, [error, showError]);
+  function commit() {
+    const number = Number(text);
+    if (!text.trim() || !Number.isFinite(number) || number < min || number > max) {
+      setError(`${label} must be ${min}–${max}${unit ? ` ${unit}` : ""}. Escape restores the previous value.`);
+      setShowError(true);
+    } else {
+      setError("");
+      if (number !== value) onCommit(number);
+    }
+    onEditEnd();
+  }
+  return <Field label={label}>
+    <span className={unit ? "parameter-input" : "number-input"}>
+      <input ref={input} name={name} type="number" autoComplete="off" min={min} max={max} step={step}
+        value={text} aria-invalid={error ? true : undefined} aria-describedby={error ? id : undefined}
+        onChange={event => setText(event.target.value)} onFocus={() => setShowError(true)} onBlur={commit}
+        onKeyDown={event => {
+          if ((event.metaKey || event.ctrlKey) && ["z", "y"].includes(event.key.toLowerCase()) && text !== String(value)) event.stopPropagation();
+          if (event.key === "Enter") { event.preventDefault(); commit(); }
+          if (event.key === "Escape") {
+            event.preventDefault(); event.stopPropagation();
+            setText(String(value)); setError(""); onEditEnd();
+          }
+        }} />
+      {unit && <span className="parameter-unit" aria-hidden="true">{unit}</span>}
+    </span>
+    {error && createPortal(<span id={id} role="alert" className={showError ? "parameter-error" : "sr-only"} style={showError ? position : undefined}>{error}</span>, document.body)}
+  </Field>;
+}
+
 export function Field({
   label,
   children,

package/src/lib/use-file-session.ts

@@ -35,6 +35,8 @@ export function useFileSession(
   const reviewRef = useRef(review);
   const buildPending = useRef(false);
   const submittingBuild = useRef(false);
+  const loading = useRef(false);
+  const loadGeneration = useRef(0);
   const callbacksRef = useRef(callbacks);
   callbacksRef.current = callbacks;
   const draftRef = useRef(draft);
@@ -49,29 +51,15 @@ export function useFileSession(
 
   useEffect(() => {
     if (!enabled || !token) return;
-    let cancelled = false;
-    void loadFileSession(token).then((session) => {
-      if (cancelled) return;
-      state.current = {
-        ready: true,
-        revision: session.revision,
-        savedJSON: canonicalJSON(session.document),
-      };
-      setStatus("saved");
-      receiveReview(session.review);
-      callbacksRef.current.onOpen(session.document, session.name);
-    }).catch((error) => {
-      if (cancelled) return;
-      setStatus("error");
-      callbacksRef.current.onError(
-        error instanceof Error ? error.message : "Could not open the file-backed composition.",
-      );
-    });
-    return () => { cancelled = true; };
+    void reload();
+    return () => {
+      loadGeneration.current++;
+      loading.current = false;
+    };
   }, [enabled, token]);
 
   useEffect(() => {
-    if (!enabled || !state.current.ready || ["conflict", "error"].includes(status))
+    if (!enabled || !state.current.ready || ["loading", "conflict", "error"].includes(status))
       return;
     if (!validateComposition(draft).ok) return;
     const timer = window.setTimeout(() => { void save(draft); }, 250);
@@ -82,19 +70,20 @@ export function useFileSession(
     if (!enabled || !token) return;
     let cancelled = false;
     const timer = window.setInterval(() => {
-      if (!state.current.ready || state.current.drain || submittingBuild.current) return;
+      if (!state.current.ready || loading.current || state.current.drain || submittingBuild.current) return;
       const revision = state.current.revision;
+      const generation = loadGeneration.current;
       void loadFileSession(token).then((remote) => {
-        if (cancelled || state.current.drain || submittingBuild.current || revision !== state.current.revision) return;
+        if (cancelled || generation !== loadGeneration.current || loading.current || state.current.drain || submittingBuild.current || revision !== state.current.revision) return;
         receiveReview(remote.review);
-        setStatus(current => current === "error" ? "saved" : current);
+        if (canonicalJSON(draftRef.current) === state.current.savedJSON) {
+          setStatus("saved");
+          callbacksRef.current.onError("");
+        }
         if (remote.revision === revision) return;
         if (canonicalJSON(draftRef.current) !== state.current.savedJSON) {
           setStatus("conflict");
-          callbacksRef.current.onNotice(
-            "The file changed elsewhere. Neither version was overwritten.",
-            "error",
-          );
+          callbacksRef.current.onError("The file changed elsewhere. Your browser edits are not saved; neither version was overwritten.");
           return;
         }
         state.current = {
@@ -104,12 +93,10 @@ export function useFileSession(
         };
         setStatus("saved");
         callbacksRef.current.onExternalChange(remote.document);
-      }).catch(() => {
-        if (cancelled || submittingBuild.current || revision !== state.current.revision) return;
+      }).catch((error) => {
+        if (cancelled || generation !== loadGeneration.current || loading.current || state.current.drain || submittingBuild.current || revision !== state.current.revision) return;
         setStatus("error");
-        if (buildPending.current) {
-          callbacksRef.current.onNotice("Could not load the agent result. Check the local file service.", "error");
-        }
+        callbacksRef.current.onError(`Could not load the latest file. ${error instanceof Error ? error.message : "Check the local file service."}`);
       });
     }, 1000);
     return () => {
@@ -132,6 +119,7 @@ export function useFileSession(
   }
 
   async function noteAction(action: () => Promise<ReviewState>, saveFirst = false) {
+    if (loading.current || !state.current.ready) throw new Error("Wait for the file to open before submitting.");
     if (submittingBuild.current) throw new Error("Wait for the current save before submitting.");
     submittingBuild.current = true;
     try {
@@ -141,7 +129,8 @@ export function useFileSession(
   }
 
   function save(next: Draft): Promise<string | undefined> {
-    if (!token || !state.current.ready || activeRequest(reviewRef.current.request)) return Promise.resolve(undefined);
+    if (!token || loading.current || !state.current.ready || activeRequest(reviewRef.current.request)) return Promise.resolve(undefined);
+    if (!validateComposition(next).ok) return Promise.resolve(undefined);
     const serialized = canonicalJSON(next);
     if (serialized === state.current.savedJSON && !state.current.drain)
       return Promise.resolve(state.current.revision);
@@ -170,15 +159,15 @@ export function useFileSession(
         state.current.revision = result.revision;
         state.current.savedJSON = pending.serialized;
         setStatus("saved");
+        callbacksRef.current.onError("");
       } catch (error) {
         state.current.pending = undefined;
         const conflict = error instanceof FileSessionError && error.status === 409;
         setStatus(conflict ? "conflict" : "error");
-        callbacksRef.current.onNotice(
+        callbacksRef.current.onError(
           conflict
-            ? "The composition changed outside this browser. Your edits were not overwritten."
-            : error instanceof Error ? error.message : "Could not save the composition file.",
-          "error",
+            ? "The file changed elsewhere. Your browser edits are not saved; neither version was overwritten."
+            : `Changes are not saved. ${error instanceof Error ? error.message : "Could not save the composition file."}`,
         );
         return;
       }
@@ -191,7 +180,7 @@ export function useFileSession(
     componentId?: string,
     elementId?: string,
   ) {
-    if (!token || buildPending.current) return false;
+    if (!token || loading.current || !state.current.ready || buildPending.current) return false;
     if (submittingBuild.current) throw new Error("Wait for your note to finish saving before building.");
     buildPending.current = true;
     submittingBuild.current = true;
@@ -218,8 +207,41 @@ export function useFileSession(
     }
   }
 
+  async function reload() {
+    if (!token || loading.current || state.current.drain || submittingBuild.current) return;
+    loading.current = true;
+    const generation = ++loadGeneration.current;
+    const requestedJSON = canonicalJSON(draftRef.current);
+    setStatus("loading");
+    try {
+      const session = await loadFileSession(token);
+      if (generation !== loadGeneration.current) return;
+      if (canonicalJSON(draftRef.current) !== requestedJSON) {
+        setStatus("conflict");
+        callbacksRef.current.onError("Your browser edits changed while opening the file. Neither version was overwritten. Download JSON before loading the file again.");
+        return;
+      }
+      state.current = { ready: true, revision: session.revision, savedJSON: canonicalJSON(session.document) };
+      draftRef.current = session.document;
+      receiveReview(session.review);
+      callbacksRef.current.onOpen(session.document, session.name);
+      callbacksRef.current.onError("");
+      setStatus("saved");
+    } catch (error) {
+      if (generation !== loadGeneration.current) return;
+      setStatus("error");
+      callbacksRef.current.onError(error instanceof Error ? error.message : "Could not open the file.");
+    } finally {
+      if (generation === loadGeneration.current) loading.current = false;
+    }
+  }
+
   return {
     status, build, building, review,
+    opening: status === "loading",
+    ready: state.current.ready,
+    reload,
+    retry: () => state.current.ready && !activeRequest(reviewRef.current.request) ? save(draftRef.current) : reload(),
     addNote: (target: ReviewTarget, text: string) => noteAction(() => addNote(token!, target, text), true),
     removeNote: (id: string) => noteAction(() => removeNote(token!, id)),
     cancel: () => noteAction(() => cancelRequest(token!, reviewRef.current.request!.id)),

package/src/styles/base.css

@@ -17,6 +17,7 @@
   --ui-hover: #f2f2f2;
   --ui-selected: #edf6fa;
   --ui-shadow: 0 8px 28px #00000014, 0 1px 3px #00000012;
+  --ui-floating-shadow: 0 0 0 1px #0000000f, 0 2px 4px #00000006, 0 8px 24px #0000000a;
 }
 * {
   box-sizing: border-box;
@@ -52,6 +53,12 @@ button:disabled {
   cursor: default;
   color: #767676;
 }
+.right-panel input[type="number"],
+.revision-note-count,
+.overflow-trigger,
+.thumbnail-page-number {
+  font-variant-numeric: tabular-nums;
+}
 :focus-visible {
   outline: 2px solid var(--accent);
   outline-offset: 3px;