release v0.3.9

Author: rawBit-io

CHANGELOG.md

@@ -112,3 +112,19 @@ and the project aims to adhere to [Semantic Versioning](https://semver.org/spec/
 - Loading example flows on mobile no longer risks a blank canvas due to mount/fit timing races.
 - Lesson content polish in L1/L3, including corrected locktime/CLTV wording and removal of stale “ready to broadcast” text in flows 1-3.
 - Improved Safari drag responsiveness in the paper skin by removing dashed-edge styling.
+
+## [0.3.9] - 2026-03-20
+
+### Added
+
+- Exports (`full`, `simplified`, `LLM`) now include `runtimeSemantics` metadata describing sentinel precedence (`__FORCE00__`, `__EMPTY__`, `__NULL__`) and numeric type coercion rules.
+
+### Changed
+
+- Lesson 2 flow renamed to **Multisig: Bare P2MS and P2SH Multisig** (`p2_Bare_P2MS_and_P2SH_MultiSig.json`), with refreshed in-flow wording.
+
+### Fixed
+
+- Shared-flow imports now use more resilient fit-view timing to avoid occasional blank/offscreen canvas states.
+- Redo no longer causes a visible canvas blink during history restore.
+- Lesson 3 cleanup: removed redundant “Resulting TXID” helper comments.

backend/tests/test_flow_roundtrip.py

@@ -51,8 +51,8 @@
         },
     },
     {
-        "name": "p2_P2PK_and_P2SH_MultiSig.json",
-        "path": ROOT / "src" / "my_tx_flows" / "p2_P2PK_and_P2SH_MultiSig.json",
+        "name": "p2_Bare_P2MS_and_P2SH_MultiSig.json",
+        "path": ROOT / "src" / "my_tx_flows" / "p2_Bare_P2MS_and_P2SH_MultiSig.json",
         "node_changes": {
             "node_DyhEXHsp": "1",
         },

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "rawbit",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "license": "MIT",
   "type": "module",
   "scripts": {

package.json

@@ -10,7 +10,7 @@
     <loc>https://rawbit.io/flows/p1_Intro_P2PKH_and_P2PK</loc>
   </url>
   <url>
-    <loc>https://rawbit.io/flows/p2_P2PK_and_P2SH_MultiSig</loc>
+    <loc>https://rawbit.io/flows/p2_Bare_P2MS_and_P2SH_MultiSig</loc>
   </url>
   <url>
     <loc>https://rawbit.io/flows/p3_Locktime_Intro</loc>

public/sitemap.xml

@@ -1001,11 +1001,18 @@ function FlowContent() {
     const instance = flowInstanceRef.current;
     if (!instance) return;
 
-    const runFit = () => instance.fitView({ padding: 0.2, maxZoom: 2, duration: 350 });
+    const runFit = () =>
+      instance.fitView({ padding: 0.2, maxZoom: 2, duration: 350 });
     // Use a double rAF so the React Flow store has applied imported nodes/edges
     requestAnimationFrame(() => requestAnimationFrame(runFit));
   }, []);
 
+  const fitSharedImportedFlow = useCallback(() => {
+    // Shared-flow loading can race WebKit layout readiness; use the resilient
+    // retry scheduler for this path only.
+    scheduleExampleFlowFit();
+  }, [scheduleExampleFlowFit]);
+
   const handleImportTooltip = useCallback(
     (filename?: string) => {
       if (!filename) return;
@@ -1540,6 +1547,7 @@ function FlowContent() {
   useSharedFlowLoader({
     getNodes,
     getEdges,
+    fitView: fitSharedImportedFlow,
     getProtocolDiagramLayout: () => protocolDiagramLayout,
     setProtocolDiagramLayout,
     onNodesChange: rawOnNodesChange,
@@ -1639,8 +1647,7 @@ function FlowContent() {
       });
 
       if (hasMissingHandle) {
-        clearHighlights();
-        setEdges([]);
+        // Keep the current edges visible while handles remount to avoid a flash.
         requestAnimationFrame(() => {
           setTimeout(() => setEdges(restoredEdges), 0);
         });

src/components/Flow.tsx

@@ -110,6 +110,106 @@ describe("useFileOperations", () => {
     };
   };
 
+  const setupDownloadCapture = () => {
+    const anchors: Array<HTMLAnchorElement> = [];
+    const blobs: Blob[] = [];
+    const originalBlob = globalThis.Blob;
+
+    class MockBlob {
+      readonly size: number;
+      readonly type: string;
+      private readonly rawText: string;
+
+      constructor(parts: BlobPart[] = [], options?: BlobPropertyBag) {
+        this.rawText = parts
+          .map((part) => {
+            if (typeof part === "string") return part;
+            if (part instanceof ArrayBuffer) {
+              return new TextDecoder().decode(part);
+            }
+            if (ArrayBuffer.isView(part)) {
+              return new TextDecoder().decode(part);
+            }
+            return String(part);
+          })
+          .join("");
+        this.size = this.rawText.length;
+        this.type = options?.type ?? "";
+      }
+
+      async text(): Promise<string> {
+        return this.rawText;
+      }
+    }
+
+    vi.stubGlobal("Blob", MockBlob as unknown as typeof Blob);
+
+    const originalCreateElement = document.createElement.bind(document);
+    const createElementSpy = vi
+      .spyOn(document, "createElement")
+      .mockImplementation((tagName: string) => {
+        if (tagName.toLowerCase() === "a") {
+          const anchor = {
+            href: "",
+            download: "",
+            click: vi.fn(),
+          } as unknown as HTMLAnchorElement;
+          anchors.push(anchor);
+          return anchor;
+        }
+        return originalCreateElement(tagName);
+      });
+
+    const mutableURL = URL as typeof URL & {
+      createObjectURL?: (blob: Blob) => string;
+      revokeObjectURL?: (url: string) => void;
+    };
+    const originalCreateObjectURL = mutableURL.createObjectURL;
+    const originalRevokeObjectURL = mutableURL.revokeObjectURL;
+    Object.defineProperty(mutableURL, "createObjectURL", {
+      configurable: true,
+      writable: true,
+      value: vi.fn((blob: Blob) => {
+        blobs.push(blob);
+        return `blob:mock-${blobs.length}`;
+      }) as typeof mutableURL.createObjectURL,
+    });
+    Object.defineProperty(mutableURL, "revokeObjectURL", {
+      configurable: true,
+      writable: true,
+      value: vi.fn() as typeof mutableURL.revokeObjectURL,
+    });
+
+    const restore = () => {
+      createElementSpy.mockRestore();
+      if (originalCreateObjectURL) {
+        Object.defineProperty(mutableURL, "createObjectURL", {
+          configurable: true,
+          writable: true,
+          value: originalCreateObjectURL,
+        });
+      } else {
+        Reflect.deleteProperty(mutableURL, "createObjectURL");
+      }
+      if (originalRevokeObjectURL) {
+        Object.defineProperty(mutableURL, "revokeObjectURL", {
+          configurable: true,
+          writable: true,
+          value: originalRevokeObjectURL,
+        });
+      } else {
+        Reflect.deleteProperty(mutableURL, "revokeObjectURL");
+      }
+      if (originalBlob) {
+        vi.stubGlobal("Blob", originalBlob);
+      } else {
+        Reflect.deleteProperty(globalThis, "Blob");
+      }
+    };
+
+    return { anchors, blobs, restore };
+  };
+
   it("notifies error when file exceeds byte limit", async () => {
     const { result, onError } = renderUseFileOperations();
     const bigContent = "x".repeat(MAX_FLOW_BYTES + 1);
@@ -456,6 +556,81 @@ describe("useFileOperations", () => {
     }
   });
 
+  it("adds runtime semantics metadata to full, simplified, and LLM exports", async () => {
+    const { blobs, restore } = setupDownloadCapture();
+
+    try {
+      const { result, nodes } = renderUseFileOperations({
+        tabTitle: "Runtime Semantics",
+      });
+      nodes[0].selected = true;
+
+      act(() => {
+        result.current.saveFlow();
+      });
+      act(() => {
+        result.current.saveSimplifiedFlow();
+      });
+      await act(async () => {
+        await result.current.saveLlmExport();
+      });
+
+      expect(blobs).toHaveLength(3);
+
+      const readBlobText = async (blob: Blob): Promise<string> => {
+        if (typeof blob.text === "function") {
+          return blob.text();
+        }
+        if (typeof blob.arrayBuffer === "function") {
+          const bytes = await blob.arrayBuffer();
+          return new TextDecoder().decode(bytes);
+        }
+        try {
+          return await new Response(blob as unknown as BodyInit).text();
+        } catch {
+          // fall through to explicit error
+        }
+        throw new Error("Unable to read downloaded blob content");
+      };
+
+      const [full, simplified, llm] = await Promise.all(
+        blobs.map(async (blob) => JSON.parse(await readBlobText(blob)) as Record<string, unknown>)
+      );
+
+      const semanticsMatcher = expect.objectContaining({
+        version: 1,
+        inputResolution: expect.objectContaining({
+          precedence: expect.arrayContaining([
+            "__FORCE00__",
+            "__EMPTY__",
+            "__NULL__",
+            "edge value",
+            "manual text",
+          ]),
+          sentinels: expect.objectContaining({
+            __FORCE00__: expect.any(String),
+            __EMPTY__: expect.any(String),
+            __NULL__: expect.any(String),
+          }),
+        }),
+        typeCoercion: expect.objectContaining({
+          integerParams: expect.any(String),
+          numberParams: expect.any(String),
+        }),
+      });
+
+      expect(full.runtimeSemantics).toEqual(semanticsMatcher);
+      expect(simplified.runtimeSemantics).toEqual(semanticsMatcher);
+      expect(llm.runtimeSemantics).toEqual(semanticsMatcher);
+      const llmContext = llm.llmContext as { whatIsExported?: string[] } | undefined;
+      expect(llmContext?.whatIsExported).toEqual(
+        expect.arrayContaining([expect.stringContaining("Runtime semantics:")])
+      );
+    } finally {
+      restore();
+    }
+  });
+
   describe("export filenames", () => {
     const setupDownloadSpies = () => {
       const anchors: Array<HTMLAnchorElement> = [];