@drawnagency/primitives 0.1.113 → 0.1.114

package/src/components/shell/SiteSettingsDisplay.tsx

@@ -5,6 +5,7 @@ import { ColorPicker } from "../shared/ColorPicker";
 import { FontPicker } from "../shared/FontPicker";
 import { Input } from "../shared/Input";
 import { Select } from "../shared/Select";
+import { Textarea } from "../shared/Textarea";
 import { SubTabs } from "../shared/SubTabs";
 import { FormLabel } from "../shared/FormLabel";
 import { useMediaLibrary } from "./MediaLibraryContext";
@@ -12,22 +13,13 @@ import { contrastRatio, wcagLevel, suggestAccessibleOn } from "../../lib/contras
 import { cn } from "../../lib/cn";
 import { buildGoogleFontsUrl } from "../../lib/google-fonts";
 import type { SiteConfig } from "../../schemas/site-config";
-import type { MediaItem } from "../../media/types";
+import { imageThumbnailUrl } from "../../media/utils";
 
 interface Props {
   siteConfig: SiteConfig;
   onChange: (config: SiteConfig) => void;
 }
 
-// Smallest generated variant for the editor-preview thumbnail (mirrors
-// DocInspector's thumbSrc) — avoids needing a MediaProvider in this context.
-function thumbSrc(imageId: string, item: MediaItem | undefined): string | null {
-  if (!item || item.kind !== "image") return null;
-  if (item.mimeType === "image/svg+xml") return `/api/media/${imageId}/original.svg`;
-  const widths = item.variants.map((v) => v.width).sort((a, b) => a - b);
-  if (widths.length === 0) return null;
-  return `/api/media/${imageId}/${widths[0]}.webp`;
-}
 
 const darkModeOptions = [
   { label: "Light", value: "light" },
@@ -63,7 +55,7 @@ function ContrastRow({ label, entries }: { label: string; entries: ContrastEntry
       <span className="text-base-contrast-light">{label}</span>
       {entries.map((e) => {
         const level = wcagLevel(e.ratio);
-        const tone = level.aa ? "text-green-600" : level.aaLarge ? "text-amber-600" : "text-red-600";
+        const tone = level.aa ? "text-success" : level.aaLarge ? "text-warning" : "text-danger";
         const mark = level.aa ? "AA" : level.aaLarge ? "large only" : "fail";
         return (
           <span key={e.mode} className="inline-flex items-center gap-1">
@@ -154,16 +146,14 @@ export function SiteSettingsDisplay({ siteConfig, onChange }: Props) {
       />
 
       <div>
-        <FormLabel htmlFor="site-description">Description</FormLabel>
-        <textarea
-          id="site-description"
+        <Textarea
+          label="Description"
           aria-label="Site description"
           rows={2}
           maxLength={300}
           value={siteConfig.description ?? ""}
-          onChange={(e) => update({ description: e.target.value || null })}
+          onChange={(value) => update({ description: value || null })}
           placeholder="Short summary for search results and social shares."
-          className="w-full rounded border border-base-200 bg-base px-3 py-2 text-sm text-base-contrast"
         />
         <div className="mt-1 flex items-start justify-between gap-2">
           <p className="text-xs text-base-contrast/70">
@@ -214,13 +204,13 @@ export function SiteSettingsDisplay({ siteConfig, onChange }: Props) {
           )}
         </div>
         <p className="mt-1 text-xs text-base-contrast/70">SVG or PNG, up to 100KB. Shown in browser tabs.</p>
-        {faviconError && <p className="mt-1 text-xs text-red-600">{faviconError}</p>}
+        {faviconError && <p className="mt-1 text-xs text-danger">{faviconError}</p>}
       </div>
 
       {(() => {
         const logo = siteConfig.logo;
-        const lightSrc = logo ? thumbSrc(logo.light.imageId, mediaLibrary?.manifest.images[logo.light.imageId]) : null;
-        const darkSrc = logo?.dark ? thumbSrc(logo.dark.imageId, mediaLibrary?.manifest.images[logo.dark.imageId]) : null;
+        const lightSrc = logo ? imageThumbnailUrl(mediaLibrary?.manifest.images[logo.light.imageId]) : null;
+        const darkSrc = logo?.dark ? imageThumbnailUrl(mediaLibrary?.manifest.images[logo.dark.imageId]) : null;
         const needsDarkHint = logo != null && siteConfig.darkMode !== "light" && !logo.dark && !logo.invertInDark;
 
         return (
@@ -302,7 +292,7 @@ export function SiteSettingsDisplay({ siteConfig, onChange }: Props) {
                 />
 
                 {needsDarkHint && (
-                  <p className="text-xs text-amber-600">
+                  <p className="text-xs text-warning">
                     Add a dark variant or enable invert so the logo stays legible in dark mode.
                   </p>
                 )}

package/src/components/shell/SiteSettingsModal.tsx

@@ -7,6 +7,8 @@ import { SiteSettingsDisplay } from "./SiteSettingsDisplay";
 import { SiteSettingsUsers } from "./SiteSettingsUsers";
 import { SiteSettingsChatbot } from "./SiteSettingsChatbot";
 import { SiteSettingsDecks } from "./SiteSettingsDecks";
+import { SiteSettingsTags } from "./SiteSettingsTags";
+import type { SiteTagging } from "../../lib/registry";
 import type { SiteConfig } from "../../schemas/site-config";
 import type { Audience } from "../../auth/types";
 
@@ -27,9 +29,13 @@ interface Props {
     passwordToggle: boolean;
   };
   currentUser: { email: string; role: "owner" | "editor" } | null;
+  tagging: SiteTagging;
 }
 
-export function SiteSettingsModal({ isOpen, onClose, siteConfig, onSiteConfigChange, onAudiencesChange, audiences, chatbotPlatformEnabled, capabilities, currentUser }: Props) {
+export function SiteSettingsModal({
+  isOpen, onClose, siteConfig, onSiteConfigChange, onAudiencesChange, audiences, chatbotPlatformEnabled, capabilities, currentUser,
+  tagging,
+}: Props) {
   const [signOutError, setSignOutError] = useState<string | null>(null);
 
   async function handleSignOut() {
@@ -92,6 +98,22 @@ export function SiteSettingsModal({ isOpen, onClose, siteConfig, onSiteConfigCha
         </div>
       ),
     },
+    {
+      id: "tags",
+      label: "Tags",
+      show: true,
+      content: (
+        <div data-testid="site-settings-tab-panel" className="flex flex-1 flex-col overflow-y-auto px-6 py-4">
+          <SiteSettingsTags
+            tags={tagging.tags}
+            editable={tagging.editable}
+            onCreate={(label) => tagging.onCreate(label)}
+            onRename={tagging.onRename}
+            onDelete={tagging.onDelete}
+          />
+        </div>
+      ),
+    },
     {
       id: "display",
       label: "Display",
@@ -130,7 +152,7 @@ export function SiteSettingsModal({ isOpen, onClose, siteConfig, onSiteConfigCha
                 <span className="ml-1 capitalize">({currentUser.role})</span>
               )}
               {signOutError && (
-                <span className="ml-2 text-red-600">— {signOutError}</span>
+                <span className="ml-2 text-danger">— {signOutError}</span>
               )}
             </div>
             <Button

package/src/components/shell/SiteSettingsTags.tsx

@@ -0,0 +1,143 @@
+import { useRef, useState, type FormEvent } from "react";
+import { pluralize } from "../../lib/text";
+import { findTagByLabel, tagDisplayLabel } from "../../lib/tags";
+import type { TagEntry } from "../../schemas/tags";
+import { Button } from "../shared/Button";
+import { ConfirmInline } from "../shared/ConfirmInline";
+import { Input } from "../shared/Input";
+
+interface Props {
+  /** The site's tag registry, already reconciled (siteTags). */
+  tags: TagEntry[];
+  /** False when the registry was never loaded, or loaded degraded; the tab then edits nothing. */
+  editable: boolean;
+  onCreate: (label: string) => void;
+  onRename: (tagId: string, label: string) => void;
+  onDelete: (tagId: string) => void;
+}
+
+export function SiteSettingsTags({ tags, editable, onCreate, onRename, onDelete }: Props) {
+  const [draft, setDraft] = useState("");
+  const [error, setError] = useState<string | null>(null);
+
+  function submit(e: FormEvent) {
+    e.preventDefault();
+    const label = draft.trim();
+    if (!label) return;
+    if (findTagByLabel(tags, label)) {
+      setError(`A tag named "${label}" already exists.`);
+      return;
+    }
+    onCreate(label);
+    setDraft("");
+    setError(null);
+  }
+
+  const header = (
+    <div>
+      <h3 className="mb-1 text-sm font-medium text-base-contrast">Section tags</h3>
+      <p className="text-xs text-base-contrast-light">
+        Tags group related sections across pages. Put them on a section from the Tags pill above it. Viewers never see
+        tag names.
+      </p>
+    </div>
+  );
+
+  if (!editable) {
+    return (
+      <div className="space-y-4">
+        {header}
+        <p className="text-xs text-danger">Tags could not be loaded in full for this session, so they are read-only. Reload the editor to manage them.</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-4">
+      {header}
+
+      <form onSubmit={submit} className="flex items-start gap-2">
+        <Input
+          label="New tag"
+          hideLabel
+          className="flex-1"
+          value={draft}
+          placeholder="New tag name"
+          error={error ?? undefined}
+          onChange={(v) => { setDraft(v); setError(null); }}
+        />
+        <Button type="submit" variant="secondary">Add tag</Button>
+      </form>
+
+      {tags.length === 0 ? (
+        <p className="text-xs text-base-contrast-light">No tags yet.</p>
+      ) : (
+        <ul className="space-y-2">
+          {tags.map((t) => (
+            <TagRow
+              key={t.id}
+              tag={t}
+              duplicate={t.label.trim() !== "" && findTagByLabel(tags, t.label)?.id !== t.id}
+              onRename={(label) => onRename(t.id, label)}
+              onDelete={() => onDelete(t.id)}
+            />
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+function TagRow({ tag, duplicate, onRename, onDelete }: {
+  tag: TagEntry;
+  /** An earlier tag already has this name — inline creates would pick that one. */
+  duplicate: boolean;
+  onRename: (label: string) => void;
+  onDelete: () => void;
+}) {
+  const [confirming, setConfirming] = useState(false);
+  const deleteRef = useRef<HTMLButtonElement>(null);
+  const count = tag.sectionIds.length;
+  const name = tagDisplayLabel(tag.label);
+
+  return (
+    <li className="rounded-md border border-base-200 px-3 py-2">
+      <div className="flex items-center gap-3">
+        <Input
+          label="Tag name"
+          hideLabel
+          className="min-w-0 flex-1"
+          value={tag.label}
+          placeholder="Untitled tag"
+          error={duplicate ? "Another tag already has this name." : undefined}
+          onChange={onRename}
+        />
+        <span className="shrink-0 text-xs text-base-contrast/60">{pluralize(count, "section")}</span>
+        {!confirming && (
+          <Button
+            ref={deleteRef}
+            variant="destructive"
+            size="sm"
+            aria-label={`Delete tag ${name}`}
+            onClick={() => (count === 0 ? onDelete() : setConfirming(true))}
+          >
+            Delete
+          </Button>
+        )}
+      </div>
+      {confirming && (
+        <div className="mt-2">
+          <ConfirmInline
+            message={`Delete "${name}"? It is removed from ${pluralize(count, "section")}. The sections themselves stay.`}
+            confirmLabel="Delete"
+            confirmAriaLabel="Confirm delete"
+            tone="destructive"
+            onConfirm={onDelete}
+            onCancel={() => setConfirming(false)}
+            returnFocusTo={deleteRef}
+          />
+        </div>
+      )}
+    </li>
+  );
+}

package/src/components/shell/SiteSettingsUsers.tsx

@@ -1,7 +1,9 @@
-import { Fragment, useState, useEffect, type FormEvent } from "react";
+import { Fragment, useRef, useState, useEffect, type FormEvent, type RefObject } from "react";
 import { ChevronDown } from "lucide-react";
 import type { Role } from "../../auth/types";
 import { Button } from "../shared/Button";
+import { ConfirmInline } from "../shared/ConfirmInline";
+import { Input } from "../shared/Input";
 
 interface User {
   id: string;
@@ -21,12 +23,25 @@ export function SiteSettingsUsers({ currentUser }: Props) {
   const [inviteRole, setInviteRole] = useState<Role>("editor");
   const [error, setError] = useState<string | null>(null);
   const [confirmingRevoke, setConfirmingRevoke] = useState<string | null>(null);
+  // One stable ref object per user, so a row's Remove button and its
+  // ConfirmInline share the same object across the swap — the button
+  // reattaches to it (layout phase) before ConfirmInline's cleanup effect
+  // (passive phase) reads it back to return focus.
+  const removeButtonRefs = useRef(new Map<string, RefObject<HTMLButtonElement | null>>());
+  function getRemoveButtonRef(userId: string): RefObject<HTMLButtonElement | null> {
+    let ref = removeButtonRefs.current.get(userId);
+    if (!ref) {
+      ref = { current: null };
+      removeButtonRefs.current.set(userId, ref);
+    }
+    return ref;
+  }
 
   async function loadUsers() {
     try {
       const res = await fetch("/api/auth/users");
       if (!res.ok) {
-        setError("Failed to load users");
+        setError("Couldn't load users");
         setUsers([]);
         return;
       }
@@ -163,27 +178,10 @@ export function SiteSettingsUsers({ currentUser }: Props) {
             <div className="flex items-center justify-end border-b border-base-200 py-2">
               {currentUser?.email === user.email ? (
                 <span className="text-xs text-base-contrast-light">—</span>
-              ) : confirmingRevoke === user.id ? (
-                <span className="flex items-center gap-1">
-                  <Button
-                    type="button"
-                    variant="ghost"
-                    tone="destructive"
-                    onClick={() => confirmRevoke(user.id)}
-                  >
-                    Confirm
-                  </Button>
-                  <Button
-                    type="button"
-                    variant="ghost"
-                    onClick={() => setConfirmingRevoke(null)}
-                  >
-                    Cancel
-                  </Button>
-                </span>
-              ) : (
+              ) : confirmingRevoke === user.id ? null : (
                 <Button
                   type="button"
+                  ref={getRemoveButtonRef(user.id)}
                   variant="ghost"
                   tone="destructive"
                   onClick={() => handleRevoke(user.id)}
@@ -192,20 +190,32 @@ export function SiteSettingsUsers({ currentUser }: Props) {
                 </Button>
               )}
             </div>
+            {confirmingRevoke === user.id && (
+              <div className="col-span-3 pb-2">
+                <ConfirmInline
+                  message={`Remove ${user.email}?`}
+                  confirmLabel="Remove"
+                  tone="destructive"
+                  onConfirm={() => confirmRevoke(user.id)}
+                  onCancel={() => setConfirmingRevoke(null)}
+                  returnFocusTo={getRemoveButtonRef(user.id)}
+                />
+              </div>
+            )}
           </Fragment>
         ))}
       </div>
 
       <form onSubmit={handleInvite} className="grid grid-cols-[1fr_7rem_5rem] text-sm">
         <div className="pr-2">
-          <input
+          <Input
+            label="Email address"
+            hideLabel
             type="email"
             placeholder="Email address"
             value={inviteEmail}
-            onChange={(e) => setInviteEmail(e.target.value)}
+            onChange={setInviteEmail}
             required
-            aria-label="Email address"
-            className="w-full rounded border border-base-200 bg-base px-3 py-2 text-sm text-base-contrast focus:border-base-contrast focus:outline-none focus:ring-1 focus:ring-base-contrast"
           />
         </div>
         <div className="pr-2">
@@ -234,7 +244,7 @@ export function SiteSettingsUsers({ currentUser }: Props) {
         Role changes take effect the next time the user signs in, or within 24 hours.
       </p>
 
-      {error && <p className="text-sm text-red-600">{error}</p>}
+      {error && <p className="text-sm text-danger">{error}</p>}
     </div>
   );
 }

package/src/components/shell/SiteSettingsViewerAccess.tsx

@@ -153,7 +153,7 @@ export function SiteSettingsViewerAccess({ audienceManagement, passwordToggle, o
   // Deliberately a hard stop rather than an empty list: rendering the normal UI
   // here would show "no audiences" for a site that has them.
   if (loadError) {
-    return <p className="text-sm text-red-600">{loadError}</p>;
+    return <p className="text-sm text-danger">{loadError}</p>;
   }
 
   return (
@@ -182,7 +182,7 @@ export function SiteSettingsViewerAccess({ audienceManagement, passwordToggle, o
                 ? "Viewers must sign in with a username and password to see any content."
                 : "Viewers must select an audience and enter a password to see any content."}
           </p>
-          {toggleError && <p className="text-xs text-red-600">{toggleError}</p>}
+          {toggleError && <p className="text-xs text-danger">{toggleError}</p>}
         </div>
       )}
 

package/src/components/shell/ViewerLoginForm.tsx

@@ -3,7 +3,8 @@ import { Input } from "../shared/Input";
 import { PasswordInput } from "../shared/PasswordInput";
 import { Button } from "../shared/Button";
 import { Select } from "../shared/Select";
-import { safeRedirect } from "../../lib/safeRedirect";
+import { safeRedirect } from "../../lib/safe-redirect";
+import { COPY } from "../shared/copy";
 
 interface Props {
   /** Audience mode only. Empty (and unused) in credential mode — the page must
@@ -55,7 +56,7 @@ export function ViewerLoginForm({ audiences, mode = "audience", next }: Props) {
 
       if (!response.ok) {
         const data = await response.json().catch(() => ({}));
-        setError(data.error || "Access denied");
+        setError(data.error || COPY.auth.signInFallback);
         return;
       }
 
@@ -99,7 +100,7 @@ export function ViewerLoginForm({ audiences, mode = "audience", next }: Props) {
         )}
 
         {error && (
-          <p className="text-sm text-red-600">{error}</p>
+          <p className="text-sm text-danger">{error}</p>
         )}
 
         <Button
@@ -108,7 +109,7 @@ export function ViewerLoginForm({ audiences, mode = "audience", next }: Props) {
           size="md"
           disabled={loading || (credentialMode ? username.trim().length === 0 : !audience)}
           isLoading={loading}
-          loadingLabel="Verifying..."
+          loadingLabel="Verifying…"
           className="w-full"
         >
           Enter

package/src/components/shell/reference-sources.ts

@@ -0,0 +1,36 @@
+import type { Audience } from "../../schemas/auth";
+import type { SiteIndex } from "../../schemas/site-config";
+import type { LoadedSection } from "../../lib/loader";
+import type { MediaManifest } from "../../media/types";
+import { pageById } from "../../lib/pages";
+import { pageReferenceCopies } from "../../lib/nav";
+import type { ReferenceSources } from "../shared/ReferenceSourcesContext";
+
+/**
+ * What References resolve against in the Published preview: main's content
+ * (`viewIndex` once the history/view fetch lands, else the `mainIndex` the
+ * load reported), live sections only — the same content and page the viewer
+ * would expand. Null when there is no published view to resolve against, and
+ * the canvas falls back to the working copy.
+ */
+export function publishedReferenceSources(opts: {
+  viewSections: LoadedSection[] | null;
+  viewIndex: SiteIndex | null;
+  mainIndex: SiteIndex | null;
+  activePageId: string | null;
+  audiences: Audience[];
+  mediaManifest: MediaManifest;
+  jumpToSection: (sectionId: string) => void;
+}): ReferenceSources | null {
+  const { viewSections, activePageId, audiences, mediaManifest, jumpToSection } = opts;
+  const index = opts.viewIndex ?? opts.mainIndex;
+  if (!viewSections || !index || !activePageId) return null;
+  const byId = new Map(viewSections.map((s) => [s.section.id, s]));
+  const pageSections = (pageById(index, activePageId)?.order ?? [])
+    .flatMap((id) => byId.get(id) ?? [])
+    .filter((s) => s.meta.status === "live");
+  return {
+    index, sections: viewSections, audiences, mediaManifest, jumpToSection,
+    copies: pageReferenceCopies(pageSections, { index, allSections: viewSections }),
+  };
+}

package/src/deck/index.ts

@@ -25,6 +25,6 @@ export {
   type DeckMediaAsset,
   type DeckMediaResolver,
 } from "./media";
-export { DeckTextEditProvider, EditableText, useDeckTextEditor, type DeckTextEditor } from "./editing";
+export { DeckTextEditProvider, EditableText, type DeckTextEditor } from "./editing";
 export { useStageScale } from "./useStageScale";
-export { deckAlign, surfaceInk, DECK_ELEVATION, SURFACE_BACKGROUND, type DeckAlign, type DeckSurface } from "./tokens";
+export { deckAlign, surfaceInk, DECK_ELEVATION, SURFACE_BACKGROUND, type DeckSurface } from "./tokens";

package/src/document/index.ts

@@ -6,7 +6,7 @@ export * from "./engine/settings";
 export { splitProseBlocks } from "./engine/blocks";
 export { harvest } from "./engine/harvest";
 export * from "./engine/paginate";
-export { layoutMasonryPage, type MasonryOpts, type MasonryBox, type Sized } from "./engine/masonry";
+export { layoutMasonryPage, type MasonryOpts, type Sized } from "./engine/masonry";
 
 export { DocPage, type DocMeta } from "./components/DocPage";
 export { DocSectionPage, type DocHost } from "./components/DocSectionPage";
@@ -14,5 +14,5 @@ export { DocCoverPage } from "./components/DocCoverPage";
 export { useDocPages } from "./components/useDocPages";
 
 // Task 3 — shared document shell (presentation + editing).
-export { DocViewer, type DocViewerProps } from "./components/DocViewer";
+export { DocViewer } from "./components/DocViewer";
 export { DocRail, entryId, type RailEntry } from "./components/DocRail";

package/src/hooks/useBlockDnd.ts

@@ -15,6 +15,17 @@ export interface UseBlockDndArgs {
 }
 
 /**
+ * One of three sibling drag-and-drop position hooks, split by location type
+ * rather than unified behind a generic `useSortable({ axis })`: this one
+ * (block/container id + index — the section canvas, root and nested),
+ * `useSortableRow` (flat index — section-ordering lists), and
+ * `useSortableNavRow` (NavLocation — the Pages modal's group-aware nav tree).
+ * A fourth location type earns its own hook on the same shape (rowRef/
+ * handleRef, lazy atlaskit import, closest-edge state, a ref for the latest
+ * callback) rather than a parameter bag bolted onto an existing one — see
+ * docs/superpowers/specs/2026-09-04-editor-ui-primitives-consolidation.md
+ * § D6 for why a shared `useSortable` was deferred.
+ *
  * Wires a block as a unified drag source + drop target. Manages only this block's
  * local hover edge + dragging flag — the actual move dispatch is centralized in the
  * EditorContent monitor (a later task), so nested targets never double-fire. The edge

package/src/hooks/useBuildStatus.ts

@@ -12,7 +12,7 @@ interface BuildStatusResponse {
 interface BuildStatusResult {
   state: BuildState;
   elapsedSeconds: number;
-  startTracking: () => void;
+  startTracking: (commitSha?: string) => void;
   dismiss: () => void;
 }
 
@@ -40,6 +40,15 @@ export function useBuildStatus(): BuildStatusResult {
   const fadeRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);
   const giveUpRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const expectedCommit = useRef<string | null>(null);
+  // Commits already on the status row when tracking began (an earlier build,
+  // possibly still running) versus commits first seen building afterwards (a
+  // later publish by a peer or the MCP connector, which supersedes ours).
+  const firstTrackedPoll = useRef(false);
+  const preexistingCommits = useRef(new Set<string>());
+  const laterBuilds = useRef(new Set<string>());
+  const trackingGeneration = useRef(0);
+  const pollInFlight = useRef(false);
   const isPolling = useRef(false);
   const mountedRef = useRef(true);
 
@@ -80,7 +89,7 @@ export function useBuildStatus(): BuildStatusResult {
 
   const fetchStatus = useCallback(async (): Promise<BuildStatusResponse | null> => {
     try {
-      const res = await fetch("/api/build-status");
+      const res = await fetch("/api/build-status", { signal: AbortSignal.timeout(10_000) });
       if (!res.ok) return null;
       const data = await res.json();
       const validStates = ["building", "ready", "error"];
@@ -107,6 +116,29 @@ export function useBuildStatus(): BuildStatusResult {
         return;
       }
 
+      const expected = expectedCommit.current;
+      if (expected && data.commitSha && data.commitSha !== expected) {
+        // Netlify builds serially, so a different commit is either an older
+        // build finishing late or a newer publish. No clock can tell them apart
+        // (the row is server time, this is browser time), so go by order seen:
+        // accept a different commit's result only if it began building after
+        // tracking did. A provider that reports no commit is accepted as-is.
+        const commit = data.commitSha;
+        const first = firstTrackedPoll.current;
+        firstTrackedPoll.current = false;
+        if (first || preexistingCommits.current.has(commit)) {
+          preexistingCommits.current.add(commit);
+          return;
+        }
+        if (data.state === "building") {
+          laterBuilds.current.add(commit);
+          return;
+        }
+        if (!laterBuilds.current.has(commit)) return;
+      } else if (expected) {
+        firstTrackedPoll.current = false;
+      }
+
       setState(data.state);
 
       if (data.state === "ready" || data.state === "error") {
@@ -133,8 +165,13 @@ export function useBuildStatus(): BuildStatusResult {
     isPolling.current = true;
 
     pollRef.current = setInterval(async () => {
-      const data = await fetchStatus();
-      handleStatusUpdate(data, false);
+      if (pollInFlight.current) return;
+      pollInFlight.current = true;
+      const generation = trackingGeneration.current;
+      try {
+        const data = await fetchStatus();
+        if (generation === trackingGeneration.current && isPolling.current) handleStatusUpdate(data, false);
+      } finally { pollInFlight.current = false; }
     }, POLL_INTERVAL);
   }, [fetchStatus, handleStatusUpdate]);
 
@@ -148,9 +185,10 @@ export function useBuildStatus(): BuildStatusResult {
     // real remount in production.
     mountedRef.current = true;
 
+    const initialGeneration = trackingGeneration.current;
     async function check() {
       const data = await fetchStatus();
-      if (cancelled) return;
+      if (cancelled || initialGeneration !== trackingGeneration.current) return;
 
       if (data && data.state === "building") {
         const ageMs = Date.now() - Date.parse(data.updatedAt);
@@ -183,7 +221,13 @@ export function useBuildStatus(): BuildStatusResult {
     };
   }, [fetchStatus, handleStatusUpdate, startPolling, startTimer, stopPolling, stopTimer, armGiveUp, clearGiveUp]);
 
-  const startTracking = useCallback(() => {
+  const startTracking = useCallback((commitSha?: string) => {
+    trackingGeneration.current++;
+    expectedCommit.current = commitSha ?? null;
+    firstTrackedPoll.current = true;
+    preexistingCommits.current = new Set();
+    laterBuilds.current = new Set();
+    if (fadeRef.current) { clearTimeout(fadeRef.current); fadeRef.current = null; }
     if (clearRef.current) { clearTimeout(clearRef.current); clearRef.current = null; }
     setState("building");
     startTimer();
@@ -192,6 +236,9 @@ export function useBuildStatus(): BuildStatusResult {
   }, [startPolling, startTimer, armGiveUp]);
 
   const dismiss = useCallback(() => {
+    trackingGeneration.current++;
+    expectedCommit.current = null;
+    if (fadeRef.current) { clearTimeout(fadeRef.current); fadeRef.current = null; }
     if (clearRef.current) { clearTimeout(clearRef.current); clearRef.current = null; }
     setState("idle");
     stopPolling();

package/src/hooks/useDocumentUploads.ts

@@ -32,7 +32,7 @@ interface UseDocumentUploadsInput {
    *  invisible here, so without this the dedup below cannot tell a live
    *  document from a doomed one. No-op for an id that isn't doomed. */
   undeleteDocument?: (id: string) => void;
-  /** Same channel the media pipeline uses — surfaces in UploadRejectionAlert. */
+  /** Same channel the media pipeline uses — surfaces in InlineAlert. */
   onUploadError?: (message: string) => void;
 }