@agent-native/core 0.120.3 → 0.121.0

package/corpus/templates/slides/app/components/editor/bullet-editing.ts

@@ -0,0 +1,350 @@
+/**
+ * Helpers for editing styled bullet lists — list-item rows built from a marker
+ * glyph plus text (e.g. `<div><span>●</span><span>Point</span></div>`) rather
+ * than real <ul>/<li> markup, which is how generated decks represent bullets.
+ *
+ * Kept in a standalone module (no React exports) so SlideEditor stays
+ * Fast-Refresh friendly and this logic is unit-testable.
+ */
+
+/** Zero-width space: keeps the caret inside an otherwise-empty text span so
+ * typed characters inherit that span's font instead of the container's. */
+export const ZERO_WIDTH_SPACE = "\u200B";
+
+/** Single glyphs commonly used as bullet markers in styled (non-<ul>) lists. */
+const BULLET_GLYPHS = new Set([
+  "\u2022", // •
+  "\u25CF", // ●
+  "\u25E6", // ◦
+  "\u25AA", // ▪
+  "\u2023", // ‣
+  "\u00B7", // ·
+  "\u2043", // ⁃
+  "-",
+  "\u2013", // –
+  "\u2014", // —
+  "*",
+]);
+
+/** True if an element is a bullet marker — either a text glyph (a leading ●
+ * span) or an empty CSS shape (a small square/dot/box span used as a marker). */
+export function isBulletMarker(el: Element): boolean {
+  return isGlyphMarker(el) || isShapeMarker(el);
+}
+
+/** A leading span whose text is only bullet glyph characters (e.g. "●"). */
+function isGlyphMarker(el: Element): boolean {
+  const text = (el.textContent ?? "").trim();
+  return text.length > 0 && [...text].every((c) => BULLET_GLYPHS.has(c));
+}
+
+/** An empty, small, roughly-square span drawn as a marker via border/background
+ * (e.g. `<span style="width:21px;height:21px;border:2px solid ...">`), which is
+ * how generated decks often render checkbox/dot bullets with no text glyph. */
+function isShapeMarker(el: Element): boolean {
+  if ((el.textContent ?? "").trim().length > 0) return false;
+  if (el.childElementCount > 0) return false;
+  const w = parseCssPx(styleValue(el, "width"));
+  const h = parseCssPx(styleValue(el, "height"));
+  if (!(w > 0 && h > 0) || w > 48 || h > 48) return false;
+  const ratio = w / h;
+  if (ratio < 0.5 || ratio > 2) return false;
+  const hasBorder =
+    parseCssPx(styleValue(el, "border-top-width")) > 0 ||
+    parseCssPx(styleValue(el, "border-left-width")) > 0 ||
+    parseCssPx(styleValue(el, "border-width")) > 0;
+  const bg = styleValue(el, "background-color");
+  const hasBg = !!bg && bg !== "transparent" && bg !== "rgba(0, 0, 0, 0)";
+  const hasRadius = parseCssPx(styleValue(el, "border-radius")) > 0;
+  return hasBorder || hasBg || hasRadius;
+}
+
+/** Read a style property, preferring inline styles and falling back to computed
+ * styles when available (jsdom-safe). */
+function styleValue(el: Element, prop: string): string {
+  const inline = (el as HTMLElement).style?.getPropertyValue(prop);
+  if (inline) return inline;
+  if (typeof window !== "undefined" && window.getComputedStyle) {
+    try {
+      return window.getComputedStyle(el).getPropertyValue(prop);
+    } catch {
+      return "";
+    }
+  }
+  return "";
+}
+
+function parseCssPx(value: string): number {
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+/** The bullet-marker element enclosing a node (or the node itself), bounded by
+ * `root`, or null when the node isn't inside a marker glyph. */
+function enclosingMarker(node: Node, root: HTMLElement): HTMLElement | null {
+  let el: HTMLElement | null =
+    node.nodeType === Node.ELEMENT_NODE
+      ? (node as HTMLElement)
+      : node.parentElement;
+  while (el && el !== root && root.contains(el)) {
+    if (isBulletMarker(el)) return el;
+    el = el.parentElement;
+  }
+  return null;
+}
+
+/**
+ * A "bullet row" is a styled list item whose first element child is a marker
+ * glyph. The text after it may be a <span> or a bare text node (contentEditable
+ * often unwraps spans while editing), and may be empty for a freshly-added
+ * bullet — so only the leading marker is required.
+ */
+export function isBulletRow(el: HTMLElement): boolean {
+  if (el.tagName !== "DIV" && el.tagName !== "LI" && el.tagName !== "P") {
+    return false;
+  }
+  const first = el.firstElementChild;
+  return !!first && isBulletMarker(first);
+}
+
+/** Count the styled bullet rows directly inside a container. */
+export function bulletRowCount(el: HTMLElement): number {
+  return Array.from(el.children).filter((k) => isBulletRow(k as HTMLElement))
+    .length;
+}
+
+/** A container whose element children are (essentially) all styled bullet rows. */
+export function isBulletList(el: HTMLElement): boolean {
+  const kids = Array.from(el.children);
+  if (kids.length === 0) return false;
+  const rows = bulletRowCount(el);
+  // Tolerate one stray non-bullet child (e.g. a stray <br>/<div> left behind by
+  // contentEditable) as long as the container is clearly a bullet list.
+  return rows >= 1 && rows >= kids.length - 1;
+}
+
+/** Regex for a markdown-style bullet prefix: a dash or asterisk plus a space,
+ * at the very start of a block's content (e.g. "- " or "* "). */
+const MARKDOWN_BULLET_PREFIX = /^[-*] $/;
+
+/**
+ * If `el`'s content starts with a markdown-style "- "/"* " prefix and the
+ * caret sits right after it, convert `el`'s content into a styled bullet row
+ * — a small marker span plus a text span holding the rest of `el`'s content —
+ * nested inside `el`, which becomes the list container. `el` itself must stay
+ * the contentEditable root (nesting the row rather than turning `el` itself
+ * into the row) so a later Enter's cloned sibling row lands inside the same
+ * contentEditable boundary and is actually typeable. Returns false when `el`
+ * is already a bullet row/list, there's no such prefix, or the selection
+ * isn't a collapsed caret.
+ */
+export function convertMarkdownPrefixToBullet(el: HTMLElement): boolean {
+  if (isBulletRow(el) || isBulletList(el)) return false;
+  const sel = window.getSelection();
+  if (!sel || sel.rangeCount === 0) return false;
+  const caretRange = sel.getRangeAt(0);
+  if (!caretRange.collapsed) return false;
+
+  const beforeCaretRange = document.createRange();
+  beforeCaretRange.selectNodeContents(el);
+  beforeCaretRange.setEnd(caretRange.endContainer, caretRange.endOffset);
+  // A freshly-placed text box seeds its content with a zero-width-space
+  // placeholder (see placeTextBoxAt) so it has a font to inherit before any
+  // real text exists. Strip it before testing so "- " typed as the very
+  // first characters is still recognized as a bullet prefix.
+  const beforeCaretText = beforeCaretRange
+    .toString()
+    .replace(new RegExp(ZERO_WIDTH_SPACE, "g"), "");
+  if (!MARKDOWN_BULLET_PREFIX.test(beforeCaretText)) return false;
+  beforeCaretRange.deleteContents();
+
+  const marker = document.createElement("span");
+  marker.style.fontSize = "0.3em";
+  marker.style.position = "relative";
+  marker.style.top = "-0.15em";
+  marker.textContent = "\u25CF";
+
+  const textSpan = document.createElement("span");
+  while (el.firstChild) textSpan.appendChild(el.firstChild);
+  const restFirstChild = textSpan.firstChild;
+  let placeholderZws: Text | null = null;
+  if (!restFirstChild) {
+    placeholderZws = document.createTextNode(ZERO_WIDTH_SPACE);
+    textSpan.appendChild(placeholderZws);
+  }
+
+  const row = document.createElement("div");
+  row.style.display = "flex";
+  row.style.alignItems = "baseline";
+  row.style.gap = "0.7em";
+  row.append(marker, textSpan);
+  el.append(row);
+
+  if (!el.style.display) el.style.display = "flex";
+  if (!el.style.flexDirection) el.style.flexDirection = "column";
+  if (!el.style.gap) el.style.gap = "0.6em";
+
+  const range = document.createRange();
+  if (restFirstChild) {
+    range.setStartBefore(restFirstChild);
+  } else {
+    // See primeNewRow: anchor the caret inside the placeholder text node
+    // (not an element-based position) so it keeps the text span's font
+    // instead of falling back to the marker's.
+    range.setStart(placeholderZws as Text, ZERO_WIDTH_SPACE.length);
+  }
+  range.collapse(true);
+  sel.removeAllRanges();
+  sel.addRange(range);
+  return true;
+}
+
+/**
+ * Walk up from a text leaf to the nearest enclosing styled bullet-row
+ * container, so Enter can add a new item to the whole list instead of being
+ * trapped inside one item.
+ */
+export function findEnclosingList(
+  el: HTMLElement,
+  root: HTMLElement,
+): HTMLElement | null {
+  let node: HTMLElement | null = el;
+  while (node && root.contains(node)) {
+    const parentEl: HTMLElement | null = node.parentElement;
+    if (!parentEl) break;
+    if (isBulletRow(node) && isBulletList(parentEl)) return parentEl;
+    // Even from a bullet row whose siblings aren't all bullets, treat the
+    // parent as a list once it holds two or more bullet rows.
+    if (isBulletRow(node) && bulletRowCount(parentEl) >= 2) return parentEl;
+    node = parentEl;
+  }
+  return null;
+}
+
+/** The non-marker text container of a row: a dedicated text <span> if present,
+ * otherwise the row itself (rows whose text is a bare node). */
+function rowTextContainer(
+  row: HTMLElement,
+  marker: HTMLElement | null,
+): HTMLElement {
+  const textSpan = Array.from(row.children).find(
+    (c) => c.tagName === "SPAN" && c !== marker && !isBulletMarker(c),
+  ) as HTMLElement | undefined;
+  return textSpan ?? row;
+}
+
+/**
+ * Seed a freshly-inserted row with the caret's trailing content and place the
+ * caret at the start of its editable text. `tail` is a DOM fragment (not a
+ * string) so inline formatting such as <strong>/<em> carried over from the
+ * split point is preserved. When there is no tail, a zero-width space text node
+ * keeps the caret inside the font-carrying text span rather than dropping it to
+ * the container.
+ */
+function primeNewRow(row: HTMLElement, tail: DocumentFragment | null): void {
+  const marker =
+    row.firstElementChild && isBulletMarker(row.firstElementChild)
+      ? (row.firstElementChild as HTMLElement)
+      : null;
+  const container = rowTextContainer(row, marker);
+
+  // Clear existing text content, preserving the marker glyph.
+  if (container !== row) {
+    container.replaceChildren();
+  } else {
+    while (marker?.nextSibling) marker.nextSibling.remove();
+    if (!marker) row.replaceChildren();
+  }
+
+  const firstTailNode = tail?.firstChild ?? null;
+  if (tail && firstTailNode) container.appendChild(tail);
+
+  const sel = window.getSelection();
+  if (!sel) return;
+  const range = document.createRange();
+  if (firstTailNode) {
+    // Caret at the very start of the moved tail (before the marker is not
+    // possible: setStartBefore anchors relative to the tail's first node).
+    range.setStartBefore(firstTailNode);
+  } else {
+    const zws = document.createTextNode(ZERO_WIDTH_SPACE);
+    container.appendChild(zws);
+    range.setStart(zws, ZERO_WIDTH_SPACE.length);
+  }
+  range.collapse(true);
+  sel.removeAllRanges();
+  sel.addRange(range);
+}
+
+/**
+ * Insert a new list item after the caret's current row. Content after the caret
+ * moves into the new row (with inline formatting preserved); the marker glyph is
+ * preserved on both rows. Returns false when the caret isn't inside a direct row
+ * of the list so the caller can fall back.
+ */
+export function insertBulletAfterCaret(list: HTMLElement): boolean {
+  const sel = window.getSelection();
+  if (!sel || sel.rangeCount === 0) return false;
+  const range = sel.getRangeAt(0);
+  if (!range.collapsed) {
+    // A selection that spans a row's marker glyph would delete it here, blanking
+    // the bullet on the surviving row (and its clone). Clamp both boundaries out
+    // of any enclosing marker so deletion never touches the glyphs.
+    const startMarker = enclosingMarker(range.startContainer, list);
+    if (startMarker) range.setStartAfter(startMarker);
+    const endMarker = enclosingMarker(range.endContainer, list);
+    if (endMarker) range.setEndBefore(endMarker);
+    if (!range.collapsed) range.deleteContents();
+  }
+
+  let row: HTMLElement | null = null;
+  let node: Node | null = range.endContainer;
+  while (node && node !== list) {
+    if (node.parentNode === list) {
+      row = node as HTMLElement;
+      break;
+    }
+    node = node.parentNode;
+  }
+  if (!row) return false;
+
+  const marker =
+    row.firstElementChild && isBulletMarker(row.firstElementChild)
+      ? (row.firstElementChild as HTMLElement)
+      : null;
+
+  // Never split inside the marker glyph itself: a caret at offset 0 of the "●"
+  // text node (e.g. clicking the marker's leading edge) would otherwise blank
+  // the marker and un-bullet the row. In that case add an empty bullet instead.
+  const caretInMarker = !!marker && marker.contains(range.endContainer);
+
+  const container = rowTextContainer(row, marker);
+  let tail: DocumentFragment | null = null;
+  if (!caretInMarker && container.contains(range.endContainer)) {
+    const tailRange = document.createRange();
+    tailRange.setStart(range.endContainer, range.endOffset);
+    const lastChild = container.lastChild;
+    if (lastChild) tailRange.setEndAfter(lastChild);
+    else tailRange.setEnd(container, container.childNodes.length);
+    // extractContents() moves the trailing DOM subtree (preserving <strong>/
+    // <em>) out of the original row so it can be reparented into the new one.
+    tail = tailRange.extractContents();
+    // A caret at the very end of the text (the common case) makes tailRange
+    // collapsed, but extractContents() on a collapsed range still clones the
+    // boundary text node with empty data instead of returning an empty
+    // fragment. Treat that as "no tail" so primeNewRow falls through to the
+    // zero-width-space placeholder — otherwise it moves in an empty text node
+    // with no character to anchor the caret's font to, and typing falls back
+    // to the marker span's formatting instead of the text span's.
+    if (tail.textContent === "") tail = null;
+  }
+
+  const newRow = row.cloneNode(true) as HTMLElement;
+  for (const el of [newRow, ...Array.from(newRow.querySelectorAll("*"))]) {
+    el.removeAttribute("data-builder-id");
+    el.removeAttribute("data-fusion-element-id");
+  }
+  row.after(newRow);
+  primeNewRow(newRow, tail);
+  return true;
+}

package/corpus/templates/slides/app/context/DeckContext.tsx

@@ -945,9 +945,7 @@ export const defaultSlideContent: Record<SlideLayout, string> = {
   "full-image": `<div class="fmd-slide" style="padding: 0; align-items: center; justify-content: center;">
   <div class="fmd-img-placeholder" style="width: 100%; height: 100%;">Full-bleed image or screenshot</div>
 </div>`,
-  blank: `<div class="fmd-slide" style="padding: 80px 110px; display: flex; flex-direction: column; justify-content: center; align-items: flex-start; font-family: 'Poppins', sans-serif;">
-  <div style="font-size: 28px; font-weight: 600; color: rgba(255,255,255,0.4); line-height: 1.3; font-family: 'Poppins', sans-serif;">Double-click to edit</div>
-</div>`,
+  blank: `<div class="fmd-slide" style="padding: 80px 110px; position: relative; font-family: 'Poppins', sans-serif;"></div>`,
 };
 
 export function DeckProvider({ children }: { children: ReactNode }) {

package/corpus/templates/slides/app/i18n/en-US.ts

@@ -121,6 +121,7 @@ const messages = {
     uploadAttachedFailed: "Could not upload the attached file.",
     uploadFailed: "Upload failed",
     doubleClickEdit: "Double-click any text to edit",
+    dragToMove: "Drag to move",
     aiEditing: "AI editing",
     startTypingCommands: "Start typing… or press / for commands",
     pinDropHint: "Click anywhere to drop a comment pin",
@@ -210,6 +211,7 @@ const messages = {
     elementAnimations: "Element animations",
     tweaks: "Tweaks",
     drawOnSlide: "Draw on slide",
+    addTextBox: "Add text box",
     pinComments: "Pin comments",
     pinCommentsDescription:
       "Click spots on the slide to queue several edits, then send them all at once.",

package/corpus/templates/slides/app/pages/DeckEditor.tsx

@@ -196,6 +196,7 @@ export default function DeckEditor() {
   const [tweaksOpen, setTweaksOpen] = useState(false);
   const [drawMode, setDrawMode] = useState(false);
   const [pinMode, setPinMode] = useState(false);
+  const [textBoxMode, setTextBoxMode] = useState(false);
   const [pendingComment, setPendingComment] = useState<{
     quotedText: string;
   } | null>(null);
@@ -816,6 +817,8 @@ export default function DeckEditor() {
         onToggleDrawMode={() => setDrawMode((v) => !v)}
         pinMode={pinMode}
         onTogglePinMode={() => setPinMode((v) => !v)}
+        textBoxMode={textBoxMode}
+        onToggleTextBoxMode={() => setTextBoxMode((v) => !v)}
         onDuplicateDeck={() => {
           const newId = `deck-${nanoid()}`;
           const optimistic = duplicateDeck(id, newId);
@@ -992,6 +995,8 @@ export default function DeckEditor() {
               onExitDrawMode={() => setDrawMode(false)}
               pinMode={pinMode}
               onExitPinMode={() => setPinMode(false)}
+              textBoxMode={textBoxMode}
+              onExitTextBoxMode={() => setTextBoxMode(false)}
               slideId={currentSlide.id}
               slideTitle={(() => {
                 const m = currentSlide.content?.match(

package/corpus/templates/slides/changelog/2026-07-23-new-bullet-rows-created-with-enter-now-keep-the-list-item-s-.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-23
+---
+
+New bullet rows created with Enter now keep the list item's font size instead of shrinking to the base font

package/corpus/templates/slides/changelog/2026-07-23-pressing-enter-in-generated-checkbox-shape-marker-lists-now-.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-23
+---
+
+Pressing Enter in generated checkbox/shape-marker lists now creates a new list item

package/corpus/templates/slides/changelog/2026-07-24-typing-a-markdown-style-dash-space-at-the-start-of-a-text-bl.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-24
+---
+
+Typing a markdown-style dash-space at the start of a text block now converts it into an editable bullet list

package/corpus/toolkit/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @agent-native/toolkit
 
+## 0.10.6
+
+### Patch Changes
+
+- 8afb252: Allow newly created empty collaborative editors to persist their first real user edit after the shared document finishes loading.
+
 ## 0.10.5
 
 ### Patch Changes

package/corpus/toolkit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/toolkit",
-  "version": "0.10.5",
+  "version": "0.10.6",
   "description": "Reusable app-building UI and helpers for Agent-Native apps.",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/corpus/toolkit/src/editor/useCollabReconcile.ts

@@ -33,6 +33,11 @@ export function getEditorMarkdown(editor: Editor): string {
  * is identical, so skipping it is safe by construction.
  */
 const EMITTED_RING_MAX = 16;
+// The hosted awareness transport polls every 2s when its SSE gateway cannot
+// forward presence. Give that first snapshot one poll plus margin before an
+// empty SQL value is allowed to clear a nonempty Y.Doc. This is the same settle
+// window used below when a known peer may deliver an edit through Yjs.
+const PEER_SETTLE_MS = 2500;
 function pushEmittedRing(ring: string[], value: string): void {
   if (!value) return;
   if (ring[ring.length - 1] === value) return;
@@ -264,6 +269,11 @@ export function useCollabReconcile({
   // arrives via Yjs, so external markdown reconcile must defer (avoid applying
   // the same change through both Yjs and setContent).
   const peerCountRef = useRef(0);
+  // Briefly gates the first empty-SQL reconcile while Collaboration projects
+  // a nonempty fragment. `seededRef` is still released immediately so a real
+  // first keystroke can persist; this ref only postpones the ambiguous clear
+  // decision until we can distinguish an active/local edit from stale CRDT.
+  const emptySnapshotDecisionPendingRef = useRef(false);
   useEffect(() => {
     if (!collab || !awareness || !ydoc) {
       setIsLeadClient(true);
@@ -299,25 +309,73 @@ export function useCollabReconcile({
     if (!collab || !editor || editor.isDestroyed || !ydoc) return;
     if (seededRef.current) return;
     if (!collabSynced) return;
-    if (!isLeadClient) return;
-    if (!value.trim()) return;
-    const fragment = ydoc.getXmlFragment("default");
-    const currentMarkdown = getMarkdown(editor);
-    // Seed only when the shared doc is genuinely empty — either the fragment has
-    // no nodes yet, or it holds no semantic markdown (an empty paragraph, or an
-    // app's sentinel-empty filler via a custom `shouldSeed`).
-    if (
-      !shouldSeed({ value, currentMarkdown, fragmentLength: fragment.length })
-    ) {
+    // An empty SQL value has nothing to seed. Release the first real keystroke
+    // immediately, but when a fragment already exists defer the ambiguous
+    // reconcile decision for one task: active-peer or just-emitted local content
+    // is live and must be adopted; stale persisted CRDT with no active writer is
+    // cleared by the canonical SQL snapshot.
+    if (!value.trim()) {
       seededRef.current = true;
-      return;
-    }
+      const fragment = ydoc.getXmlFragment("default");
+      const currentMarkdown = getMarkdown(editor);
+      if (fragment.length === 0 && !currentMarkdown.trim()) return;
 
+      emptySnapshotDecisionPendingRef.current = true;
+      let cancelled = false;
+      const adoptTimer = setTimeout(
+        () => {
+          if (cancelled || editor.isDestroyed) return;
+          const projectedMarkdown = getMarkdown(editor);
+          const isOwnFreshEdit =
+            projectedMarkdown.trim() &&
+            (projectedMarkdown === lastEmittedRef.current ||
+              recentEmittedRef.current.includes(projectedMarkdown));
+          if (
+            projectedMarkdown.trim() &&
+            (peerCountRef.current > 0 || isOwnFreshEdit)
+          ) {
+            lastAppliedValueRef.current = value;
+            lastAppliedSerializedRef.current = projectedMarkdown;
+            if (contentUpdatedAt) {
+              lastAppliedUpdatedAtRef.current = contentUpdatedAt;
+            }
+          }
+          emptySnapshotDecisionPendingRef.current = false;
+        },
+        awareness ? PEER_SETTLE_MS : 0,
+      );
+      return () => {
+        cancelled = true;
+        clearTimeout(adoptTimer);
+        emptySnapshotDecisionPendingRef.current = false;
+      };
+    }
+    if (!isLeadClient) return;
     let cancelled = false;
     // Defer via a timer task (NOT a microtask — microtasks can still run
     // inside React's commit and trigger flushSync-from-lifecycle warnings).
+    // Read the editor and fragment INSIDE that task. The collaboration
+    // extension can finish projecting an already-populated Y.Doc into
+    // ProseMirror after this effect is scheduled. Capturing the pre-projection
+    // empty editor here would incorrectly seed the SQL snapshot alongside the
+    // existing CRDT content, duplicating the whole document after reload.
     const seedTimer = setTimeout(() => {
       if (cancelled || editor.isDestroyed) return;
+      const fragment = ydoc.getXmlFragment("default");
+      const currentMarkdown = getMarkdown(editor);
+      // Seed only when the shared doc is genuinely empty — either the fragment
+      // has no nodes yet, or it holds no semantic markdown (an empty paragraph,
+      // or an app's sentinel-empty filler via a custom `shouldSeed`).
+      if (
+        !shouldSeed({
+          value,
+          currentMarkdown,
+          fragmentLength: fragment.length,
+        })
+      ) {
+        seededRef.current = true;
+        return;
+      }
       isSettingContentRef.current = true;
       try {
         setContent(editor, value, {});
@@ -362,16 +420,26 @@ export function useCollabReconcile({
     // With peers present, a peer's edit also arrives via Yjs. Defer one poll
     // cycle (+margin) and re-check before applying via setContent so the same
     // change isn't inserted twice (Yjs + setContent → duplicated region).
-    const PEER_SETTLE_MS = 2500;
-
     const apply = (deferred = false) => {
       if (cancelled || editor.isDestroyed) return;
       // In collab mode, defer all reconcile until the shared doc is seeded so we
       // never setContent over an unseeded fragment.
-      if (collab && (!collabSynced || !seededRef.current)) {
+      if (collab && !collabSynced) {
         retry = setTimeout(() => apply(deferred), 300);
         return;
       }
+      // The seed decision itself is deferred one task so Collaboration can
+      // project persisted Y.Doc state before we inspect it. Poll that short
+      // handoff promptly: waiting the full provider cadence here makes a newer
+      // canonical SQL snapshot visibly stale after reload.
+      if (collab && !seededRef.current) {
+        retry = setTimeout(() => apply(deferred), 25);
+        return;
+      }
+      if (collab && emptySnapshotDecisionPendingRef.current) {
+        retry = setTimeout(() => apply(deferred), 50);
+        return;
+      }
       const currentMarkdown = getMarkdown(editor);
       // Compare against the canonical form the editor would emit so a serializer
       // that re-normalizes (Content's NFM) still recognizes "already in sync".

package/dist/client/use-db-sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-db-sync.d.ts","sourceRoot":"","sources":["../../src/client/use-db-sync.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"use-db-sync.d.ts","sourceRoot":"","sources":["../../src/client/use-db-sync.ts"],"names":[],"mappings":"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"}

package/dist/client/use-db-sync.js

@@ -196,9 +196,12 @@ class SyncTransport {
     }
     get activeSseUrl() {
         if (this.mode === "hosted" && this.gateway) {
-            return this.token
-                ? `${this.gateway.sseUrl}?token=${encodeURIComponent(this.token)}`
-                : this.gateway.sseUrl;
+            if (!this.token)
+                return this.gateway.sseUrl;
+            const base = `${this.gateway.sseUrl}?token=${encodeURIComponent(this.token)}`;
+            // Cursor lets the gateway replay the reconnect gap on connect instead of
+            // deferring it to the next poll; 0 on first connect means nothing to replay.
+            return this.versionRef > 0 ? `${base}&since=${this.versionRef}` : base;
         }
         return this.sseUrl;
     }
@@ -514,28 +517,30 @@ class SyncTransport {
             this.schedulePoll();
         };
         source.onerror = () => {
+            // A replaced/closed source can still fire late; ignore it so it can't
+            // flip the connected state or tear down the current stream.
+            if (this.eventSource !== source)
+                return;
             this.setSseConnected(false);
-            // When the browser gives up permanently (HTTP error → readyState
-            // CLOSED), it won't auto-reconnect. Drop the ref so a later
-            // connectEvents() (on focus/visibility) can establish a fresh stream;
-            // otherwise the non-null closed `eventSource` blocks reconnection and
-            // we'd be stuck on polling-only forever.
+            if (this.mode === "hosted" && this.gateway) {
+                // Browser auto-reconnect reuses the URL frozen at construction, so it
+                // would replay from a stale `since`. Own the reconnect so the next
+                // connect rebuilds activeSseUrl from the current versionRef. CLOSED also
+                // refreshes the token (expired/rotated/deploy); CONNECTING keeps it. A
+                // successful reconnect resets the count in onopen; a hard-down gateway
+                // trips the threshold and health-gates to local.
+                if (source.readyState === EventSource.CLOSED)
+                    this.token = null;
+                this.closeEvents();
+                this.onGatewayTransientFailure();
+                if (this.mode === "hosted")
+                    this.scheduleGatewayReconnect();
+                return;
+            }
+            // Local mode: native EventSource reconnect is fine. Drop a CLOSED ref so a
+            // later connectEvents() (focus/visibility) can establish a fresh stream.
             if (source.readyState === EventSource.CLOSED) {
                 this.eventSource = null;
-                if (this.mode === "hosted" && this.gateway) {
-                    // A closed gateway stream is most likely an expired token or a
-                    // request-timeout/deploy cycle. Re-mint and reconnect with jitter;
-                    // this is NOT the poll-401 cooldown path. Each closed stream counts
-                    // toward the unhealthy threshold so a hard-down gateway (or one
-                    // rejecting our tokens) health-gates to local instead of looping
-                    // mint+connect forever; a successful reconnect resets the count in
-                    // onopen above.
-                    this.token = null;
-                    this.onGatewayTransientFailure();
-                    if (this.mode === "hosted")
-                        this.scheduleGatewayReconnect();
-                    return;
-                }
             }
             this.schedulePoll();
         };