@1agh/maude 0.60.6 → 1.0.2

package/apps/studio/clip-ops.ts

@@ -394,6 +394,11 @@ export function applyInsertClipAt(
       }
       const indent = `${lineStartInfo(source, rootClose).indent}  `;
       const s2 = new MagicString(source);
+      // Placeholder wins over media (same precedence as the append path below),
+      // then media, then nothing. The old two-arm form read `media.tag` in the
+      // else, where only the `needs media` throw above ruled out null — a
+      // disjunction the checker cannot carry. Spelled as three arms it needs no
+      // assertion, and the unreachable third arm is honest rather than absent.
       const gfChild = opts.placeholder
         ? placeholderChildText(
             canvasAbsPath,
@@ -402,7 +407,9 @@ export function applyInsertClipAt(
             `${indent}  `,
             dur
           ).trimEnd()
-        : `\n${indent}    <${media.tag} src="${escapeAttr(media.src)}" />`;
+        : media
+          ? `\n${indent}    <${media.tag} src="${escapeAttr(media.src)}" />`
+          : '';
       s2.appendLeft(
         rootClose,
         `  <TransitionSeries>\n${indent}  <TransitionSeries.Sequence durationInFrames={${dur}}>` +

package/apps/studio/cloud/endpoints.ts

@@ -25,7 +25,7 @@ import {
   writeFileSync,
 } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, dirname, join } from 'node:path';
+import { basename, dirname, join, relative, sep } from 'node:path';
 
 import { deleteHubCredential, saveHubCredential } from '../sync/hub-link.ts';
 import { getHubToken, normalizeUrl } from '../sync/hubs-config.ts';
@@ -48,6 +48,26 @@ export interface CloudEndpointResult {
   json: unknown;
 }
 
+/**
+ * Why a historical blob could not be produced — or the blob.
+ *
+ * `not-found` is the only AUTHORITATIVE negative: a commit's content never
+ * changes, so the answer is stable and a caller may cache it. `unreachable`,
+ * `not-linked` and the two argument refusals are all transient or caller-side,
+ * and caching any of them turns an outage into a permanent 404.
+ */
+export type HistoryFileResult =
+  | { ok: true; source: string }
+  | { ok: false; reason: 'not-found' | 'unreachable' | 'not-linked' | 'bad-sha' | 'bad-path' };
+
+/**
+ * Ceiling on ONE response from a linked cell.
+ *
+ * Comfortably above the hub's own 2 MiB blob cap, so a legitimate answer is
+ * never refused, and far below "buffer whatever arrives for eight seconds".
+ */
+const MAX_HUB_RESPONSE_BYTES = 8 * 1024 * 1024;
+
 /** Whatever the control plane answered. Read defensively at every use. */
 type CloudBody = Record<string, unknown> & {
   token?: string;
@@ -123,6 +143,13 @@ interface Ctx {
    * missing supervisor degrades to exactly the old behaviour — linked on disk,
    * syncing after the next start.
    */
+  /**
+   * The link changed (attach / detach). Lets the server drop anything it
+   * cached about "what a past version of this file looked like" — those
+   * answers were produced under the OLD link and are keyed by nothing that
+   * would distinguish them.
+   */
+  onLinkChanged?: () => void;
   syncControl?: {
     /** `null` = unlink: clear the runtime's in-memory link, cycle to solo. */
     restart(
@@ -266,7 +293,10 @@ export function createCloudEndpoints(ctx: Ctx) {
         headers: { authorization: `Bearer ${file.token}`, 'content-type': 'application/json' },
         body: JSON.stringify({ project: projectId }),
       });
-      if (opened.status !== 200 || !opened.body?.token) {
+      // `url` is checked alongside `token`: linkToWorkspace requires a
+      // workspace URL, and a 200 body missing it would have linked against
+      // `undefined` rather than refusing.
+      if (opened.status !== 200 || !opened.body?.token || !opened.body.url) {
         return {
           status: 502,
           json: { ok: false, error: 'The project could not be opened with this account.' },
@@ -295,7 +325,7 @@ export function createCloudEndpoints(ctx: Ctx) {
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ code }),
       });
-      if (exchanged.status !== 200 || !exchanged.body?.token) {
+      if (exchanged.status !== 200 || !exchanged.body?.token || !exchanged.body.url) {
         return {
           status: 410,
           json: {
@@ -331,6 +361,93 @@ export function createCloudEndpoints(ctx: Ctx) {
       });
     },
 
+    /**
+     * THE HISTORY THAT IS ACTUALLY BEING WRITTEN — feature-cloud-managed-git-
+     * posture.
+     *
+     * In cloud-managed posture the cell is the sole committer (DDR-198/209/213)
+     * and the local repo has no commits at all, so the desktop's History tab
+     * read a repo nobody writes and reported "No saved versions yet" directly
+     * under "Cloud is saving". This asks the cell instead.
+     *
+     * SERVER-SIDE, ALWAYS. The hub credential resolved here never reaches the
+     * browser — the client talks only to the loopback `/_api/cloud/history`,
+     * exactly as it does for every other call in this module.
+     */
+    async history(pathRaw?: string | null, limitRaw?: string | null): Promise<CloudEndpointResult> {
+      const hub = credentialedHub();
+      if (!hub) return { status: 200, json: { ok: false, reason: 'not-linked' } };
+
+      const qs = new URLSearchParams();
+      const rel = designRelative(pathRaw);
+      if (rel) qs.set('path', rel);
+      const limit = Number(limitRaw);
+      if (Number.isFinite(limit) && limit > 0)
+        qs.set('limit', String(Math.min(100, Math.trunc(limit))));
+
+      const r = await hubFetch(hub, `/api/history?${qs.toString()}`);
+      if (!r.ok) return { status: 200, json: { ok: false, reason: 'unreachable' } };
+      // Clamp what the cell says before it reaches a renderer. The hub caps its
+      // own page at 100 rows, but a compromised cell does not run that code.
+      const clamp = (v: unknown, n: number) => (typeof v === 'string' ? v.slice(0, n) : '');
+      const body = (r.body ?? {}) as { entries?: unknown; branch?: unknown; project?: unknown };
+      const rows = Array.isArray(body.entries) ? body.entries.slice(0, 100) : [];
+      return {
+        status: 200,
+        json: {
+          ok: true,
+          entries: rows.map((e) => {
+            const r0 = (e ?? {}) as Record<string, unknown>;
+            return {
+              sha: clamp(r0.sha, 40),
+              message: clamp(r0.message, 500),
+              author: clamp(r0.author, 120),
+              date: clamp(r0.date, 40),
+            };
+          }),
+          branch: typeof body.branch === 'string' ? body.branch.slice(0, 200) : null,
+          project: typeof body.project === 'string' ? body.project.slice(0, 200) : null,
+          hubHost: hubHost(hub.url),
+        },
+      };
+    },
+
+    /**
+     * One file's source at one cloud commit — what the version preview builds
+     * from when the sha exists only on the cell.
+     *
+     * `sha` is validated HERE as well as on the hub. It reaches the preview
+     * route from the UNTRUSTED canvas origin (DDR-054), and "the other side
+     * checks it" is how a guard ends up existing on neither side.
+     */
+    async historyFile(sha: string, pathRaw: string): Promise<HistoryFileResult> {
+      // WHY THIS REPORTS A REASON INSTEAD OF JUST `null`.
+      //
+      // The caller caches a miss so a repeated bad sha costs nothing. If every
+      // failure looked alike, an UNREACHABLE cell (or an unlinked project)
+      // would be remembered as "this version does not exist" — and the entry
+      // outlives the outage, so a version stays permanently unpreviewable. That
+      // is the same collapse of "could not reach" into "is not there" this
+      // whole feature exists to undo; the panel is careful about it one layer
+      // up, and it would be silly to re-introduce it one layer down.
+      //
+      // Only `not-found` is authoritative. Everything else is transient.
+      if (!/^[0-9a-f]{7,40}$/.test(String(sha ?? ''))) return { ok: false, reason: 'bad-sha' };
+      const rel = designRelative(pathRaw);
+      if (!rel) return { ok: false, reason: 'bad-path' };
+      const hub = credentialedHub();
+      if (!hub) return { ok: false, reason: 'not-linked' };
+
+      const qs = new URLSearchParams({ sha, path: rel });
+      const r = await hubFetch(hub, `/api/history/file?${qs.toString()}`, { text: true });
+      if (r.ok && typeof r.text === 'string') return { ok: true, source: r.text };
+      // A 404 is the cell's ONE indistinguishable refusal (out-of-scope,
+      // out-of-tree, wrong class, absent). Treating it as authoritative is
+      // correct for caching: none of those become true later for the same
+      // (sha, path), because a commit's content never changes.
+      return { ok: false, reason: r.status === 404 ? 'not-found' : 'unreachable' };
+    },
+
     /**
      * Detach THIS project from its workspace — the in-app `maude design
      * unlink` (fix 7's Disconnect, sync RCA 2026-08-10). Drops the committed
@@ -372,6 +489,7 @@ export function createCloudEndpoints(ctx: Ctx) {
       } catch {
         /* best-effort — the link is gone on disk either way */
       }
+      ctx.onLinkChanged?.();
       return { status: 200, json: { ok: true, detached: !!linked } };
     },
   };
@@ -404,6 +522,148 @@ export function createCloudEndpoints(ctx: Ctx) {
     }
   }
 
+  /**
+   * The linked hub AND its credential, or null.
+   *
+   * "Linked" alone is not enough to make a network call on: `config.json` is
+   * COMMITTED and travels with the repo, so a `linkedHub` in it is
+   * attacker-authorable (B2). A stored credential is the corroboration — and
+   * it is also the thing we would be sending, so resolving both together is
+   * what keeps a no-credential case from becoming an unauthenticated request
+   * to an address a repo named.
+   */
+  function credentialedHub(): { url: string; token: string } | null {
+    const linked = readLinkedHub();
+    if (!linked?.credentialed) return null;
+    try {
+      const url = normalizeUrl(linked.url);
+      const token = getHubToken(url);
+      return token ? { url, token } : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * One authenticated GET against the linked cell.
+   *
+   * NEITHER THE TOKEN NOR THE HUB'S OWN ERROR BODY EVER LEAVES THIS FUNCTION.
+   * Callers get `{ ok }` plus the parsed payload on success, so a hub message
+   * cannot be relayed into the browser (or into a log) by accident.
+   *
+   * A 401 IS A PLAIN READ FAILURE HERE. `/_api/cloud/status`'s 401 path
+   * DELETES the stored credential (confused-deputy F6, and correct there: the
+   * control plane is the authority on whether this device is still trusted).
+   * A History poll is not that authority — a cell restarting mid-token-renewal
+   * would otherwise silently unlink a working project. Read fails; credential
+   * stands.
+   */
+  async function hubFetch(
+    hub: { url: string; token: string },
+    path: string,
+    { text = false, timeoutMs = 8_000, maxBytes = MAX_HUB_RESPONSE_BYTES } = {}
+  ): Promise<{ ok: boolean; status: number; body?: unknown; text?: string }> {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), timeoutMs);
+    try {
+      const res = await fetch(`${hub.url}${path}`, {
+        headers: { authorization: `Bearer ${hub.token}` },
+        signal: ctl.signal,
+      });
+      if (!res.ok) return { ok: false, status: res.status };
+      // THE CELL IS NOT TRUSTED TO RESPECT ITS OWN LIMITS. The hub caps a blob
+      // at 2 MiB and checks `cat-file -s` before reading — but a compromised
+      // cell, or anything MITM-ing a self-hosted `http://` hub, simply does
+      // not run that code. Without a cap here the desktop buffers an endless
+      // stream into one JS string for the whole timeout, and the trigger is
+      // reachable from the UNTRUSTED canvas origin (a canvas picks the `?sha=`
+      // on the version-preview route). Read through a counted stream and abort
+      // past the cap. (Security re-review of 8134ca8f, finding F2.)
+      const body = await readCapped(res, ctl, maxBytes);
+      if (body == null) return { ok: false, status: 0 };
+      if (text) return { ok: true, status: res.status, text: body };
+      try {
+        return { ok: true, status: res.status, body: JSON.parse(body) };
+      } catch {
+        return { ok: true, status: res.status, body: {} };
+      }
+    } catch {
+      return { ok: false, status: 0 };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /** Read a response body, aborting past `maxBytes`. Null = refused/failed. */
+  async function readCapped(
+    res: Response,
+    ctl: AbortController,
+    maxBytes: number
+  ): Promise<string | null> {
+    const declared = Number(res.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > maxBytes) {
+      ctl.abort();
+      return null;
+    }
+    if (!res.body) {
+      const t = await res.text();
+      return t.length > maxBytes ? null : t;
+    }
+    const reader = res.body.getReader();
+    const dec = new TextDecoder('utf8');
+    let out = '';
+    let seen = 0;
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      seen += value?.byteLength ?? 0;
+      if (seen > maxBytes) {
+        // Content-Length is a claim; this is the measurement.
+        try {
+          await reader.cancel();
+        } catch {
+          /* already gone */
+        }
+        return null;
+      }
+      out += dec.decode(value, { stream: true });
+    }
+    return out + dec.decode();
+  }
+
+  /**
+   * repo-relative (`.design/ui/Card.tsx`) → design-root-relative (`ui/Card.tsx`).
+   *
+   * The hub speaks design-root-relative on every file surface it has, and the
+   * cell's design root need not share this machine's folder name — so the
+   * translation belongs on this side, where both roots are known. A path
+   * outside the design tree returns null rather than being passed through: the
+   * cell would refuse it anyway, and sending it would make this a probe.
+   */
+  function designRelative(raw?: string | null): string | null {
+    if (typeof raw !== 'string' || raw === '') return null;
+    const p = raw.replace(/\\/g, '/');
+    if (p.split('/').includes('..')) return null;
+    const designRel = relative(ctx.paths.repoRoot, ctx.paths.designRoot).split(sep).join('/');
+    if (!designRel || designRel.startsWith('..')) return null;
+    if (p === designRel) return null;
+    if (p.startsWith(`${designRel}/`)) return p.slice(designRel.length + 1) || null;
+    // Already design-root-relative (the History scope the panel holds for a
+    // canvas opened from the cell) — accept it as-is rather than refusing a
+    // caller for using the hub's own vocabulary.
+    return p.startsWith('/') ? null : p;
+  }
+
+  /** The cell's host, for a header that must name SOMETHING when the project
+   *  name is unknown. Address only — already-public, and never the token. */
+  function hubHost(url: string): string | null {
+    try {
+      return new URL(url).host;
+    } catch {
+      return null;
+    }
+  }
+
   /** The shared tail of every attach: cell exchange → credential + linkedHub. */
   async function linkToWorkspace({
     workspaceUrl,
@@ -499,6 +759,8 @@ export function createCloudEndpoints(ctx: Ctx) {
       };
     }
 
+    ctx.onLinkChanged?.();
+
     return {
       status: 200,
       json: {

package/apps/studio/collab/origins.ts

@@ -129,7 +129,9 @@ export const SYNC_AGENT_ORIGIN: object = markTrustedOrigin(
 export function rootTypesTouched(transaction: Y.Transaction): Set<string> {
   const roots = new Set<string>();
   for (const type of transaction.changed.keys()) {
-    let t: Y.AbstractType<unknown> = type;
+    // `transaction.changed` keys are AbstractType<YEvent<any>>; the parent walk
+    // below is event-type agnostic, so widen once here rather than at each step.
+    let t: Y.AbstractType<unknown> = type as unknown as Y.AbstractType<unknown>;
     // biome-ignore lint/suspicious/noExplicitAny: `_item` is yjs-internal but stable API surface for parent walks.
     while ((t as any)._item != null) t = (t as any)._item.parent;
     try {

package/apps/studio/comments-overlay.tsx

@@ -73,6 +73,11 @@ interface ComposeSelection {
   id?: string;
   selector: string;
   artboardId?: string | null;
+  /** Occurrence index within `selector` — always set by buildComposeSelection,
+   *  read into the comment payload below. Missing from this local mirror of
+   *  dom-selection's `Selection`, so the payload was silently sending
+   *  `undefined` to the checker's eyes and the real value at runtime. */
+  index: number;
   tag: string;
   classes: string;
   text: string;

package/apps/studio/config.schema.json

@@ -228,6 +228,30 @@
           "type": "boolean",
           "default": true,
           "description": "DDR-079 (supersedes DDR-072) — project-level TSX sync, ON BY DEFAULT. Omit the field to sync ALL .tsx canvases to this hub (the common case: a linked teammate sees the project's TSX without a hidden opt-in). Set false to opt the whole project OUT. A per-canvas .meta.json \"syncable\": false still excludes one canvas (the sidecar always wins). Inert unless the cross-origin sandbox is active (MAUDE_CANVAS_ORIGIN_SPLIT != 0) — the DDR-060 Lock-2 coupling is preserved. TSX bodies execute, so syncing broadens a WebRTC/self-nav exfil residual to every synced canvas — link only hubs you operate or trust; the dev-server prints a loud boot banner against non-loopback hubs."
+        },
+        "workspaceId": {
+          "type": "string",
+          "description": "DDR-192 §5 — stable workspace identity for the hub document namespace (ws/<workspace-id>/<branch>/<slug>). Authoritative when present; the cloud control plane sets it at provisioning time. Absent, the sync runtime derives it from the git origin remote."
+        },
+        "syncFiles": {
+          "type": "boolean",
+          "default": true,
+          "description": "Sync v2 — the journal-driven file plane (Plane B): the downward project-file pull AND the widened upward sweep. Default ON; set false to fall back to the pre-Sync-v2 reach (binary media under assets/ only). Settable from the Sync panel's Settings section."
+        },
+        "propagateDeletes": {
+          "type": "boolean",
+          "default": true,
+          "description": "Sync v2 Increment 6 — a deletion here becomes a deletion everywhere (losers quarantined into _trash/, never unlinked; cumulative breakers hold bulk removals for confirmation). Default ON; set false to hold every absence instead. Settable from the Sync panel's Settings section."
+        },
+        "resolveFirstAnchor": {
+          "type": "string",
+          "enum": ["keep-local", "keep-cloud"],
+          "description": "How to settle a FIRST-ANCHOR hold for the whole set at once: keep-local pushes this machine's copies up; keep-cloud takes the project's and parks yours beside them. ABSENT means keep asking — the hold is not an error. Settable from the Sync panel's Settings section."
+        },
+        "fileEvents": {
+          "type": "boolean",
+          "default": true,
+          "description": "Sync v2 Increment 2 (DDR-226 §4) — the file-event control channel (poke). Default ON where the hub advertises ledger support; set false to fall back to the 20 s poll cadence. The documented rollback for the poke — a config key because the target user has no terminal (DDR-177)."
         }
       },
       "additionalProperties": false

package/apps/studio/context-menu.tsx

@@ -371,7 +371,11 @@ export function ContextMenuView({
           el.querySelectorAll<HTMLButtonElement>('button.dc-menu-item:not([disabled])')
         );
         if (items.length === 0) return;
-        const idx = items.indexOf(document.activeElement);
+        // `document.activeElement` is Element | null; anything that is not one
+        // of these buttons behaves as "no current item" (-1), which is what
+        // indexOf returned before and what the wrap-around arithmetic expects.
+        const active = document.activeElement;
+        const idx = active instanceof HTMLButtonElement ? items.indexOf(active) : -1;
         const nextIdx =
           e.key === 'ArrowDown'
             ? (idx + 1) % items.length
@@ -526,32 +530,41 @@ function MenuItemRow({
           onMouseEnter={cancelClose}
           onMouseLeave={scheduleClose}
         >
-          {submenuItems.map((sub) => (
-            <button
-              key={sub.id}
-              type="button"
-              role="menuitem"
-              disabled={sub.disabled}
-              title={sub.disabled ? sub.disabledHint : undefined}
-              className={`dc-menu-item${sub.destructive ? ' is-destructive' : ''}`}
-              onClick={() => {
-                if (sub.disabled) return;
-                sub.onSelect(target);
-                onClose();
-              }}
-              onKeyDown={(e) => {
-                if (e.key === 'ArrowLeft' || e.key === 'Escape') {
-                  e.preventDefault();
-                  e.stopPropagation();
-                  setSubOpen(false);
-                  btnRef.current?.focus();
-                }
-              }}
-            >
-              <span>{sub.label}</span>
-              {sub.shortcut ? <span className="dc-menu-shortcut">{sub.shortcut}</span> : null}
-            </button>
-          ))}
+          {submenuItems.map((sub) => {
+            // Same per-click resolution the leaf branch does at `disabled`
+            // above. Passing the raw value here meant a FUNCTION-form
+            // `disabled` — always truthy — greyed the item out permanently and
+            // swallowed every click, whatever the predicate said about this
+            // target. Submenus simply never got the resolution leaves had.
+            const subDisabled =
+              typeof sub.disabled === 'function' ? sub.disabled(target) : sub.disabled;
+            return (
+              <button
+                key={sub.id}
+                type="button"
+                role="menuitem"
+                disabled={subDisabled}
+                title={subDisabled ? sub.disabledHint : undefined}
+                className={`dc-menu-item${sub.destructive ? ' is-destructive' : ''}`}
+                onClick={() => {
+                  if (subDisabled) return;
+                  sub.onSelect(target);
+                  onClose();
+                }}
+                onKeyDown={(e) => {
+                  if (e.key === 'ArrowLeft' || e.key === 'Escape') {
+                    e.preventDefault();
+                    e.stopPropagation();
+                    setSubOpen(false);
+                    btnRef.current?.focus();
+                  }
+                }}
+              >
+                <span>{sub.label}</span>
+                {sub.shortcut ? <span className="dc-menu-shortcut">{sub.shortcut}</span> : null}
+              </button>
+            );
+          })}
         </div>
       ) : null}
     </div>

package/apps/studio/context.ts

@@ -48,14 +48,59 @@ export interface LinkedHub {
    */
   workspaceId?: string;
   /**
-   * feature-sync-file-plane — opt-in for the manifest-driven file plane
-   * (Plane B): the downward project-file pull AND the widened upward sweep
-   * (stylesheets, docs, code modules — classifier membership, see
-   * sync/file-membership.ts). Default OFF this release; `MAUDE_SYNC_FILES=1`
-   * forces it on for a session. The flag gates ONLY the new plane — the
-   * canvas CRDT lanes and the DDR-217 asset lanes run regardless.
+   * Sync v2 — the journal-driven file plane (Plane B): the downward
+   * project-file pull AND the widened upward sweep (stylesheets, docs, code
+   * modules — classifier membership, see sync/file-membership.ts).
+   *
+   * **Default ON from Increment 4**, once its security gate closed. Set to
+   * `false` per project to fall back to the pre-Sync-v2 reach (binary media
+   * under `assets/` only) — a config key rather than a terminal command,
+   * because the target user has no terminal (DDR-177). `MAUDE_SYNC_FILES=0`
+   * forces it off for one session.
+   *
+   * The flag gates ONLY this plane — the canvas CRDT lanes and the DDR-217
+   * asset lanes run regardless.
    */
   syncFiles?: boolean;
+  /**
+   * Sync v2 Increment 6 — does a deletion here become a deletion everywhere?
+   *
+   * **Default ON.** A hub-owned mirror that ignores deletes is not a mirror:
+   * you remove a file, it comes back on the next pass, and the model the
+   * product describes stops being true.
+   *
+   * What makes that safe is not caution but the breakers: past ten files, or a
+   * quarter of what this machine tracks, in one pass, nothing is removed in
+   * EITHER direction and the pass says what it was about to do — a branch
+   * switch and a deliberate purge look identical until somebody confirms which
+   * one it was. Losers are quarantined into `_trash/`, never unlinked, on both
+   * ends. Set `false` per project to hold every absence instead.
+   */
+  propagateDeletes?: boolean;
+  /**
+   * How to settle a FIRST-ANCHOR hold, for the whole set at once.
+   *
+   * When a project is linked for the first time both sides usually have
+   * content and neither has been reconciled here, so sync holds rather than
+   * writing a conflict copy per file. `keep-local` pushes this machine's
+   * copies up; `keep-cloud` takes the project's and parks yours beside them.
+   * Absent means keep asking — the hold is not an error and waiting costs
+   * nothing but time.
+   */
+  resolveFirstAnchor?: 'keep-local' | 'keep-cloud';
+  /**
+   * Sync v2 Increment 2 (DDR-226 §4) — the file-event control channel.
+   *
+   * Default ON where the hub advertises `ledger`; set to `false` to fall back
+   * to exactly today's 20 s poll cadence. A CONFIG KEY rather than an env var
+   * on purpose: this is the documented rollback for the poke, and the target
+   * user has no terminal to set an env var in (DDR-177).
+   *
+   * Absence means ON. A committed `false` can only ever make sync SLOWER, so
+   * unlike `syncTsx` it carries no trust weight and needs no restore-proof
+   * absence-means-on gymnastics.
+   */
+  fileEvents?: boolean;
 }
 
 export interface DevServerConfig {
@@ -209,8 +254,12 @@ export interface Context {
     }>;
     /** A cycle is in flight — Resync refuses early rather than queueing. */
     busy?(): boolean;
-    /** The live runtime, for the sweep-scoped cancel. Null in solo mode. */
-    current?(): { cancelAssetSweep(): boolean } | null;
+    /** The live runtime, for the sweep-scoped cancel + the move protocol's
+     *  retire step. Null in solo mode. Structural on purpose — see above. */
+    current?(): {
+      cancelAssetSweep(): boolean;
+      retireForMove?(fromSlug: string, toRel: string): Promise<boolean>;
+    } | null;
   };
 }
 

package/apps/studio/cursors-overlay.tsx

@@ -17,9 +17,10 @@
  * 30 Hz publish cadence keeps it smooth enough for the multiplayer demo.
  */
 
+import type { JSX } from 'react';
 import { memo, useEffect, useState } from 'react';
 
-import { useViewportControllerContext } from './canvas-lib.tsx';
+import { useLiveViewport } from './canvas-lib.tsx';
 import { type ForeignAwareness, useCollab, useForeignAwareness } from './use-collab.tsx';
 
 const CURSOR_CSS = `
@@ -164,9 +165,17 @@ const Cursor = memo(function Cursor({ peer, viewport }: CursorProps): JSX.Elemen
  */
 interface PeerAnnotationSelectionProps {
   peer: ForeignAwareness;
+  /**
+   * Unused in the math below — the halo is measured straight off the DOM — but
+   * load-bearing as a PROP: `memo` compares props, and through a pan/zoom the
+   * peer never changes, so without a value that ticks with the camera this
+   * component would bail out of every re-render and leave the halo frozen in
+   * screen space while the stroke it outlines moves away underneath it.
+   */
+  viewport: ViewportSnapshot;
 }
 
-const PeerAnnotationSelection = memo(function PeerAnnotationSelection({
+export const PeerAnnotationSelection = memo(function PeerAnnotationSelection({
   peer,
 }: PeerAnnotationSelectionProps): JSX.Element | null {
   if (!peer.annotationSelection || peer.annotationSelection.length === 0) return null;
@@ -218,9 +227,11 @@ const PeerAnnotationSelection = memo(function PeerAnnotationSelection({
  */
 interface PeerSelectionProps {
   peer: ForeignAwareness;
+  /** See PeerAnnotationSelectionProps.viewport — the memo-invalidation tick. */
+  viewport: ViewportSnapshot;
 }
 
-const PeerSelection = memo(function PeerSelection({
+export const PeerSelection = memo(function PeerSelection({
   peer,
 }: PeerSelectionProps): JSX.Element | null {
   if (!peer.selection) return null;
@@ -267,14 +278,15 @@ const PeerSelection = memo(function PeerSelection({
 export function CursorsOverlay(): JSX.Element {
   ensureCursorStyles();
   const peers = useForeignAwareness();
-  const controller = useViewportControllerContext();
-  const liveVp = controller?.viewport ?? { x: 0, y: 0, zoom: 1 };
-  // Take a snapshot per render — controller.viewport already changes on
-  // throttle, so this stays smooth enough at 30 Hz.
-  const [vp, setVp] = useState<ViewportSnapshot>(liveVp);
-  useEffect(() => {
-    setVp({ x: liveVp.x, y: liveVp.y, zoom: liveVp.zoom });
-  }, [liveVp.x, liveVp.y, liveVp.zoom]);
+  // LIVE, not the published viewport. `controller.viewport` republishes only on
+  // the settle (SETTLE_MS), so through a pan/zoom it is one frozen value: every
+  // peer cursor and every peer selection frame sat at the screen position the
+  // camera had when the gesture STARTED and only snapped onto the content half
+  // a second after it ended. Same root cause, same fix as the annotation resize
+  // handles — read the camera that is written on every applyViewport. Settled,
+  // `useLiveViewport()` IS the published value, and it only subscribes to the
+  // shared rAF ticker while a gesture is in flight.
+  const vp = useLiveViewport();
 
   // Bump a render tick whenever annotations change so PeerAnnotationSelection
   // re-resolves [data-id] bounds. Without this, a peer resizing a stroke
@@ -299,10 +311,10 @@ export function CursorsOverlay(): JSX.Element {
   return (
     <div className="dc-cursor-overlay" aria-hidden="true">
       {peers.map((peer) => (
-        <PeerSelection key={`sel-${peer.clientID}`} peer={peer} />
+        <PeerSelection key={`sel-${peer.clientID}`} peer={peer} viewport={vp} />
       ))}
       {peers.map((peer) => (
-        <PeerAnnotationSelection key={`asel-${peer.clientID}`} peer={peer} />
+        <PeerAnnotationSelection key={`asel-${peer.clientID}`} peer={peer} viewport={vp} />
       ))}
       {peers.map((peer) => (
         <Cursor key={peer.clientID} peer={peer} viewport={vp} />