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

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.
@@ -502,10 +686,34 @@ function DCViewport({ children, minScale = 0.1, maxScale = 8, style = {} }) {
       lastPostedScale.current = scale;
       window.parent.postMessage({ type: 'miaoda:canvas:zoom', scale }, '*');
     }
-    clearTimeout(saveT.current);
-    saveT.current = setTimeout(() => {
-      try { localStorage.setItem(tfKey, JSON.stringify(tf.current)); } catch {}
-    }, 200);
+    // 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);
+    }
   }, [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 {
@@ -852,10 +1063,42 @@ function DCViewport({ children, minScale = 0.1, maxScale = 8, style = {} }) {
         // after the mount-time announce) drops prior state, so re-declare here.
         window.parent.postMessage({ type: 'miaoda:upgrade:available', kind: 'design-canvas' }, '*');
         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
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-registry-buildless",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "Miaoda registry (buildless runtime) — shadcn-style copy-in SDKs (globals + CDN-pinned, browser Babel) for buildless static HTML stacks",
   "type": "module",
   "files": [

package/scripts/deck-stage.js

@@ -111,11 +111,86 @@
  *       @media (prefers-reduced-motion:no-preference){ [data-deck-active] .fade-up{ animation: fadeUp .5s both } }
  *       @keyframes fadeUp { from{ opacity:0; transform:translateY(24px) } to{ opacity:1; transform:none } }
  *     Avoid infinite decorative loops on slide content.
+ *
+ * window.__miaodaMirror (defined below) is Magic-Share sync plumbing between
+ * this component and the miaoda host — internal; do not call it from slide
+ * code or remove it.
  */
 /* END USAGE */
 
 (() => {
   if (typeof window === 'undefined') return;
+
+  // ── 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) {}
+    });
+  }
+
   const DESIGN_W_DEFAULT = 1920;
   const DESIGN_H_DEFAULT = 1080;
   // Safe margin around the scaled slide in edit/preview (non-presenting) mode,
@@ -880,6 +955,57 @@
       });
       // Announce to the host that this product IS a deck scene.
       try { window.parent.postMessage({ type: 'miaoda:deck:available' }, '*'); } catch (e) {}
+      // Magic Share replay entries — each consumes the very message type this
+      // component emits, so the emit↔apply contract lives in one file and is
+      // version-consistent on both ends of a share by construction. Replays
+      // route through the same internal paths as local interaction (_go, the
+      // miaoda:deck:* inbound handlers); the re-emit those paths produce is
+      // the host role gate's to drop (the protocol's first anti-echo layer).
+      // Synthetic replays through _onMessage run under _applyingMirror so the
+      // handlers can tell "presenter state to render" from "this viewer's own
+      // choice to persist" (see the rail localStorage guard).
+      const applyViaOnMessage = (data) => {
+        this._applyingMirror = true;
+        try { this._onMessage({ data }); } finally { this._applyingMirror = false; }
+      };
+      // Capture iframes navigate on their own — the emit side stays unstamped
+      // there for exactly that reason, and the replay entries stay
+      // unregistered symmetrically so a (mis)forwarded apply can't steer a
+      // pinned thumbnail either.
+      this._mirrorOff = this._snthumb ? [] : [
+        window.__miaodaMirror.onApply('miaoda:deck:slide-changed', (m) => {
+          // isFinite, not typeof: NaN|0 would silently land on slide 1.
+          if (!Number.isFinite(m.index) || m.index < 0) return { type: 'ignored', reason: 'bad index' };
+          // Slides are collected by slotchange AFTER connectedCallback, so a
+          // late joiner's replay can beat them — that's transient, and only
+          // 'failed' makes the SDK retry ('ignored' would strand the joiner
+          // on slide 1).
+          if (!this._slides.length) return { type: 'failed', reason: 'no slides yet' };
+          const requested = m.index | 0;
+          const clamped = Math.max(0, Math.min(this._slides.length - 1, requested));
+          if (clamped !== requested) {
+            // Fewer slides than the presenter (reload lag after an agent
+            // edit): show the nearest page as best effort, but answer
+            // 'failed' so the SDK keeps retrying until the slide exists —
+            // 'applied' here would strand this end on the clamped page.
+            if (clamped !== this._index) this._go(clamped, 'api');
+            return { type: 'failed', reason: 'requested slide not present yet' };
+          }
+          if (clamped === this._index) return { type: 'applied' };
+          this._go(clamped, 'api');
+          return this._index === clamped ? { type: 'applied' } : { type: 'failed', reason: 'goto did not land' };
+        }),
+        window.__miaodaMirror.onApply('miaoda:deck:presenting-changed', (m) => {
+          if (typeof m.on !== 'boolean') return { type: 'ignored', reason: 'no on' };
+          applyViaOnMessage({ type: 'miaoda:deck:presenting', on: m.on });
+          return { type: 'applied' };
+        }),
+        window.__miaodaMirror.onApply('miaoda:deck:rail-visible-changed', (m) => {
+          if (typeof m.on !== 'boolean') return { type: 'ignored', reason: 'no on' };
+          applyViaOnMessage({ type: 'miaoda:deck:rail-visible', on: m.on });
+          return { type: 'applied' };
+        }),
+      ];
     }
 
     _enableRail() {
@@ -1235,6 +1361,8 @@
       if (this._headObserver) this._headObserver.disconnect();
       (this._thumbs || []).forEach((t) => clearTimeout(t._canvasRecapTimer));
       if (this._onTweakChange) window.removeEventListener('tweakchange', this._onTweakChange);
+      (this._mirrorOff || []).forEach((off) => off());
+      this._mirrorOff = null;
     }
 
     attributeChangedCallback() {
@@ -1689,6 +1817,16 @@
       if (n >= 0 && n !== this._index) this._go(n, 'api');
     }
 
+    // Single home for the capture-iframe rule: presenter-popup thumbnails
+    // (_snthumb) navigate on their own, so nothing they post may carry the
+    // Magic Share stamp — a stamped emit from a pinned N±1 thumbnail would
+    // broadcast conflicting state. Route every stamp through here so a new
+    // emit site can't forget the rule.
+    _stampMirror(msg, key) {
+      if (!this._snthumb) msg.__mirror = { v: 1, key: key };
+      return msg;
+    }
+
     _applyIndex({ broadcast = true, reason = 'init' } = {}) {
       if (!this._slides.length) return;
       const prev = this._prevIndex == null ? -1 : this._prevIndex;
@@ -1718,8 +1856,14 @@
       this._syncNotesBody();
 
       if (broadcast) {
-        // (1) Parent-window postMessage for speaker-notes renderers.
-        try { window.parent.postMessage({ type: 'miaoda:deck:slide-changed', index: curr, total: this._slides.length, skipped: this._skippedIndices() }, '*'); } catch (e) {}
+        // (1) Parent-window postMessage for speaker-notes renderers, stamped
+        //     __mirror for Magic Share. Capture iframes (presenter-popup
+        //     thumbnails pinned to N±1) navigate on their own — stamping them
+        //     would broadcast conflicting indices, so they stay unstamped.
+        try {
+          const msg = { type: 'miaoda:deck:slide-changed', index: curr, total: this._slides.length, skipped: this._skippedIndices() };
+          window.parent.postMessage(this._stampMirror(msg, 'deck:slide'), '*');
+        } catch (e) {}
 
         // (2) In-page CustomEvent on the <deck-stage> element itself.
         //     Bubbles and composes out of shadow DOM so slide code can listen:
@@ -1977,6 +2121,10 @@
     _onMessage(e) {
       const d = e.data;
       if (d && d.type === 'miaoda:deck:presenting' && typeof d.on === 'boolean') {
+        // Same-value messages (incl. mirror replays routed back through here)
+        // must not re-run the layout work or re-emit. _presenting starts
+        // undefined, so the first message always lands.
+        if (d.on === this._presenting) return;
         this._presenting = d.on;
         this._syncMobileMode();
         if (!d.on) this._toggleMobUi(false);
@@ -1985,6 +2133,9 @@
         this._closeMenu();
         this._fit();
         this._scaleThumbs();
+        // Presenting is host-driven, so the inbound handler is the one place
+        // the state settles — snapshot it out for Magic Share from here.
+        try { window.parent.postMessage(this._stampMirror({ type: 'miaoda:deck:presenting-changed', on: d.on }, 'deck:presenting'), '*'); } catch (e) {}
       }
       // Host's Preview segment (ViewerMode='none'): the rail's drag-reorder /
       // right-click skip-delete affordances are editing chrome, so hide it
@@ -2007,9 +2158,14 @@
       if (d && d.type === 'miaoda:deck:rail-visible' && typeof d.on === 'boolean') {
         if (d.on === this._railVisible) return;
         this._railVisible = d.on;
-        try { localStorage.setItem('deck-stage.railVisible', d.on ? '1' : '0'); } catch (e) {}
+        // Rail visibility is a per-viewer preference — a mirror replay drives
+        // the visual state but must not overwrite what this viewer chose for
+        // themselves after the share ends.
+        if (!this._applyingMirror) {
+          try { localStorage.setItem('deck-stage.railVisible', d.on ? '1' : '0'); } catch (e) {}
+        }
         // Notify the parent so its toolbar state stays in sync.
-        try { window.parent.postMessage({ type: 'miaoda:deck:rail-visible-changed', on: d.on }, '*'); } catch (e) {}
+        try { window.parent.postMessage(this._stampMirror({ type: 'miaoda:deck:rail-visible-changed', on: d.on }, 'deck:rail-visible'), '*'); } catch (e) {}
         // Arm the transition, commit it, then flip state — otherwise the
         // browser coalesces both writes and nothing animates on show.
         this.setAttribute('data-rail-anim', '');
@@ -2132,6 +2288,9 @@
         this._fit();
         this._toggleMobUi(false);
         try { window.parent.postMessage({ type: 'miaoda:deck:presenting-dismissed' }, '*'); } catch (err) {}
+        // The mobile back button flips presenting locally (no host round-trip),
+        // so mirror the settled state from here too.
+        try { window.parent.postMessage(this._stampMirror({ type: 'miaoda:deck:presenting-changed', on: false }, 'deck:presenting'), '*'); } catch (e) {}
       });
       const strip = document.createElement('div');
       strip.className = 'mob-strip';
@@ -2742,7 +2901,10 @@
       this._emitDeckChange({ action: on ? 'skip' : 'unskip', from: i, slide });
       // Re-broadcast so the presenter popup's prev/next thumbnails re-pick
       // the nearest non-skipped slide without waiting for a nav event.
-      try { window.parent.postMessage({ type: 'miaoda:deck:slide-changed', index: this._index, total: this._slides.length, skipped: this._skippedIndices() }, '*'); } catch (e) {}
+      try {
+        const msg = { type: 'miaoda:deck:slide-changed', index: this._index, total: this._slides.length, skipped: this._skippedIndices() };
+        window.parent.postMessage(this._stampMirror(msg, 'deck:slide'), '*');
+      } catch (e) {}
     }
 
     _skippedIndices() {