docs: add Soroban storage strategies guide (#2649)

* add storage strategies guide with animated diagrams

* codex worked oncorrecting Soroban storage strategies guide

* fix storage guide facts, diagram styling and animations

* polish storage guide, add markdown-source plugin

* fix ttl animation, clarify tier and cap wording

* clarify strategies 7-8, fix swap-and-pop diagram

* polish strategy titles, s9 wording and diagrams

* rework strategy 10 and its diagram, note cap-85

* clarify decision path, cheatsheet, s11 diagram

* add checkpoints strategy as s10, renumber s10-11 to s11-12

* make d1/d3/d7 animations finite, show allowance deadline checks

The three looping diagrams auto-started on scroll and never stopped,
breaking the component's plays-once contract (WCAG 2.2.2); capped at
2-3 iterations (~5s) since Replay covers re-watching. The Strategy 4
snippet claimed the deadline was checked but only stored it — now it
shows the write-side validation and read-side expiration guard from
the canonical token example.

* drop the markdown-source dev middleware

Serving raw markdown under docusaurus start meant re-deriving source
paths from URLs, which missed README-backed section pages, /docs.md,
and front-matter slugs, and required a fragile re-install of the eval
source map middleware that silently failed on Docusaurus 3.10. Not
worth the surface: the Open Markdown button works in production and
PR previews, where docusaurus-markdown-source-plugin resolves sources
from route metadata.

* apply review wording and formatting feedback

* correct snippet semantics and cost accounting

* relabel d5 ttl diagram as not to scale

* show bump-on-read via a balance getter

also polish comment

* show diagram final frames when javascript is off

* cite oz smart account instead of passkey-kit

Author: marcelosalloum

docs/build/guides/storage/storage-strategies.mdx

@@ -111,6 +111,7 @@
 /docs/build/guides/storage
 /docs/build/guides/storage/choosing-the-right-storage
 /docs/build/guides/storage/migrate-contract-storage
+/docs/build/guides/storage/storage-strategies
 /docs/build/guides/storage/use-instance
 /docs/build/guides/storage/use-persistent
 /docs/build/guides/storage/use-temporary

routes.txt

@@ -0,0 +1,109 @@
+import React, { useEffect, useRef, useState } from "react";
+import "./diagrams.css";
+
+interface AnimatedDiagramProps {
+  id: string;
+  caption?: string;
+  children: React.ReactNode;
+}
+
+// Card that plays its CSS/SVG animations once it scrolls into view, with a
+// replay button. Animations are gated behind the .play class (see diagrams.css).
+export default function AnimatedDiagram({
+  id,
+  caption,
+  children,
+}: AnimatedDiagramProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  // .play must live in React state: it gates animation-play-state in CSS, and
+  // an imperatively added class would be dropped on the next re-render.
+  const [playing, setPlaying] = useState(false);
+  const [restored, setRestored] = useState({
+    instance: false,
+    persistent: false,
+  });
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) {
+      return undefined;
+    }
+    const io = new IntersectionObserver(
+      (entries) => {
+        entries.forEach((entry) => {
+          if (entry.isIntersecting) {
+            setPlaying(true);
+            io.unobserve(el);
+          }
+        });
+      },
+      { threshold: 0.45 },
+    );
+    io.observe(el);
+    return () => io.disconnect();
+  }, []);
+
+  const replay = () => {
+    const el = ref.current;
+    if (!el) {
+      return;
+    }
+    setRestored({ instance: false, persistent: false });
+    setPlaying(true);
+    // Toggling .play only pauses/resumes; to restart from frame 0 the
+    // animations themselves must be torn down and recreated.
+    const anims = el.querySelectorAll<HTMLElement | SVGElement>(".anim");
+    anims.forEach((a) => {
+      a.style.animation = "none";
+    });
+    void (el as HTMLElement).offsetWidth;
+    anims.forEach((a) => {
+      a.style.animation = "";
+    });
+  };
+
+  const className = [
+    "ssd",
+    playing ? "play" : "",
+    restored.instance ? "restored-instance" : "",
+    restored.persistent ? "restored-persistent" : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <div className={className} id={id} ref={ref}>
+      <div className="diagram-controls">
+        {id === "d0" ? (
+          <>
+            <button
+              className="restore"
+              type="button"
+              aria-pressed={restored.instance}
+              onClick={() =>
+                setRestored((current) => ({ ...current, instance: true }))
+              }
+            >
+              Restore instance
+            </button>
+            <button
+              className="restore"
+              type="button"
+              aria-pressed={restored.persistent}
+              onClick={() =>
+                setRestored((current) => ({ ...current, persistent: true }))
+              }
+            >
+              Restore persistent entry
+            </button>
+          </>
+        ) : null}
+        <button className="replay" type="button" onClick={replay}>
+          {id === "d0" ? "↻ Replay expiry" : "↻ Replay"}
+        </button>
+      </div>
+      {children}
+      {caption ? <p className="caption">{caption}</p> : null}
+    </div>
+  );
+}