@lark-apaas/coding-registry-buildless 0.1.20 → 0.1.22

package/components/animations.jsx

@@ -20,9 +20,82 @@
 // `progress` via the useSprite() hook. Use Easing + interpolate()/animate()
 // for tweens; TextSprite / ImageSprite / RectSprite have built-in entry/exit.
 // Build YOUR scenes by composing Sprites inside a Stage.
+//
+// window.__miaodaMirror (defined below) is Magic-Share sync plumbing between
+// this component and the miaoda host — internal; do not call or remove it.
 /* END USAGE */
 // ─────────────────────────────────────────────────────────────────────────────
 
+// ── Mirror sync singleton ──────────────────────────────────────────────────
+// Shared by every buildless script on the page (first one to load defines
+// it). Inlined per script rather than shipped as its own registry file:
+// call sites use the global bare, so inlining is what guarantees
+// definition-before-use — a separate copy-in file would add a whole "SDK
+// copied but <script> tag missing" failure mode. Keep this block identical
+// across deck-stage.js / design-canvas.jsx / animations.jsx — same
+// convention as the mobile-UA regex. Two halves of
+// the 妙享 (Magic Share) mirror protocol:
+//   emit(msg, opts)   — stamps msg.__mirror so the host relay treats the
+//                       message as a broadcastable UI-state snapshot;
+//                       unstamped messages are never mirrored. opts.key is
+//                       the sync channel (maps to the share SDK's
+//                       actionType): late joiners receive only the LATEST
+//                       snapshot per key, so states that overwrite each
+//                       other must share one key. opts.throttle is the
+//                       suggested host-side coalescing interval in ms —
+//                       snapshots make dropped intermediate frames
+//                       lossless, so hint it on any continuous gesture.
+//   onApply(type, fn) — replay entry for a message type this script itself
+//                       emits. The host sends {type:'miaoda:mirror:apply',
+//                       uuid, message, latencyMs} and needs
+//                       {type:'miaoda:mirror:apply-result', uuid, result}
+//                       back to drive the SDK's retry: result.type
+//                       'failed' means retry (use it for transient
+//                       not-ready states), 'ignored' is terminal (not
+//                       applicable / bad payload), 'applied' is success.
+//                       Unregistered types stay silent on purpose —
+//                       another script on the page may own them, and the
+//                       host's timeout is the backstop.
+if (!window.__miaodaMirror) {
+  const appliers = new Map(); // message.type -> Set<fn>
+  window.__miaodaMirror = {
+    emit(msg, opts) {
+      try { window.parent.postMessage(Object.assign({}, msg, { __mirror: Object.assign({ v: 1 }, opts) }), '*'); } catch (e) {}
+    },
+    onApply(type, fn) {
+      if (!appliers.has(type)) appliers.set(type, new Set());
+      appliers.get(type).add(fn);
+      return () => { const s = appliers.get(type); if (s) s.delete(fn); };
+    },
+  };
+  window.addEventListener('message', async (e) => {
+    // Replays are accepted from the host frame only — generated pages embed
+    // arbitrary third-party iframes, any of which could otherwise forge an
+    // apply and drive state (plus its persisted side effects).
+    if (e.source !== window.parent) return;
+    const d = e.data;
+    if (!d || d.type !== 'miaoda:mirror:apply' || !d.message || !d.message.type) return;
+    const fns = appliers.get(d.message.type);
+    if (!fns || !fns.size) return;
+    // Merge across handlers (multi-instance case): one success is enough.
+    // Instances share a channel, so a sibling that can't apply yet (a lazily
+    // slotted second deck returning 'failed') must not poison an applied
+    // result into an SDK retry storm of no-ops — 'failed' only stands when
+    // nobody applied. Every handler still runs (no short-circuit) so each
+    // sibling instance gets the state.
+    let result = { type: 'ignored', reason: 'no applier result' };
+    for (const fn of Array.from(fns)) {
+      let r;
+      try { r = await fn(d.message, { latencyMs: d.latencyMs, uuid: d.uuid }); }
+      catch (err) { r = { type: 'failed', reason: String((err && err.message) || err) }; }
+      if (!r) continue;
+      if (r.type === 'applied') result = r;
+      else if (result.type !== 'applied' && (r.type === 'failed' || result.type !== 'failed')) result = r;
+    }
+    try { window.parent.postMessage({ type: 'miaoda:mirror:apply-result', uuid: d.uuid, result }, '*'); } catch (e2) {}
+  });
+}
+
 // ── Easing functions (hand-rolled, Popmotion-style) ─────────────────────────
 // All easings take t ∈ [0,1] and return eased t ∈ [0,1] (may overshoot for back/elastic).
 const Easing = {
@@ -346,6 +419,13 @@ function Stage({
   // ~1s as a fallback — paused, with the playback bar hidden, so the product
   // thumbnail is a deterministic frame of the first composed scene.
   const captureMode = typeof location !== 'undefined' && /[?&]thumbnail=/.test(location.search || '');
+  // Mirror silence additionally covers _snthumb frames (deck's presenter
+  // popup pins LIVE product iframes per slide — a stage embedded in such a
+  // slide is on the presenter's side, so the role gate can't drop its
+  // stamped emits). Kept separate from captureMode on purpose: the poster
+  // freeze stays keyed to ?thumbnail= only, so _snthumb thumbnails still
+  // look like the live slide.
+  const captureFrame = captureMode || (typeof location !== 'undefined' && /[?&]_snthumb=/.test(location.search || ''));
 
   const [time, setTime] = React.useState(() => {
     if (captureMode) return clamp(poster == null ? 1 : poster, 0, duration);
@@ -362,7 +442,11 @@ function Stage({
   const rafRef = React.useRef(null);
   const lastTsRef = React.useRef(null);
 
-  // Persist playhead
+  // Persist playhead. A Magic-Share-replayed time persists too, on purpose:
+  // unlike the rail/viewport preferences this IS the stage's current
+  // position, and while playing the next local rAF tick would re-persist it
+  // anyway (a guard would only reach the paused case, whose landing spot is
+  // equally this stage's real position).
   React.useEffect(() => {
     try { localStorage.setItem(persistKey + ':t', String(time)); } catch {}
   }, [time, persistKey]);
@@ -402,7 +486,51 @@ function Stage({
   // The playback bar is a *sibling* of this node, so it never lands in a capture
   // and needs no hiding.
   const bridgeStateRef = React.useRef(null);
-  bridgeStateRef.current = { time, duration, fps, width, height, setTime, setPlaying };
+  bridgeStateRef.current = { time, duration, fps, width, height, playing, loop, setTime, setPlaying };
+
+  // Magic Share: playhead sync fires only from explicit interactions (playbar,
+  // keyboard) plus the coarse keepalive below — never from the rAF tick, which
+  // would broadcast at frame rate for nothing (each message is already a full
+  // snapshot). Scrub-drags still call this per mousemove, so the actual post
+  // is trailing-throttled locally (same rule as design-canvas's viewport:
+  // no per-event cross-frame posts). Capture iframes are frozen stills and
+  // the host export drives the bridge programmatically, so captureMode
+  // stays silent. ts rides along for the HOST, which derives from it the
+  // latencyMs it hands back to replays.
+  const emitTRef = React.useRef(0);
+  React.useEffect(() => () => clearTimeout(emitTRef.current), []);
+  const emitPlayhead = () => {
+    if (captureFrame || emitTRef.current) return;
+    emitTRef.current = setTimeout(() => {
+      emitTRef.current = 0;
+      // Read at fire time, not call time — by 80ms the interaction's state
+      // has committed and bridgeStateRef is fresh (same live-ref pattern as
+      // design-canvas's tf trailing timer).
+      const cur = bridgeStateRef.current;
+      window.__miaodaMirror.emit(
+        { type: 'miaoda:anim:playhead-changed', t: cur.time, playing: cur.playing, ts: Date.now() },
+        { key: 'anim:playhead', throttle: 60 },
+      );
+    }, 80);
+  };
+
+  // Coarse drift correction: followers free-run their own rAF between
+  // messages, so while playing re-anchor them every few seconds. 3s is
+  // coarse enough to be free and tight enough that free-run drift stays
+  // imperceptible. Quiesced while replays are flowing in: a replayed
+  // playing:true arms this effect on followers too, and their competing
+  // snapshots are otherwise only stopped by the host's presenter role gate —
+  // don't lean on a single layer across presenter-handoff windows.
+  const lastApplyTsRef = React.useRef(0);
+  React.useEffect(() => {
+    if (!playing || captureFrame) return;
+    const iv = setInterval(() => {
+      if (Date.now() - lastApplyTsRef.current < 3000) return;
+      emitPlayhead();
+    }, 3000);
+    return () => clearInterval(iv);
+  }, [playing]);
+
   React.useEffect(() => {
     const s = bridgeStateRef;
     const bridge = {
@@ -420,7 +548,42 @@ function Stage({
     // Announce to the host that this product IS an animation scene, so it can
     // reveal the export entry (mirrors deck-stage's miaoda:deck:available).
     try { window.parent.postMessage({ type: 'miaoda:anim:available' }, '*'); } catch (e) {}
-    return () => { if (window.__animStage === bridge) delete window.__animStage; };
+    // Magic Share replay — a thin adapter over the same setTime/setPlaying the
+    // export bridge exposes. The setters themselves never emit, but
+    // setPlaying(true) does arm the keepalive effect, whose re-emit — like
+    // every follower emit — is dropped host-side by the presenter role gate.
+    const offApply = window.__miaodaMirror.onApply('miaoda:anim:playhead-changed', (m, ctx) => {
+      // Capture iframes are frozen stills — a forwarded replay's playing:true
+      // would unfreeze the poster mid-screenshot. The emit side is already
+      // silent under captureMode; keep the apply side symmetric.
+      if (captureFrame) return { type: 'ignored', reason: 'capture iframe' };
+      // isFinite, not typeof: NaN would sail through clamp() (Math.min/max
+      // propagate it) into setTime and persisted state.
+      if (!Number.isFinite(m.t)) return { type: 'ignored', reason: 'no t' };
+      // Kill any pending local-emit timer — it reads state at fire time and
+      // would re-broadcast the just-replayed values as this end's own (same
+      // rule as design-canvas's viewport applier).
+      clearTimeout(emitTRef.current);
+      emitTRef.current = 0;
+      const st = s.current;
+      // While playing, advance the replayed time by the transport delay so
+      // both playheads aim at the same wall-clock frame. A looping stage
+      // wraps rather than clamps — a snapshot sent near the seam would
+      // otherwise pin the follower on the last frame until its own rAF
+      // wraps.
+      const lat = m.playing && ctx && Number.isFinite(ctx.latencyMs) ? ctx.latencyMs / 1000 : 0;
+      const nt = m.t + lat;
+      // Double-mod wrap: JS % keeps the sign, and a (forged/skewed) negative
+      // t would otherwise render a negative playhead.
+      st.setTime(m.playing && st.loop && st.duration > 0 ? ((nt % st.duration) + st.duration) % st.duration : clamp(nt, 0, st.duration));
+      st.setPlaying(!!m.playing);
+      lastApplyTsRef.current = Date.now();
+      return { type: 'applied' };
+    });
+    return () => {
+      offApply();
+      if (window.__animStage === bridge) delete window.__animStage;
+    };
   }, []);
 
   // Animation loop
@@ -457,12 +620,16 @@ function Stage({
       if (e.code === 'Space') {
         e.preventDefault();
         setPlaying(p => !p);
+        emitPlayhead();
       } else if (e.code === 'ArrowLeft') {
         setTime(t => clamp(t - (e.shiftKey ? 1 : 0.1), 0, duration));
+        emitPlayhead();
       } else if (e.code === 'ArrowRight') {
         setTime(t => clamp(t + (e.shiftKey ? 1 : 0.1), 0, duration));
+        emitPlayhead();
       } else if (e.key === '0' || e.code === 'Home') {
         setTime(0);
+        emitPlayhead();
       }
     };
     window.addEventListener('keydown', onKey);
@@ -519,9 +686,9 @@ function Stage({
           time={time}
           duration={duration}
           playing={playing}
-          onPlayPause={() => setPlaying(p => !p)}
-          onReset={() => { setTime(0); }}
-          onSeek={(t) => setTime(t)}
+          onPlayPause={() => { setPlaying(p => !p); emitPlayhead(); }}
+          onReset={() => { setTime(0); emitPlayhead(); }}
+          onSeek={(t) => { setTime(t); emitPlayhead(); }}
         />
       )}
     </div>

package/components/design-canvas.jsx

@@ -32,6 +32,9 @@
 // On mobile devices the canvas automatically becomes a browse-only surface
 // (touch pan/zoom, editing disabled). This needs NO authoring changes:
 // never add custom touch handling or mobile-specific layouts.
+//
+// window.__miaodaMirror (defined below) is Magic-Share sync plumbing between
+// this component and the miaoda host — internal; do not call or remove it.
 /* END USAGE */
 
 const DC = {
@@ -54,6 +57,82 @@ const dcIsMobile = typeof navigator !== 'undefined' &&
   (DC_MOBILE_UA_RE.test(navigator.userAgent) ||
     (/iPad|Tab|Tablet/i.test(navigator.userAgent) && !!navigator.maxTouchPoints && navigator.maxTouchPoints > 1));
 
+// Capture iframes (?thumbnail= product screenshots) sit out Magic Share in
+// BOTH directions — same rule as deck-stage's _snthumb and animations'
+// captureMode: their emits would carry a throwaway instance's state, and a
+// (mis)forwarded replay could reframe the canvas mid-shot.
+const dcCaptureMode = typeof location !== 'undefined' && /[?&](_snthumb|thumbnail)=/.test(location.search || '');
+
+// ── Mirror sync singleton ──────────────────────────────────────────────────
+// Shared by every buildless script on the page (first one to load defines
+// it). Inlined per script rather than shipped as its own registry file:
+// call sites use the global bare, so inlining is what guarantees
+// definition-before-use — a separate copy-in file would add a whole "SDK
+// copied but <script> tag missing" failure mode. Keep this block identical
+// across deck-stage.js / design-canvas.jsx / animations.jsx — same
+// convention as the mobile-UA regex. Two halves of
+// the 妙享 (Magic Share) mirror protocol:
+//   emit(msg, opts)   — stamps msg.__mirror so the host relay treats the
+//                       message as a broadcastable UI-state snapshot;
+//                       unstamped messages are never mirrored. opts.key is
+//                       the sync channel (maps to the share SDK's
+//                       actionType): late joiners receive only the LATEST
+//                       snapshot per key, so states that overwrite each
+//                       other must share one key. opts.throttle is the
+//                       suggested host-side coalescing interval in ms —
+//                       snapshots make dropped intermediate frames
+//                       lossless, so hint it on any continuous gesture.
+//   onApply(type, fn) — replay entry for a message type this script itself
+//                       emits. The host sends {type:'miaoda:mirror:apply',
+//                       uuid, message, latencyMs} and needs
+//                       {type:'miaoda:mirror:apply-result', uuid, result}
+//                       back to drive the SDK's retry: result.type
+//                       'failed' means retry (use it for transient
+//                       not-ready states), 'ignored' is terminal (not
+//                       applicable / bad payload), 'applied' is success.
+//                       Unregistered types stay silent on purpose —
+//                       another script on the page may own them, and the
+//                       host's timeout is the backstop.
+if (!window.__miaodaMirror) {
+  const appliers = new Map(); // message.type -> Set<fn>
+  window.__miaodaMirror = {
+    emit(msg, opts) {
+      try { window.parent.postMessage(Object.assign({}, msg, { __mirror: Object.assign({ v: 1 }, opts) }), '*'); } catch (e) {}
+    },
+    onApply(type, fn) {
+      if (!appliers.has(type)) appliers.set(type, new Set());
+      appliers.get(type).add(fn);
+      return () => { const s = appliers.get(type); if (s) s.delete(fn); };
+    },
+  };
+  window.addEventListener('message', async (e) => {
+    // Replays are accepted from the host frame only — generated pages embed
+    // arbitrary third-party iframes, any of which could otherwise forge an
+    // apply and drive state (plus its persisted side effects).
+    if (e.source !== window.parent) return;
+    const d = e.data;
+    if (!d || d.type !== 'miaoda:mirror:apply' || !d.message || !d.message.type) return;
+    const fns = appliers.get(d.message.type);
+    if (!fns || !fns.size) return;
+    // Merge across handlers (multi-instance case): one success is enough.
+    // Instances share a channel, so a sibling that can't apply yet (a lazily
+    // slotted second deck returning 'failed') must not poison an applied
+    // result into an SDK retry storm of no-ops — 'failed' only stands when
+    // nobody applied. Every handler still runs (no short-circuit) so each
+    // sibling instance gets the state.
+    let result = { type: 'ignored', reason: 'no applier result' };
+    for (const fn of Array.from(fns)) {
+      let r;
+      try { r = await fn(d.message, { latencyMs: d.latencyMs, uuid: d.uuid }); }
+      catch (err) { r = { type: 'failed', reason: String((err && err.message) || err) }; }
+      if (!r) continue;
+      if (r.type === 'applied') result = r;
+      else if (result.type !== 'applied' && (r.type === 'failed' || result.type !== 'failed')) result = r;
+    }
+    try { window.parent.postMessage({ type: 'miaoda:mirror:apply-result', uuid: d.uuid, result }, '*'); } catch (e2) {}
+  });
+}
+
 // One-time CSS injection (classes are dc-prefixed so they don't collide with
 // the hosted design's own styles).
 if (typeof document !== 'undefined' && !document.getElementById('dc-styles')) {
@@ -228,10 +307,23 @@ function dcFlatten(children) {
 // ─────────────────────────────────────────────────────────────
 const DC_STATE_FILE = '.design-canvas.state.json';
 
-// Persist a sidecar file back to the host.
-function miaodaWriteFile(path, content) {
+// Persist a sidecar file back to the host. writeContext is an OWNERSHIP
+// declaration for the host's release pipeline (not a sync receipt — the
+// product can't know whether a Magic Share sync actually reached anyone):
+// {kind:'mirror-managed', key} says this file's full content is the same
+// state a mirror channel carries, so the host may skip reloading followers
+// in FOLLOW mode for a release made purely of such writes — they already
+// have the state via mirror, and channel guarantees (retry / per-key latest
+// on rejoin / re-seed after reload / the file itself on next cold load)
+// cover every miss. Persistence and deploy proceed unchanged — this is NOT
+// a notify:false. Only declare it where emit and write are fed by the very
+// same snapshot — an untagged write reloads as before, which is the
+// fail-safe for states that are NOT mirrored.
+function miaodaWriteFile(path, content, writeContext) {
   try {
-    window.parent.postMessage({ type: 'miaoda:bridge:write-file', path: path, content: content }, '*');
+    const msg = { type: 'miaoda:bridge:write-file', path: path, content: content };
+    if (writeContext) msg.writeContext = writeContext;
+    window.parent.postMessage(msg, '*');
   } catch (e) {
     /* no parent — ignore */
   }
@@ -248,13 +340,30 @@ function DesignCanvas({ children, minScale, maxScale, style }) {
   const [ready, setReady] = React.useState(false);
   const didRead = React.useRef(false);
   const skipNextWrite = React.useRef(false);
+  // Magic Share echo guards, one per mirrored state: a remote apply must land
+  // locally without re-broadcasting as if the user did it here.
+  const skipNextMirrorEmit = React.useRef(false);
+  const skipNextFocusEmit = React.useRef(false);
+  // Current focus, readable synchronously by the applier — an apply carrying
+  // the value we already hold must NOT set the skip flag: same-value setState
+  // re-renders but the [state.focus] effect bails out (primitive dep), so the
+  // flag would strand and swallow the next real focus broadcast.
+  const focusRef = React.useRef(state.focus);
+  focusRef.current = state.focus;
+
+  // Set once a Magic Share structure replay has landed. A late joiner's
+  // replay races the sidecar fetch below — the replay is the fresher truth
+  // (it IS the presenter's current arrangement, and it was already answered
+  // with 'applied' so the SDK won't resend), so a slower fetch must not
+  // clobber it with this end's stale sidecar.
+  const mirrorSeeded = React.useRef(false);
 
   React.useEffect(() => {
     let off = false;
     fetch('./' + DC_STATE_FILE)
       .then((r) => (r.ok ? r.json() : null))
       .then((saved) => {
-        if (off || !saved || !saved.sections) return;
+        if (off || mirrorSeeded.current || !saved || !saved.sections) return;
         skipNextWrite.current = true;
         setState((s) => ({ ...s, sections: saved.sections }));
       })
@@ -266,13 +375,78 @@ function DesignCanvas({ children, minScale, maxScale, style }) {
 
   React.useEffect(() => {
     if (!didRead.current) return;
+    // Magic Share: snapshot the arrangement whenever it settles — including
+    // the sidecar hydration (the skipNextWrite path), which is exactly the
+    // baseline a late-joining follower needs. Only a remote apply must not
+    // re-broadcast.
+    if (skipNextMirrorEmit.current) skipNextMirrorEmit.current = false;
+    else if (!dcCaptureMode) window.__miaodaMirror.emit({ type: 'miaoda:canvas:structure-changed', sections: state.sections }, { key: 'canvas:structure' });
     if (skipNextWrite.current) { skipNextWrite.current = false; return; }
     const t = setTimeout(() => {
-      miaodaWriteFile(DC_STATE_FILE, JSON.stringify({ sections: state.sections })).catch(() => {});
+      // mirror-managed precondition: this write persists the same snapshot
+      // the emit above carried on canvas:structure — keep both fed by the
+      // same state if either moves.
+      miaodaWriteFile(DC_STATE_FILE, JSON.stringify({ sections: state.sections }),
+        { kind: 'mirror-managed', key: 'canvas:structure' }).catch(() => {});
     }, 250);
     return () => clearTimeout(t);
   }, [state.sections]);
 
+  // Magic Share: focus is ephemeral view state — mirror it as its own key so
+  // a follower enters/exits the focus overlay in step with the presenter.
+  React.useEffect(() => {
+    if (dcCaptureMode) return;
+    if (skipNextFocusEmit.current) { skipNextFocusEmit.current = false; return; }
+    window.__miaodaMirror.emit({ type: 'miaoda:canvas:focus-changed', focus: state.focus }, { key: 'canvas:focus' });
+  }, [state.focus]);
+
+  // Magic Share replay entries — consume the same message types this
+  // component emits, so the emit↔apply contract stays in this one file.
+  React.useEffect(() => {
+    if (dcCaptureMode) return;
+    const offs = [
+      window.__miaodaMirror.onApply('miaoda:canvas:structure-changed', (m) => {
+        // Per-field shape check, not just typeof: a malformed snapshot (e.g.
+        // order that isn't an array) would pass setState here, be answered
+        // 'applied', and only then blow up the whole React tree in render —
+        // an unrecoverable failure the retry protocol can't see.
+        if (!m.sections || typeof m.sections !== 'object') return { type: 'ignored', reason: 'no sections' };
+        for (const sec of Object.values(m.sections)) {
+          if (!sec || typeof sec !== 'object' ||
+              (sec.order !== undefined && !Array.isArray(sec.order)) ||
+              (sec.hidden !== undefined && !Array.isArray(sec.hidden)) ||
+              (sec.labels !== undefined && (typeof sec.labels !== 'object' || sec.labels === null))) {
+            return { type: 'ignored', reason: 'malformed sections' };
+          }
+        }
+        skipNextMirrorEmit.current = true;
+        // A replayed arrangement is the presenter's state, not a local edit —
+        // never persist it back through this end's write bridge.
+        skipNextWrite.current = true;
+        // Marking didRead lets the sections effect run NOW and consume both
+        // flags — before hydration settles they would otherwise strand on the
+        // effect's !didRead early-return and swallow a later real emit/write.
+        mirrorSeeded.current = true;
+        didRead.current = true;
+        setState((s) => ({ ...s, sections: m.sections }));
+        return { type: 'applied' };
+      }),
+      window.__miaodaMirror.onApply('miaoda:canvas:focus-changed', (m) => {
+        const next = typeof m.focus === 'string' ? m.focus : null;
+        // Same value → nothing will change and the [state.focus] effect won't
+        // re-run; setting the skip flag would strand it (see focusRef note).
+        if (next === focusRef.current) return { type: 'applied' };
+        // Sync the ref now, not at next render — a second apply landing in
+        // the same tick would otherwise compare against the stale value.
+        focusRef.current = next;
+        skipNextFocusEmit.current = true;
+        setState((s) => ({ ...s, focus: next }));
+        return { type: 'applied' };
+      }),
+    ];
+    return () => offs.forEach((off) => off());
+  }, []);
+
   // Build registries synchronously from children so FocusOverlay can read
   // them in the same render. Fragments are flattened; wrapping in other
   // elements still opts out of focus/reorder.
@@ -466,6 +640,16 @@ function DCViewport({ children, minScale = 0.1, maxScale = 8, style = {} }) {
   const saveT = React.useRef(0);
 
   const lastPostedScale = React.useRef();
+  // Magic Share: trailing-throttle timer for the viewport snapshot, plus a
+  // guard so a replayed viewport doesn't schedule its own re-broadcast.
+  const mirrorEmitT = React.useRef(0);
+  const applyingRemoteView = React.useRef(false);
+  // True while tf holds a REMOTE framing (last write came from a replay,
+  // no local gesture since). Gates every localStorage persist path — the
+  // 200ms saveT and the pagehide/unmount flush both read tf at fire time,
+  // so guarding only the scheduling call would still leak the presenter's
+  // framing into this viewer's saved viewport.
+  const viewIsRemote = React.useRef(false);
   // Imperative handle for the on-canvas zoom control to zoom around the
   // viewport centre (same path as the host's set-zoom message). Assigned in
   // the pointer/wheel effect below where zoomAt is in scope.
@@ -500,12 +684,36 @@ function DCViewport({ children, minScale = 0.1, maxScale = 8, style = {} }) {
     // ticks leave scale unchanged — skip the cross-frame post for those.
     if (lastPostedScale.current !== scale) {
       lastPostedScale.current = scale;
-      window.parent.postMessage({ type: 'miaoda:canvas:zoom', scale }, '*');
+      try { window.parent.postMessage({ type: 'miaoda:canvas:zoom', scale }, '*'); } catch (e) { /* no parent — ignore */ }
+    }
+    // A replayed viewport is the presenter's framing, not this viewer's — it
+    // must not overwrite the viewport this end will restore when opening the
+    // canvas on its own later. Any local gesture re-owns the view (and its
+    // persistence); apply() is the single fan-out for both, so this branch
+    // is the one place that distinction needs to live.
+    if (applyingRemoteView.current) {
+      viewIsRemote.current = true;
+    } else {
+      viewIsRemote.current = false;
+      clearTimeout(saveT.current);
+      saveT.current = setTimeout(() => {
+        try { localStorage.setItem(tfKey, JSON.stringify(tf.current)); } catch {}
+      }, 200);
+    }
+    // Magic Share: mirror the full viewport (scale AND pan) as a snapshot.
+    // Trailing-throttled at 120ms rather than per-apply — apply() runs at
+    // pointer rate, and this file deliberately avoids per-frame cross-frame
+    // posts (see the zoom guard above); 120ms keeps a follower tracking a
+    // continuous pan without that cost.
+    if (!dcCaptureMode && !applyingRemoteView.current && !mirrorEmitT.current) {
+      mirrorEmitT.current = setTimeout(() => {
+        mirrorEmitT.current = 0;
+        window.__miaodaMirror.emit(
+          { type: 'miaoda:canvas:viewport-changed', x: tf.current.x, y: tf.current.y, scale: tf.current.scale },
+          { key: 'canvas:viewport', throttle: 60 },
+        );
+      }, 120);
     }
-    clearTimeout(saveT.current);
-    saveT.current = setTimeout(() => {
-      try { localStorage.setItem(tfKey, JSON.stringify(tf.current)); } catch {}
-    }, 200);
   }, [tfKey]);
 
   // Whether the mount-time restore found a saved viewport — when it did, the
@@ -516,6 +724,9 @@ function DCViewport({ children, minScale = 0.1, maxScale = 8, style = {} }) {
   React.useLayoutEffect(() => {
     const flush = () => {
       clearTimeout(saveT.current);
+      // Unload/unmount with a replayed framing on screen: persist nothing —
+      // the saved viewport must stay this viewer's own.
+      if (viewIsRemote.current) return;
       try { localStorage.setItem(tfKey, JSON.stringify(tf.current)); } catch {}
     };
     try {
@@ -846,16 +1057,48 @@ function DCViewport({ children, minScale = 0.1, maxScale = 8, style = {} }) {
         // images/fonts is after our mount-time announce, so re-announce.
         // Clear the pan-tick guard so apply() re-posts the current scale
         // even if it's unchanged — the host just reset dcScale to 1.
-        window.parent.postMessage({ type: 'miaoda:canvas:present' }, '*');
+        try { window.parent.postMessage({ type: 'miaoda:canvas:present' }, '*'); } catch (e) { /* no parent — ignore */ }
         // Re-announce the upgrade capability too — the host's readyGen reset
         // (fires on iframe 'load', which for image/font-heavy canvases lands
         // after the mount-time announce) drops prior state, so re-declare here.
-        window.parent.postMessage({ type: 'miaoda:upgrade:available', kind: 'design-canvas' }, '*');
+        try { window.parent.postMessage({ type: 'miaoda:upgrade:available', kind: 'design-canvas' }, '*'); } catch (e) { /* no parent — ignore */ }
         lastPostedScale.current = undefined;
+        // The re-announce apply() must not change who owns the view: a
+        // viewport seed can land BEFORE the iframe's native 'load' fires this
+        // probe, and a plain local apply() would flip viewIsRemote and
+        // persist the presenter's framing — the exact leak viewIsRemote
+        // exists to stop. The zoom % re-post is ungated either way.
+        applyingRemoteView.current = viewIsRemote.current;
         apply();
+        applyingRemoteView.current = false;
       }
     };
     window.addEventListener('message', onHostMsg);
+    // Magic Share replay entry for the viewport — reuses the local apply()
+    // pipeline (DOM transform, --dc-inv-zoom, host % readout); the
+    // applyingRemoteView guard keeps the replay from re-broadcasting or
+    // persisting the presenter's framing.
+    const offViewportApply = dcCaptureMode ? () => {} : window.__miaodaMirror.onApply('miaoda:canvas:viewport-changed', (m) => {
+      if (![m.x, m.y, m.scale].every(Number.isFinite)) return { type: 'ignored', reason: 'bad snapshot' };
+      // Kill any pending local-emit timer: it was armed before this replay
+      // and would otherwise fire 120ms later with tf already holding the
+      // REMOTE state — echoing the presenter's viewport back as our own.
+      clearTimeout(mirrorEmitT.current);
+      mirrorEmitT.current = 0;
+      // Same staleness for the persist timer: scheduled by a local gesture,
+      // but it reads tf at fire time and would save the remote framing.
+      clearTimeout(saveT.current);
+      // A replayed framing IS this canvas's framing now — mark the first-visit
+      // fit as satisfied, or its layout effect (armed whenever a fresh viewer
+      // has no saved viewport) would re-measure and override the presenter's
+      // viewport as soon as content mounts.
+      didFit.current = true;
+      applyingRemoteView.current = true;
+      tf.current = { x: m.x, y: m.y, scale: Math.min(maxScale, Math.max(minScale, m.scale)) };
+      apply();
+      applyingRemoteView.current = false;
+      return { type: 'applied' };
+    });
     // Announce canvas mode so the host toolbar proxies its % control here
     // instead of scaling the iframe element (which would just shrink the
     // viewport window of an infinite canvas). The apply() that follows emits
@@ -863,13 +1106,13 @@ function DCViewport({ children, minScale = 0.1, maxScale = 8, style = {} }) {
     // lastPostedScale reset mirrors the miaoda:canvas:probe handler: the layout
     // effect's restore-path apply() may already have posted the restored
     // scale (before miaoda:canvas:present), so clear the guard to re-post it in order.
-    window.parent.postMessage({ type: 'miaoda:canvas:present' }, '*');
+    try { window.parent.postMessage({ type: 'miaoda:canvas:present' }, '*'); } catch (e) { /* no parent — ignore */ }
     // Generic "upgrade" capability signal — announce that this artifact offers
     // an upgrade entry so the host can show/hide its upgrade button. Decoupled
     // from the canvas zoom-proxy protocol above; any product may post the same
     // message. Listener (onHostMsg) is already registered above → announce-after-
     // register order holds. No client-side behavior here.
-    window.parent.postMessage({ type: 'miaoda:upgrade:available', kind: 'design-canvas' }, '*');
+    try { window.parent.postMessage({ type: 'miaoda:upgrade:available', kind: 'design-canvas' }, '*'); } catch (e) { /* no parent — ignore */ }
     lastPostedScale.current = undefined;
     apply();
 
@@ -889,6 +1132,9 @@ function DCViewport({ children, minScale = 0.1, maxScale = 8, style = {} }) {
     vp.addEventListener('pointercancel', pu);
     return () => {
       window.removeEventListener('message', onHostMsg);
+      offViewportApply();
+      clearTimeout(mirrorEmitT.current);
+      mirrorEmitT.current = 0;
       vp.removeEventListener('wheel', onWheel);
       vp.removeEventListener('gesturestart', onGestureStart);
       vp.removeEventListener('gesturechange', onGestureChange);

package/components/tweaks-panel.jsx

@@ -190,7 +190,7 @@ function useTweaks(defaults) {
     const edits = typeof keyOrEdits === 'object' && keyOrEdits !== null
       ? keyOrEdits : { [keyOrEdits]: val };
     setValues((prev) => ({ ...prev, ...edits }));
-    window.parent.postMessage({ type: 'miaoda:tweaks:set-keys', edits }, '*');
+    try { window.parent.postMessage({ type: 'miaoda:tweaks:set-keys', edits }, '*'); } catch (e) { /* no parent — ignore */ }
     // Same-window signal so in-page listeners (deck-stage rail thumbnails)
     // can react — the parent message only reaches the host, not peers.
     window.dispatchEvent(new CustomEvent('tweakchange', { detail: edits }));
@@ -248,13 +248,13 @@ function TweaksPanel({ title = 'Tweaks', children }) {
       else if (t === 'miaoda:tweaks:deactivate') setOpen(false);
     };
     window.addEventListener('message', onMsg);
-    window.parent.postMessage({ type: 'miaoda:tweaks:available' }, '*');
+    try { window.parent.postMessage({ type: 'miaoda:tweaks:available' }, '*'); } catch (e) { /* no parent — ignore */ }
     return () => window.removeEventListener('message', onMsg);
   }, []);
 
   const dismiss = () => {
     setOpen(false);
-    window.parent.postMessage({ type: 'miaoda:tweaks:dismissed' }, '*');
+    try { window.parent.postMessage({ type: 'miaoda:tweaks:dismissed' }, '*'); } catch (e) { /* no parent — ignore */ }
   };
 
   const onDragStart = (e) => {
@@ -586,8 +586,11 @@ Object.assign(window, {
   document.head.appendChild(s);
 })();
 
-const __twkSendChat = (text) =>
-  window.parent.postMessage({ type: 'miaoda:tweaks:chat', text }, '*');
+const __twkSendChat = (text) => {
+  // Posting to the host must never take the component down: the parent frame can be
+  // cross-origin or already gone, and postMessage throws in both cases.
+  try { window.parent.postMessage({ type: 'miaoda:tweaks:chat', text }, '*'); } catch (e) { /* no parent — ignore */ }
+};
 
 const __TWK_SPARK_PATH = 'M18.3658 62.2435L36.7823 51.9165L37.0858 51.012L36.7823 50.5083H35.8716L32.7853 50.3206L22.2616 50.0389L13.1546 49.6634L4.30054 49.194L2.07438 48.7246L0 45.9551L0.202378 44.5938L2.07438 43.3264L4.75589 43.5611L10.6755 43.9836L19.5801 44.5938L26.0056 44.9693L35.568 45.9551H37.0858L37.2882 45.3448L36.7823 44.9693L36.3775 44.5938L27.1693 38.3507L17.2022 31.7789L11.9909 27.9767L9.20822 26.0522L7.79157 24.2684L7.18443 20.3254L9.71416 17.5089L13.1546 17.7436L14.0147 17.9783L17.5057 20.654L24.9431 26.4277L34.6573 33.5627L36.0739 34.7362L36.6444 34.3512L36.7317 34.079L36.0739 32.9994L30.8121 23.4704L25.1961 13.7537L22.6664 9.71675L22.0086 7.32277C21.7539 6.31812 21.6039 5.48695 21.6039 4.45938L24.4878 0.516349L26.1068 0L30.0026 0.516349L31.6216 1.92457L34.0502 7.46359L37.9459 16.1476L44.0173 27.9767L45.7881 31.4973L46.7494 34.7362L47.1036 35.722H47.7107V35.1587L48.2166 28.4931L49.1274 20.3254L50.0381 9.81063L50.3416 6.85336L51.8089 3.28586L54.7434 1.36128L57.0201 2.44092L58.8921 5.11655L58.6391 6.85336L57.5261 14.0822L55.3505 25.395L53.9338 32.9994H54.7434L55.7047 32.0136L59.5498 26.944L65.9753 18.8702L68.8086 15.6782L72.1479 12.1577L74.2729 10.4678H78.3204L81.2549 14.8802L79.9395 19.4335L75.7907 24.6909L72.3503 29.1503L67.4173 35.7593L64.3563 41.0732L64.6308 41.5116L65.3682 41.4487L76.499 39.0548L82.5198 37.9751L89.7042 36.7547L92.9423 38.2568L93.2964 39.8058L92.0316 42.9509L84.3412 44.8285L75.3354 46.6592L61.9245 49.8162L61.776 49.9356L61.9513 50.1956L67.9991 50.743L70.5795 50.8839H76.9038L88.6923 51.7757L91.7786 53.7942L93.6 56.282L93.2964 58.2066L88.5405 60.6006L82.1656 59.0985L67.2402 55.531L62.1302 54.2636H61.4218V54.6861L65.6718 58.8638L73.514 65.9049L83.2787 75.0114L83.7846 77.2646L82.5198 79.0483L81.2043 78.8606L72.6032 72.3827L69.264 69.4724L61.776 63.1354H61.2701V63.7926L62.9903 66.3274L72.1479 80.081L72.6032 84.3057L71.9455 85.667L69.5676 86.5119L66.9872 86.0425L61.5736 78.4851L56.0588 70.0357L51.6065 62.4313L51.0687 62.7708L48.419 91.0652L47.2048 92.5204L44.3715 93.6L41.9935 91.8162L40.7286 88.9059L41.9935 83.1322L43.5114 75.6217L44.7256 69.6602L45.8387 62.2435L46.5185 59.7659L46.4584 59.6001L45.9153 59.6914L40.3239 67.3601L31.824 78.8606L25.0949 86.0425L23.4759 86.6997L20.6932 85.2445L20.9462 82.6628L22.5146 80.3627L31.824 68.5336L37.44 61.1639L41.0595 56.9335L41.0243 56.3216L40.8245 56.3046L16.0891 72.4297L11.6874 72.993L9.76476 71.2092L10.0177 68.2989L10.9284 67.3601L18.3658 62.2435Z';