@drawnagency/primitives 0.1.76 → 0.1.77

package/src/collab/rebase.ts

@@ -0,0 +1,140 @@
+// rebase.ts — pure-function rebase merge: fold a fresh remote (saved-branch)
+// content snapshot under local unsaved work. Consumed by the 409 auto-recovery
+// path and the live save-sync path (both in core); no I/O here.
+import type { LoadedSection } from "../lib/loader";
+import type { SiteIndex } from "../schemas/site-config";
+
+export interface RebaseArgs {
+  localSections: LoadedSection[];
+  localIndex: SiteIndex;
+  localIndexDirty: boolean;
+  dirtySectionIds: Set<string>;
+  /** Section ids created locally since the last clean baseline (i.e. dirty ids
+   *  absent from the last-loaded saved-branch index). Callers derive this from
+   *  the cached clean baseline (Dexie contentCache index), NOT from remoteIndex —
+   *  remote absence is exactly what this field disambiguates: without it, a
+   *  locally-added unsaved section is indistinguishable from a section deleted
+   *  remotely while dirty (both dirty, present locally, absent remotely). */
+  locallyAddedIds: Set<string>;
+  locallyDeletedIds: Set<string>;
+  remoteSections: LoadedSection[];
+  remoteIndex: SiteIndex;
+  // Sections the remote save changed (from SavedMessage, or a diff on 409
+  // recovery). Remote deletions of dirty sections are detected directly from
+  // remoteIndex, so callers need not fold deletedSectionIds in — but doing so
+  // is harmless.
+  remoteChangedIds: Set<string>;
+}
+
+export interface RebaseResult {
+  sections: LoadedSection[];
+  index: SiteIndex;
+  // dirty locally AND changed (or deleted) remotely — needs user choice.
+  // Never contains locally-added unsaved ids (see locallyAddedIds) or
+  // locally-deleted ids.
+  conflictIds: string[];
+}
+
+/** Merge a fresh remote (saved-branch) snapshot under local unsaved work.
+ *  Remote wins everywhere the local editor has no unsaved edits; dirty local
+ *  sections are kept verbatim; overlaps are reported as conflicts for the
+ *  caller's keep-mine/take-theirs dialog. Implements the 5 merge rules from
+ *  the collaboration spec ("conflict-free by construction under lock
+ *  discipline").
+ *
+ *  Invariants: inputs are never mutated (the returned index is a fresh
+ *  structure in both branches), and the result partitions: every section in
+ *  `sections` is reachable from `index`; a dirty section deleted remotely is
+ *  kept, re-linked into the index, and reported in `conflictIds`. */
+export function rebaseContent(args: RebaseArgs): RebaseResult {
+  const localById = new Map(args.localSections.map((s) => [s.section.id, s]));
+  const remoteIds = new Set(args.remoteSections.map((s) => s.section.id));
+
+  // Rules 1-3: remote baseline (in remote order), overlay local-dirty
+  // sections, drop locally-deleted ids. The append loop also skips locally
+  // deleted ids — a section edited THEN deleted locally must stay deleted.
+  const merged: LoadedSection[] = args.remoteSections
+    .filter((s) => !args.locallyDeletedIds.has(s.section.id))
+    .map((s) => (args.dirtySectionIds.has(s.section.id) ? (localById.get(s.section.id) ?? s) : s));
+  for (const id of args.dirtySectionIds) {
+    if (remoteIds.has(id) || args.locallyDeletedIds.has(id)) continue;
+    const local = localById.get(id);
+    if (local) merged.push(local); // locally-added, or dirty survivor of a remote deletion
+  }
+
+  // Rule 4: conflicts = dirty ∩ remote-changed, PLUS dirty survivors of a
+  // remote deletion (present locally, absent from remoteIndex) — detected
+  // here directly; the caller is not trusted to fold remote deletions into
+  // remoteChangedIds. Locally-added ids are excluded from the deletion
+  // backstop: they are absent remotely because they were never saved, not
+  // because anyone deleted them.
+  const conflictSet = new Set<string>();
+  for (const id of args.dirtySectionIds) {
+    if (args.locallyDeletedIds.has(id)) continue; // dropped above; nothing to resolve
+    if (args.remoteChangedIds.has(id)) {
+      conflictSet.add(id);
+    } else if (localById.has(id) && !(id in args.remoteIndex.sections) && !args.locallyAddedIds.has(id)) {
+      conflictSet.add(id); // deleted remotely while dirty locally
+    }
+  }
+  const conflictIds = [...conflictSet].sort();
+
+  // Rule 5: index merge. Both branches build a fresh structure (fresh page
+  // objects, fresh order arrays, fresh sections map) so the invariant repair
+  // below never mutates an input.
+  let index: SiteIndex;
+  if (!args.localIndexDirty) {
+    index = {
+      ...args.remoteIndex,
+      pages: args.remoteIndex.pages.map((p) => ({ ...p, order: [...p.order] })),
+      sections: { ...args.remoteIndex.sections },
+    };
+  } else {
+    const localOrderIds = new Set(args.localIndex.pages.flatMap((p) => p.order));
+
+    // Local wins: drop ids that are absent from both the remote index and
+    // the local dirty/added set (deleted remotely, not something we're
+    // actively editing).
+    const pages = args.localIndex.pages.map((p) => ({
+      ...p,
+      order: p.order.filter((id) => id in args.remoteIndex.sections || args.dirtySectionIds.has(id)),
+    }));
+    const sections: SiteIndex["sections"] = {};
+    for (const [id, meta] of Object.entries(args.localIndex.sections)) {
+      if (id in args.remoteIndex.sections || args.dirtySectionIds.has(id)) sections[id] = meta;
+    }
+
+    // Reconcile: append remote-new ids (present remotely, absent locally) to
+    // the local page occupying the same page id remotely; fall back to the
+    // first local page if that page id doesn't exist locally. Never creates
+    // a new page.
+    for (const remotePage of args.remoteIndex.pages) {
+      for (const id of remotePage.order) {
+        if (localOrderIds.has(id) || args.locallyDeletedIds.has(id)) continue;
+        const target = pages.find((p) => p.id === remotePage.id) ?? pages[0];
+        if (target && !target.order.includes(id)) target.order.push(id);
+        sections[id] = args.remoteIndex.sections[id];
+      }
+    }
+
+    index = { ...args.localIndex, pages, sections };
+  }
+
+  // Partition invariant (unconditional): every id in `merged` must be
+  // reachable from `index`. The only ids that can be missing are dirty
+  // survivors of a remote deletion — re-link each where the local index had
+  // it (else the first page), with its local index meta, falling back to the
+  // validated meta the LoadedSection itself carries.
+  for (const s of merged) {
+    const id = s.section.id;
+    if (id in index.sections) continue;
+    const meta = args.localIndex.sections[id] ?? s.meta;
+    const localPage = args.localIndex.pages.find((p) => p.order.includes(id));
+    const target = (localPage && index.pages.find((p) => p.id === localPage.id)) ?? index.pages[0];
+    if (!target) continue;
+    if (!target.order.includes(id)) target.order.push(id);
+    index.sections[id] = meta;
+  }
+
+  return { sections: merged, index, conflictIds };
+}

package/src/collab/recovery.ts

@@ -0,0 +1,149 @@
+// recovery.ts — pure functions for the 409 auto-recovery path. The EditorShell
+// keeps only IO glue (fetch, Dexie, setState); everything decision-shaped lives
+// here so it can be unit-tested directly with injected data.
+import type { LoadedSection } from "../lib/loader";
+import type { Section, SectionContent } from "../schemas/sections";
+import type { SiteIndex } from "../schemas/site-config";
+
+/** The last CLEAN saved-branch snapshot (no local dirty overlays folded in).
+ *  Lifecycle: primed by loadContent, re-primed with the committed snapshot on
+ *  every successful save, and re-primed with the fetched remote snapshot on
+ *  every recovery — so it is always the editor's last agreed-with-server state. */
+export interface RecoveryBaseline {
+  sections: LoadedSection[];
+  index: SiteIndex;
+}
+
+/** Derive rebaseContent's remoteChangedIds + locallyAddedIds from a clean
+ *  baseline and the freshly fetched remote snapshot.
+ *
+ *  - remoteChangedIds: sections whose content differs between the clean baseline
+ *    and the fresh remote. The baseline MUST be clean — diffing against the dirty
+ *    in-memory view would flag every locally-edited section as remote-changed,
+ *    turning every dirty section into a false conflict.
+ *  - locallyAddedIds: dirty ids absent from the clean baseline INDEX — sections
+ *    created locally and never saved. This is what lets rebase distinguish a
+ *    local add from a section deleted remotely while dirty.
+ *
+ *  Degraded mode (baseline === null — should be unreachable, since every load,
+ *  save, and recovery re-primes the cache): fail SAFE, not silent. Every dirty
+ *  section that still exists remotely is flagged remote-changed (forcing the
+ *  keep-mine/take-theirs dialog instead of a silent local-wins merge), and every
+ *  dirty section absent remotely is treated as locally added (kept — a true
+ *  remote-deletion-while-dirty resurrects instead of conflicting, which loses
+ *  nothing). This is deliberately NOT derived from the published mainIndex: a
+ *  main-based baseline would silently local-win every dirty section that already
+ *  exists on main — the exact lost-update this path exists to prevent. */
+export function deriveRecoveryInputs({ baseline, remote, dirtyRows, deletedIds }: {
+  baseline: RecoveryBaseline | null;
+  remote: { sections: LoadedSection[]; index: SiteIndex };
+  dirtyRows: { sectionId: string }[];
+  deletedIds: Set<string>;
+}): { remoteChangedIds: Set<string>; locallyAddedIds: Set<string> } {
+  // Locally deleted ids are dropped by rebase regardless; keep them out of both
+  // derived sets so a delete never masquerades as an add or a conflict.
+  const dirtyIds = new Set(dirtyRows.map((r) => r.sectionId).filter((id) => !deletedIds.has(id)));
+
+  if (!baseline) {
+    return {
+      remoteChangedIds: new Set([...dirtyIds].filter((id) => id in remote.index.sections)),
+      locallyAddedIds: new Set([...dirtyIds].filter((id) => !(id in remote.index.sections))),
+    };
+  }
+
+  const baselineById = new Map(baseline.sections.map((s) => [s.section.id, JSON.stringify(s.section)]));
+  const remoteChangedIds = new Set(
+    remote.sections
+      .filter((s) => baselineById.has(s.section.id) && baselineById.get(s.section.id) !== JSON.stringify(s.section))
+      .map((s) => s.section.id),
+  );
+  // Safety: a dirty id that exists remotely but was never in the baseline means
+  // both sides created the same id independently (id collision). Flag it so the
+  // overlap goes to the dialog instead of silently keeping one side.
+  for (const id of dirtyIds) {
+    if (id in remote.index.sections && !(id in baseline.index.sections)) remoteChangedIds.add(id);
+  }
+  const locallyAddedIds = new Set([...dirtyIds].filter((id) => !(id in baseline.index.sections)));
+  return { remoteChangedIds, locallyAddedIds };
+}
+
+/** Apply the user's keep-mine/take-theirs choices to a rebase result.
+ *  Pure — inputs are never mutated. For every conflict the LOCAL copy is
+ *  returned in `preserved` (the caller snapshots it via preserveEdit so no
+ *  choice is destructive). "theirs" swaps in the remote section — or, when the
+ *  remote side DELETED it, removes the section AND strips its id from the index
+ *  (pages' order + sections map); leaving the dangling index ref would make the
+ *  server's dangling-ref gate reject every later save. `droppedDirtyIds` lists
+ *  the "theirs" ids whose local dirty rows must be deleted so the retry doesn't
+ *  re-send the overridden local content. */
+export function applyConflictChoices({ merged, remoteSections, choices }: {
+  merged: { sections: LoadedSection[]; index: SiteIndex };
+  remoteSections: LoadedSection[];
+  choices: Record<string, "mine" | "theirs">;
+}): {
+  sections: LoadedSection[];
+  index: SiteIndex;
+  droppedDirtyIds: string[];
+  preserved: { sectionId: string; section: Section }[];
+} {
+  let sections = [...merged.sections];
+  const index: SiteIndex = {
+    ...merged.index,
+    pages: merged.index.pages.map((p) => ({ ...p, order: [...p.order] })),
+    sections: { ...merged.index.sections },
+  };
+  const droppedDirtyIds: string[] = [];
+  const preserved: { sectionId: string; section: Section }[] = [];
+  const remoteById = new Map(remoteSections.map((s) => [s.section.id, s]));
+
+  for (const [id, choice] of Object.entries(choices)) {
+    const local = sections.find((s) => s.section.id === id);
+    if (local) preserved.push({ sectionId: id, section: local.section });
+    if (choice !== "theirs") continue;
+    droppedDirtyIds.push(id);
+    const remote = remoteById.get(id);
+    if (remote) {
+      sections = sections.map((s) => (s.section.id === id ? remote : s));
+    } else {
+      // Remote deletion won: drop the section and every index reference to it.
+      sections = sections.filter((s) => s.section.id !== id);
+      for (const page of index.pages) page.order = page.order.filter((x) => x !== id);
+      delete index.sections[id];
+    }
+  }
+
+  return { sections, index, droppedDirtyIds, preserved };
+}
+
+/** Build the COMMITTED post-save snapshot for re-priming the clean baseline.
+ *  The committed content is exactly what performSave sent (savedRows), NOT the
+ *  current view state — edits typed while the request was in flight must not
+ *  leak into the "clean" baseline (they are still dirty rows and would otherwise
+ *  read as remote changes on the next recovery). Base = the previous clean
+ *  baseline when available (post-recovery it is the fetched remote snapshot);
+ *  fallback = the loaded sections captured at save start. Ids absent from the
+ *  sent index (deleted this save) are dropped; saved ids absent from the base
+ *  (locally added) are appended with their meta from the sent index. */
+export function buildCommittedBaseline({ baselineSections, fallbackSections, savedRows, sentIndex }: {
+  baselineSections: LoadedSection[] | null;
+  fallbackSections: LoadedSection[];
+  savedRows: { sectionId: string; content: SectionContent }[];
+  sentIndex: SiteIndex;
+}): LoadedSection[] {
+  const base = baselineSections ?? fallbackSections;
+  const sentById = new Map(savedRows.map((r) => [r.sectionId, r.content]));
+
+  const out = base
+    .filter((s) => s.section.id in sentIndex.sections)
+    .map((s) => {
+      const sent = sentById.get(s.section.id);
+      return sent ? { ...s, section: { ...s.section, ...sent } } : s;
+    });
+
+  const present = new Set(out.map((s) => s.section.id));
+  for (const [id, content] of sentById) {
+    if (present.has(id) || !(id in sentIndex.sections)) continue;
+    out.push({ section: { id, ...content }, meta: sentIndex.sections[id] });
+  }
+  return out;
+}

package/src/collab/types.ts

@@ -0,0 +1,96 @@
+// types.ts — the whole contract. No Supabase imports anywhere in primitives.
+import { z } from "zod";
+
+export const HEARTBEAT_INTERVAL_MS = 15_000;
+export const LOCK_STALE_MS = 45_000;
+
+export const CollabPeerSchema = z.object({
+  userId: z.string(),
+  email: z.string(),
+  focusSectionId: z.string().nullable(),
+  heldSectionIds: z.array(z.string()),
+});
+export type CollabPeer = z.infer<typeof CollabPeerSchema>;
+
+export const SectionUpdateMessageSchema = z.object({
+  v: z.literal(1),
+  sectionId: z.string(),
+  content: z.unknown(),
+  userId: z.string(),
+});
+export type SectionUpdateMessage = z.infer<typeof SectionUpdateMessageSchema>;
+
+export const IndexUpdateMessageSchema = z.object({
+  v: z.literal(1),
+  index: z.unknown(),
+  userId: z.string(),
+});
+export type IndexUpdateMessage = z.infer<typeof IndexUpdateMessageSchema>;
+
+export const TakeoverMessageSchema = z.object({
+  v: z.literal(1),
+  sectionId: z.string(),
+  byUserId: z.string(),
+  byEmail: z.string(),
+});
+export type TakeoverMessage = z.infer<typeof TakeoverMessageSchema>;
+
+export const SavedMessageSchema = z.object({
+  v: z.literal(1),
+  newSha: z.string(),
+  changedSectionIds: z.array(z.string()),
+  deletedSectionIds: z.array(z.string()),
+  source: z.enum(["editor", "api"]),
+});
+export type SavedMessage = z.infer<typeof SavedMessageSchema>;
+
+export type CollabStatus = "connecting" | "connected" | "offline";
+
+/** Opaque server-minted connection blob. Provider-specific keys ride along;
+ *  primitives only reads the three identity fields. */
+export interface CollabBootstrap {
+  siteId: string;
+  userId: string;
+  email: string;
+  [key: string]: unknown;
+}
+
+export interface CollabEvents {
+  onPeers(peers: CollabPeer[]): void;
+  onSectionUpdate(msg: SectionUpdateMessage): void;
+  onIndexUpdate(msg: IndexUpdateMessage): void;
+  onTakeover(msg: TakeoverMessage): void;
+  onSaved(msg: SavedMessage): void;
+  onStatus(status: CollabStatus): void;
+}
+
+/** A live connection to one site channel. The session owns the held-lock set
+ *  (heartbeats them every HEARTBEAT_INTERVAL_MS and includes them in its
+ *  presence payload). acquireLock({steal:true}) also emits the takeover
+ *  broadcast on success. */
+export interface CollabSession {
+  setFocus(sectionId: string | null): void;
+  acquireLock(sectionId: string, opts?: { steal?: boolean }): Promise<boolean>;
+  releaseLocks(sectionIds: string[]): Promise<void>;
+  broadcastSectionUpdate(sectionId: string, content: unknown): void;
+  broadcastIndexUpdate(index: unknown): void;
+  disconnect(): Promise<void>;
+}
+
+export interface SavedBroadcast {
+  newSha: string;
+  changedSectionIds: string[];
+  deletedSectionIds: string[];
+  source: "editor" | "api";
+}
+
+export interface CollabProvider {
+  /** Browser: join the site channel. Resolves null when collaboration is
+   *  unavailable (no session, join refused) — caller runs solo-mode. */
+  connect(bootstrap: CollabBootstrap, events: CollabEvents): Promise<CollabSession | null>;
+  /** Server: mint the browser bootstrap for an authenticated editor session,
+   *  or null when the provider can't support collab (e.g. missing env). */
+  getBootstrap(args: { siteId: string; userId: string; email: string }): CollabBootstrap | null;
+  /** Server: post-commit fan-out of a successful save to all connected editors. */
+  broadcastSaved(siteId: string, event: SavedBroadcast): Promise<void>;
+}

package/src/components/editor/AudienceIndicator.tsx

@@ -8,9 +8,11 @@ interface AudienceIndicatorProps {
   access: string[];
   audiences: Audience[];
   onChange: (access: string[]) => void;
+  /** Display-only mode — the pill still shows audiences but the picker never opens. */
+  disabled?: boolean;
 }
 
-export function AudienceIndicator({ access, audiences, onChange }: AudienceIndicatorProps) {
+export function AudienceIndicator({ access, audiences, onChange, disabled }: AudienceIndicatorProps) {
   const selected = audiences.filter((a) => access.includes(a.name));
   const visibleDots = selected.slice(0, 3);
 
@@ -35,6 +37,7 @@ export function AudienceIndicator({ access, audiences, onChange }: AudienceIndic
       dots={pillDots}
       label={labelText}
       buttonClassName={selected.length === 0 ? "text-base-contrast-light" : undefined}
+      disabled={disabled}
       clickContent={
         audiences.length === 0 ? (
           <div className="px-3 py-2 text-xs text-base-contrast-light whitespace-nowrap">

package/src/components/editor/ConflictDialog.tsx

@@ -0,0 +1,61 @@
+import { useRef, useState } from "react";
+import { Button } from "../shared/Button";
+import { useFocusTrap } from "../../hooks/useFocusTrap";
+
+export interface ConflictItem {
+  sectionId: string;
+  label: string;
+}
+
+/** Presented on 409 recovery when a section the editor changed was ALSO changed
+ *  remotely. The user picks which side wins per section; the losing local copy
+ *  is always snapshotted to Dexie either way (stored, not user-recoverable via
+ *  the UI). Defaults every conflict to "mine" so a blind Continue never silently
+ *  drops local work. */
+export function ConflictDialog({
+  conflicts,
+  onResolve,
+}: {
+  conflicts: ConflictItem[];
+  onResolve: (choices: Record<string, "mine" | "theirs">) => void;
+}) {
+  const [choices, setChoices] = useState<Record<string, "mine" | "theirs">>(
+    Object.fromEntries(conflicts.map((c) => [c.sectionId, "mine" as const])),
+  );
+  const panelRef = useRef<HTMLDivElement>(null);
+  useFocusTrap(panelRef, true);
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50" role="dialog" aria-modal="true">
+      <div ref={panelRef} className="max-w-md rounded-lg bg-base p-6 shadow-xl">
+        <h2 className="mb-2 text-lg font-semibold text-base-contrast">Section changed by someone else</h2>
+        <p className="mb-4 text-sm text-base-contrast-light">
+          These sections were changed remotely while you edited them. Choose which version to keep — the other is safely stored locally.
+        </p>
+        <ul className="mb-4 space-y-2">
+          {conflicts.map((c) => (
+            <li key={c.sectionId} className="flex items-center justify-between gap-4 text-sm">
+              <span className="font-medium text-base-contrast">{c.label}</span>
+              <span className="flex gap-1">
+                {(["mine", "theirs"] as const).map((side) => (
+                  <button
+                    key={side}
+                    type="button"
+                    onClick={() => setChoices((prev) => ({ ...prev, [c.sectionId]: side }))}
+                    className={choices[c.sectionId] === side
+                      ? "rounded bg-primary px-2 py-1 text-primary-contrast"
+                      : "rounded border border-base-200 px-2 py-1 text-base-contrast hover:bg-base-accent"}
+                  >
+                    {side === "mine" ? "Keep mine" : "Take theirs"}
+                  </button>
+                ))}
+              </span>
+            </li>
+          ))}
+        </ul>
+        <div className="flex justify-end">
+          <Button variant="primary" size="md" onClick={() => onResolve(choices)}>Continue</Button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/editor/IndicatorPill.tsx

@@ -16,6 +16,9 @@ interface IndicatorPillProps {
   className?: string;
   buttonClassName?: string;
   ariaLabel?: string;
+  /** Display-only mode: dots/label still render but the popovers never open
+   *  (e.g. while another editor holds the section lock). */
+  disabled?: boolean;
 }
 
 export function IndicatorPill({
@@ -26,6 +29,7 @@ export function IndicatorPill({
   className,
   buttonClassName,
   ariaLabel,
+  disabled,
 }: IndicatorPillProps) {
   const [hoverOpen, setHoverOpen] = useState(false);
   const [clickOpen, setClickOpen] = useState(false);
@@ -41,7 +45,7 @@ export function IndicatorPill({
 
   function handleMouseEnter() {
     clearHoverTimeout();
-    if (!clickOpen && hoverContent) {
+    if (!disabled && !clickOpen && hoverContent) {
       setHoverOpen(true);
     }
   }
@@ -54,7 +58,7 @@ export function IndicatorPill({
   }
 
   function handleClick() {
-    if (!clickContent) return;
+    if (disabled || !clickContent) return;
     setHoverOpen(false);
     clearHoverTimeout();
     setClickOpen((v) => !v);
@@ -72,15 +76,17 @@ export function IndicatorPill({
         onClick={handleClick}
         onMouseEnter={handleMouseEnter}
         onMouseLeave={handleMouseLeave}
-        aria-haspopup={clickContent ? "true" : undefined}
-        aria-expanded={clickContent ? clickOpen : undefined}
+        aria-haspopup={!disabled && clickContent ? "true" : undefined}
+        aria-expanded={!disabled && clickContent ? clickOpen : undefined}
+        aria-disabled={disabled || undefined}
         aria-label={ariaLabel}
         className={cn(
           // align-middle keeps the inline-flex pill centred in its line box regardless of
           // whether it leads with a status/audience dot — without it, the dot-less variant's
           // text baseline sits ~2px lower than the dotted variant, misaligning the two pills.
-          "cursor-pointer inline-flex items-center gap-1.5 rounded-full px-2 py-0.5 text-xs font-medium align-middle",
-          "border border-base-200 hover:bg-base-accent",
+          "inline-flex items-center gap-1.5 rounded-full px-2 py-0.5 text-xs font-medium align-middle",
+          "border border-base-200",
+          disabled ? "cursor-default opacity-60" : "cursor-pointer hover:bg-base-accent",
           buttonClassName,
         )}
       >

package/src/components/editor/LockBadge.tsx

@@ -0,0 +1,31 @@
+import { Lock } from "lucide-react";
+import { cn } from "../../lib/cn";
+
+interface LockBadgeProps {
+  email: string;
+  onTakeover?: () => void;
+}
+
+// Reuses the "modified" status tokens (an amber pair defined in base.css) so the
+// lock badge sits in the same visual family as the other editor status pills
+// rather than introducing raw amber-* literals.
+export function LockBadge({ email, onTakeover }: LockBadgeProps) {
+  return (
+    <span className="pointer-events-auto inline-flex items-center gap-1.5 rounded-full bg-status-modified-bg px-2 py-0.5 text-xs font-medium text-status-modified-text align-middle">
+      <Lock size={12} strokeWidth={2.5} aria-hidden="true" />
+      <span className="whitespace-nowrap">{email} is editing</span>
+      {onTakeover && (
+        <button
+          type="button"
+          onClick={onTakeover}
+          className={cn(
+            "cursor-pointer rounded px-1.5 py-0.5 font-semibold",
+            "bg-status-modified-text/10 hover:bg-status-modified-text/20",
+          )}
+        >
+          Take over
+        </button>
+      )}
+    </span>
+  );
+}

package/src/components/editor/PresenceAvatars.tsx

@@ -0,0 +1,53 @@
+import type { CollabPeer, CollabStatus } from "../../collab/types";
+import { cn } from "../../lib/cn";
+
+// Vivid -600 fills read as distinct badge colors and keep white text legible
+// in both light and dark editor chrome.
+const AVATAR_COLORS = [
+  "bg-sky-600",
+  "bg-emerald-600",
+  "bg-amber-600",
+  "bg-fuchsia-600",
+  "bg-rose-600",
+];
+
+function initials(email: string): string {
+  return email.slice(0, 2).toUpperCase();
+}
+
+function colorFor(userId: string): string {
+  let h = 0;
+  for (const c of userId) h = (h * 31 + c.charCodeAt(0)) >>> 0;
+  return AVATAR_COLORS[h % AVATAR_COLORS.length];
+}
+
+interface PresenceAvatarsProps {
+  peers: CollabPeer[];
+  selfUserId: string | null;
+  status: CollabStatus;
+}
+
+export function PresenceAvatars({ peers, selfUserId, status }: PresenceAvatarsProps) {
+  const others = peers.filter((p) => p.userId !== selfUserId);
+  if (status !== "connected" || others.length === 0) return null;
+
+  return (
+    <div className="flex -space-x-2" aria-label="Editors online">
+      {others.map((p) => (
+        <span
+          key={p.userId}
+          title={p.focusSectionId ? `${p.email} — editing` : p.email}
+          className={cn(
+            // border-base-accent matches the toolbar surface behind the row in
+            // both themes (white in light, dark panel in dark), giving a clean
+            // ring where the avatars overlap.
+            "flex h-7 w-7 items-center justify-center rounded-full border-2 border-base-accent text-xs font-semibold text-white",
+            colorFor(p.userId),
+          )}
+        >
+          {initials(p.email)}
+        </span>
+      ))}
+    </div>
+  );
+}