@drawmotive/textgraph 0.2.2-alpha.4 → 0.2.2-alpha.5

package/docs/api-v1.md

@@ -75,11 +75,23 @@ Use `languagePacks: []` with `fallback: false` to explicitly disable automatic f
 
 Catalog fonts carry actual Unicode coverage, language hints, byte sizes and SHA-256.
 They are verified before native installation. Catalog URLs are cached per instance;
-HTTP font URLs include the content hash as a stable `v` parameter. HTTP caching remains
-browser/server-owned; there is no new IndexedDB or Service Worker. Offline operation
+HTTP font URLs include the content hash as a stable `v` parameter. The SDK automatically
+stores verified bundled and optional font bytes in browser/Worker Cache Storage
+(`textgraph-fonts-v1`) and reuses them across instances and page reloads, independent
+of server cache headers. Cached bytes are verified again before use; damaged entries
+are replaced from the configured source. Storage denial or quota errors fall back
+to normal loading. Local files and descriptors without hashes are not persisted. Offline operation
 requires the complete runtime and font package on a local filesystem or local server;
 an online page cannot fetch an uncached font after losing network access.
 
+For interactive previews, pass `onPreview` to `renderPng` or `renderSvg`. When visible
+labels need optional fonts, the callback receives a provisional successful image
+using installed fonts before catalog/font downloads. Display it with a font-loading
+notice; missing glyphs or different text geometry can appear temporarily. The returned
+promise still resolves to the final output after fonts are installed and layout is
+recomputed. Calls without the callback retain final-output semantics. Font-loading
+failures reject so the host can keep the provisional image and offer a retry.
+
 `renderPng(source, { language: "ja" })` and `renderSvg(source, { language: "ja" })` can disambiguate Han-only labels. Without a hint,
 kana selects Japanese for that label and Han-only labels use Chinese. Grapheme-aware
 emoji selection includes flags, ZWJ sequences, modifiers and keycaps. Font selection

package/docs/react.md

@@ -38,10 +38,17 @@ Use your deployed base path instead of `/` for subdirectory hosting. The [React/
 | `alt` | Image description; defaults to `TextGraph diagram`. |
 | `renderOptions` | Defaults to `scale: 1`; `padding` and `maxWidth` use SDK defaults. Set `scale: 2` explicitly for higher raster density. |
 | `loading` | React content shown with `role="status"`; defaults to `Rendering diagram…`. |
+| `fontsLoading` | Content shown beside the provisional image while optional fonts load; defaults to `Fonts are still loading…`. |
 | Other image attributes | Passed to the successful `<img>`, including `className`, `style`, `width`, and `height`. |
 
 The component owns `src`, encoding, and cancellation. While new input renders, old images are replaced by loading content. A stale result cannot replace newer input. DSL diagnostics and operational failures appear as escaped text with `role="alert"`; corrected input renders again. Changing only `alt` or image styles does not rerun layout.
 
+When optional fonts are needed, the component displays a provisional image first,
+shows `fontsLoading`, and replaces the image after loading and measuring the fonts.
+If loading fails, the preview remains beside the error. The SDK automatically caches
+verified font bytes across instances and reloads in browser Cache Storage; no host
+cache setup is required.
+
 Images use the render result's logical `displayWidth` and `displayHeight`, so increasing `scale` adds pixels without enlarging the diagram. `maxWidth` limits raster pixels rather than CSS width. Styles default to `maxWidth: '100%'` and `height: 'auto'`; supplied styles merge over these defaults, and explicit image dimensions override the logical dimensions.
 
 Older runtimes omit display dimensions. The component then divides raster dimensions by the requested scale; this preserves logical size unless `maxWidth` has lowered the effective density. Deploy matching updated runtime assets for accurate sizing in that case. PNG DPI metadata does not control CSS size.

package/generated/wasm/dotnet.boot.js

@@ -1,7 +1,7 @@
 export const config = /*json-start*/{
   "mainAssemblyName": "DrawMotive.TextGraph.Bridge.dll",
   "resources": {
-    "hash": "sha256-9p7nKPZDEyEeO7h5+hbeTVO+aIMmHG1Ag8bTDOrdQuo=",
+    "hash": "sha256-NkSXf6BaW3IAk8E3aIFzyrGG28CgnWT4/WC1onNX/Z0=",
     "jsModuleNative": [
       {
         "name": "dotnet.native.js"
@@ -15,7 +15,7 @@ export const config = /*json-start*/{
     "wasmNative": [
       {
         "name": "dotnet.native.wasm",
-        "hash": "sha256-l+otbw6uFZ21z01W05/xUXFIRDzxg/dMnecyrBCASaM="
+        "hash": "sha256-Tqb9aNQTpsiBcpNevNGjnyxzrpZE0n77Sx4Rcn4UFhc="
       }
     ],
     "coreAssembly": [
@@ -27,7 +27,7 @@ export const config = /*json-start*/{
       {
         "virtualPath": "System.Private.CoreLib.wasm",
         "name": "System.Private.CoreLib.wasm",
-        "hash": "sha256-uYf/GlG3fALkgSWaDt9Vqn6mq0tqM/xncMHkkH2mnjk="
+        "hash": "sha256-Iaa0Sf9pQ/5qOAIAghx8wjz/9jodVQVYvksdfYoyQo8="
       }
     ],
     "assembly": [
@@ -39,12 +39,12 @@ export const config = /*json-start*/{
       {
         "virtualPath": "Grpc.Core.Api.wasm",
         "name": "Grpc.Core.Api.wasm",
-        "hash": "sha256-gg8LFP6oezgeQTFssVaMra0ks5hWP86J9NmzfhC4rYs="
+        "hash": "sha256-X6Xe6EsTbgz2wWCfm/jWGDbHliLWTyZ4/q8tq0mEXuA="
       },
       {
         "virtualPath": "HarfBuzzSharp.wasm",
         "name": "HarfBuzzSharp.wasm",
-        "hash": "sha256-IdHAAVCqzCO9wrijQNqEG5BxcqxWCpSP0VZBaC7qTjE="
+        "hash": "sha256-ANRkrpepe+vbsz6PkjgjWbgkW2W68G7iYG9gU7qx+zs="
       },
       {
         "virtualPath": "MagicOnion.Abstractions.wasm",
@@ -139,7 +139,7 @@ export const config = /*json-start*/{
       {
         "virtualPath": "Polly.Core.wasm",
         "name": "Polly.Core.wasm",
-        "hash": "sha256-+O4E8HgPEQfCXVrc5qGIOHIIudYsesBVBsOfDMO1jxA="
+        "hash": "sha256-dXCCNoxEuqdFCoVDH1ZfKecXtEldfinkUKjwj18RqKE="
       },
       {
         "virtualPath": "R3.wasm",
@@ -154,7 +154,7 @@ export const config = /*json-start*/{
       {
         "virtualPath": "SkiaSharp.wasm",
         "name": "SkiaSharp.wasm",
-        "hash": "sha256-ZwutJ8qzOxKdchnZ7LCPhOrIAwq+ZDU4Eao2EUPOySE="
+        "hash": "sha256-bRa2qn2QJTeC0dSx2LmKFUS1lm/ZeqoaJ31c24l8NtI="
       },
       {
         "virtualPath": "SkiaSharp.HarfBuzz.wasm",
@@ -166,15 +166,10 @@ export const config = /*json-start*/{
         "name": "Stateless.wasm",
         "hash": "sha256-EWplLf93o2pQw4CGMvCTYO234EMwTX1tSqc2xJ8JbCw="
       },
-      {
-        "virtualPath": "ZstdSharp.wasm",
-        "name": "ZstdSharp.wasm",
-        "hash": "sha256-KR3cAHwB6xsvw0WXeCcP8OnTHPehbTBzJ5VbX5vlOVU="
-      },
       {
         "virtualPath": "Graphics.Core.wasm",
         "name": "Graphics.Core.wasm",
-        "hash": "sha256-99LKei+dk+MU19LjgjT0kZfLXokIHFK89MU+hqU8Lqk="
+        "hash": "sha256-RkBXYEmkqaTS5u4oaD9LgCGW9BeM6Yx6y7Faf0anA0A="
       },
       {
         "virtualPath": "Math.Core.wasm",
@@ -184,17 +179,17 @@ export const config = /*json-start*/{
       {
         "virtualPath": "RBush.wasm",
         "name": "RBush.wasm",
-        "hash": "sha256-c8CJit4SZtGzETyarNEiwYWc/dzfWi5uwCy4m9CwQ98="
+        "hash": "sha256-hB+961dw2Pyftv3Lyp+nlvtuEj0yUB5d/Fzby23Rq2k="
       },
       {
         "virtualPath": "DrawMotive.TextGraph.Bridge.wasm",
         "name": "DrawMotive.TextGraph.Bridge.wasm",
-        "hash": "sha256-B7fOl72lT908oLFjkodTlVEx8+zoqxElSL6Enzk7NQw="
+        "hash": "sha256-FPqTWFElDDiTkAPoR5NrVyDpUDK4hTEj5naELw5Y21c="
       },
       {
         "virtualPath": "System.Collections.Concurrent.wasm",
         "name": "System.Collections.Concurrent.wasm",
-        "hash": "sha256-BXUr4+prcuxklm+r7szsDktFIfPfcb8/02SPaRyz960="
+        "hash": "sha256-Jeoyh28M8wBA9+BQ0e4ANv2Jq6ITNW88s/DsalFTOII="
       },
       {
         "virtualPath": "System.Collections.Immutable.wasm",
@@ -239,7 +234,7 @@ export const config = /*json-start*/{
       {
         "virtualPath": "System.Console.wasm",
         "name": "System.Console.wasm",
-        "hash": "sha256-BAKmU+lUWgxhtkmZ8jieCZeWo80RWxGZs2ooZ6iqZ/o="
+        "hash": "sha256-wWvOkB7Asdsz3ljcee0YzCbdSqWCXg1y/VElLjmc4IA="
       },
       {
         "virtualPath": "System.Diagnostics.StackTrace.wasm",
@@ -254,12 +249,12 @@ export const config = /*json-start*/{
       {
         "virtualPath": "System.IO.Compression.Brotli.wasm",
         "name": "System.IO.Compression.Brotli.wasm",
-        "hash": "sha256-F4xiJc7ffAvcTm67k1NojAE82TOqJutN2GLp8nguyLY="
+        "hash": "sha256-DcPCQCYlBqXrd+tiArKhLDeuqXNSS6lnKVwPOoQ9NZg="
       },
       {
         "virtualPath": "System.IO.Compression.wasm",
         "name": "System.IO.Compression.wasm",
-        "hash": "sha256-LEpM7vWA7l1pAc9qqrubbXdboEwopOLFK3a7VMdGJLg="
+        "hash": "sha256-smvpD00XQvKdSiwuc7hnhCoRz2Nk9VsSTg7MQ9QDipY="
       },
       {
         "virtualPath": "System.IO.Pipelines.wasm",
@@ -284,7 +279,7 @@ export const config = /*json-start*/{
       {
         "virtualPath": "System.Net.Http.wasm",
         "name": "System.Net.Http.wasm",
-        "hash": "sha256-VTLLDv0CufL90HZn7zDPWv02ruTg8G9m+SwcJyD1i3Q="
+        "hash": "sha256-ARrgegBDSux9EF+zqRrsot7EbG1Q9fVGFdJPdHm/r54="
       },
       {
         "virtualPath": "System.Net.Primitives.wasm",
@@ -334,12 +329,12 @@ export const config = /*json-start*/{
       {
         "virtualPath": "System.Runtime.InteropServices.wasm",
         "name": "System.Runtime.InteropServices.wasm",
-        "hash": "sha256-JOphI8UBDfRYPMoPVWX6vtbIvIl2X5JrfC/mHtvh7ks="
+        "hash": "sha256-Q+92Kf8z4HWVuCYT5hM1wtDe4wQSltcDE8cvVbCH8fU="
       },
       {
         "virtualPath": "System.Runtime.Intrinsics.wasm",
         "name": "System.Runtime.Intrinsics.wasm",
-        "hash": "sha256-eakqOzOkp0Mj/WG0i0fuK0e4F/dENzwC+AF5SXmatt0="
+        "hash": "sha256-Amor9SnGJljEQGEHCbNnu8SJdtb2TN+4vW5fSBgwcMc="
       },
       {
         "virtualPath": "System.Runtime.Loader.wasm",
@@ -359,7 +354,7 @@ export const config = /*json-start*/{
       {
         "virtualPath": "System.Runtime.wasm",
         "name": "System.Runtime.wasm",
-        "hash": "sha256-k2UA6JqOpAVySatRrwRGNVQnnfCX79dzJL1D9a7vC2M="
+        "hash": "sha256-f0aumL0L3t2Dj97l3TzNxbOS4K9q93bDGqeAdICfb/A="
       },
       {
         "virtualPath": "System.Security.Cryptography.wasm",
@@ -394,7 +389,7 @@ export const config = /*json-start*/{
       {
         "virtualPath": "System.Threading.Thread.wasm",
         "name": "System.Threading.Thread.wasm",
-        "hash": "sha256-z/9sp9813ITXlJUi0QmOUPMRNX77BVzO6yU0bIKss/w="
+        "hash": "sha256-xmNkGMgtSroWqZ6CxqqzoILHxIWocNCS8InItRUqIUE="
       },
       {
         "virtualPath": "System.Threading.ThreadPool.wasm",

package/generated/wasm-manifest.js

@@ -1,7 +1,7 @@
 export default {
   "schemaVersion": 1,
   "packageName": "@drawmotive/textgraph",
-  "packageVersion": "0.2.2-alpha.4",
+  "packageVersion": "0.2.2-alpha.5",
   "abiVersion": "1.0.0",
   "protocolVersion": 1,
   "runtimeModule": "wasm/dotnet.js",
@@ -27,7 +27,7 @@ export default {
   },
   "targetFramework": "net10.0",
   "privateSource": {
-    "commit": "be84f251d1a3c5154879ffb1706f550cf2e27b7a",
+    "commit": "f7627ef2646772503fb3d8165ee312d4f411566c",
     "project": "DrawMotive.TextGraph.Bridge"
   },
   "entryAssembly": "wasm/DrawMotive.TextGraph.Bridge.wasm",
@@ -52,7 +52,7 @@ export default {
       "path": "wasm/DrawMotive.TextGraph.Bridge.wasm",
       "mediaType": "application/wasm",
       "bytes": 87317,
-      "sha256": "07b7ce97bda54fdd3ca0b163928753955131f3ece8ab112548be849f393b350c"
+      "sha256": "14fa935851250c38939003e847936b5720e95032b8853123e676842f0e58db57"
     },
     {
       "path": "wasm/ExCSS.wasm",
@@ -75,20 +75,20 @@ export default {
     {
       "path": "wasm/Graphics.Core.wasm",
       "mediaType": "application/wasm",
-      "bytes": 3978521,
-      "sha256": "f7d2ca7a2f9d93e314d7d2e38234f49197cb5e89081c52bcf4c53e86a53c2ea9"
+      "bytes": 4040985,
+      "sha256": "4640576049a4a9a4d2e6ee28683f4b802196f4178ce98c7acbb15a7f46a70340"
     },
     {
       "path": "wasm/Grpc.Core.Api.wasm",
       "mediaType": "application/wasm",
       "bytes": 7957,
-      "sha256": "820f0b14fea87b381e41316cb1568cadad24b398563fce89f4d9b37e10b8ad8b"
+      "sha256": "5fa5dee84b136e0cf6c1609f9bf8d61836c79622d64f2678feaf2dab49845ee0"
     },
     {
       "path": "wasm/HarfBuzzSharp.wasm",
       "mediaType": "application/wasm",
       "bytes": 30485,
-      "sha256": "21d1c00150aacc23bdc2b8a340da841b907172ac560a948fd15641682eea4e31"
+      "sha256": "00d464ae97a97bebdbb33e8f92382359b8245b65baf06ee2606f6053bab1fb3b"
     },
     {
       "path": "wasm/MagicOnion.Abstractions.wasm",
@@ -214,7 +214,7 @@ export default {
       "path": "wasm/Polly.Core.wasm",
       "mediaType": "application/wasm",
       "bytes": 62741,
-      "sha256": "f8ee04f0780f1107c25d5adce6a188387208b9d62c7ac05506c39f0cc3b58f10"
+      "sha256": "757082368c44baa7450a85431f565f29e717b4495d7e29e450a8f08f5f11a8a1"
     },
     {
       "path": "wasm/Polly.wasm",
@@ -238,7 +238,7 @@ export default {
       "path": "wasm/RBush.wasm",
       "mediaType": "application/wasm",
       "bytes": 24341,
-      "sha256": "73c0898ade1266d1b3113c9aacd122c1859cfddcdf5a2e6ec02cb89bd0b043df"
+      "sha256": "841fbdeb5770d8fc9fb6fdcbca9fa796fb6e123d32501e5dfc5cdbcb6dd1ab69"
     },
     {
       "path": "wasm/SkiaSharp.HarfBuzz.wasm",
@@ -250,7 +250,7 @@ export default {
       "path": "wasm/SkiaSharp.wasm",
       "mediaType": "application/wasm",
       "bytes": 102677,
-      "sha256": "670bad27cab33b129d7219d9ecb08f84eac8030abe64353811aa361143cec921"
+      "sha256": "6d16b6aa7d90253782d1d4b1d8b98a1544b5966fd97aaa1a277d5cdb897c36d2"
     },
     {
       "path": "wasm/Stateless.wasm",
@@ -261,8 +261,8 @@ export default {
     {
       "path": "wasm/System.Collections.Concurrent.wasm",
       "mediaType": "application/wasm",
-      "bytes": 39189,
-      "sha256": "05752be3ea6b72ec64966fabeeccec0e4b4521f3df71bf3fd3648f691cb3f7ad"
+      "bytes": 36117,
+      "sha256": "25ea32876f0cf30040f7e050d1ee0036fd89aba213356f3cb3f0ec6a51533882"
     },
     {
       "path": "wasm/System.Collections.Immutable.wasm",
@@ -316,7 +316,7 @@ export default {
       "path": "wasm/System.Console.wasm",
       "mediaType": "application/wasm",
       "bytes": 15125,
-      "sha256": "0402a653e9545a0c61b64999f2389e099796a3cd115b1199b36a2867a8aa67fa"
+      "sha256": "c16bce901ec0b1db33de58dc79ed18cc26dd4aa5825e0d72fd51252e399ce080"
     },
     {
       "path": "wasm/System.Diagnostics.StackTrace.wasm",
@@ -333,14 +333,14 @@ export default {
     {
       "path": "wasm/System.IO.Compression.Brotli.wasm",
       "mediaType": "application/wasm",
-      "bytes": 5397,
-      "sha256": "178c6225cedf7c0bdc4e6ebb9353688c013cd933aa26eb4dd862e9f2782ec8b6"
+      "bytes": 6933,
+      "sha256": "0dc3c240262506a5eb77eb6202b2a12c37aea973524ba967295c0f3a843d3598"
     },
     {
       "path": "wasm/System.IO.Compression.wasm",
       "mediaType": "application/wasm",
       "bytes": 13077,
-      "sha256": "2c4a4ceef580ee5d6901cf6aaabb9b6d775ba04c28a4e2c52b76bb54c74624b8"
+      "sha256": "b26be90f4d1742f29d4a2c2e73b867842a11cf6364f55b124e0ecc43d4038a96"
     },
     {
       "path": "wasm/System.IO.Pipelines.wasm",
@@ -370,7 +370,7 @@ export default {
       "path": "wasm/System.Net.Http.wasm",
       "mediaType": "application/wasm",
       "bytes": 142101,
-      "sha256": "5532cb0efd02b9f2fdd07667ef30cf5afd36aee4e0f06f66f92c1c2720f58b74"
+      "sha256": "011ae07a00434aec7d105fb3a91aeca2dec46c6d50f5f54615d24f7479bfaf9e"
     },
     {
       "path": "wasm/System.Net.Primitives.wasm",
@@ -393,8 +393,8 @@ export default {
     {
       "path": "wasm/System.Private.CoreLib.wasm",
       "mediaType": "application/wasm",
-      "bytes": 2177817,
-      "sha256": "b987ff1a51b77c02e481259a0edf55aa7ea6ab4b6a33fc6770c1e4907da69e39"
+      "bytes": 2173721,
+      "sha256": "21a6b449ff6943fe6a380200821c7cc23cfff63a1d550558be4b1d7d8a32428f"
     },
     {
       "path": "wasm/System.Private.Uri.wasm",
@@ -442,13 +442,13 @@ export default {
       "path": "wasm/System.Runtime.InteropServices.wasm",
       "mediaType": "application/wasm",
       "bytes": 8981,
-      "sha256": "24ea6123c5010df4583cca0f5565fabed6c8bc89765f926b7c2fe61edbe1ee4b"
+      "sha256": "43ef7629ff33e07595b82613e61335c2d0dee3041296d70313c72f55b087f1f5"
     },
     {
       "path": "wasm/System.Runtime.Intrinsics.wasm",
       "mediaType": "application/wasm",
-      "bytes": 5397,
-      "sha256": "79a92a3b33a4a74323fd61b48b47ee2b47b817f744373c02f8017949799ab6dd"
+      "bytes": 4885,
+      "sha256": "026a2bf529c62658c440610709b367bbc48976d6f64cdfb8bd6e5f48183070c7"
     },
     {
       "path": "wasm/System.Runtime.Loader.wasm",
@@ -472,7 +472,7 @@ export default {
       "path": "wasm/System.Runtime.wasm",
       "mediaType": "application/wasm",
       "bytes": 16661,
-      "sha256": "936500e89a8ea4057249ab51af04463554279df097efd77324bd43f5aeef0b63"
+      "sha256": "7f46ae98bd0bdedd838fdee5dd3ccdc5b392e0af6af776c31aa78074809f6ff0"
     },
     {
       "path": "wasm/System.Security.Cryptography.wasm",
@@ -514,7 +514,7 @@ export default {
       "path": "wasm/System.Threading.Thread.wasm",
       "mediaType": "application/wasm",
       "bytes": 4885,
-      "sha256": "cfff6ca7df35dc84d7949522d1098e50f311357efb055cceeb25346c82acb3fc"
+      "sha256": "c6636418c82d4aba16a99e82c6aab3a082c7c485a870d092f089c8b5152a2141"
     },
     {
       "path": "wasm/System.Threading.ThreadPool.wasm",
@@ -546,17 +546,11 @@ export default {
       "bytes": 4885,
       "sha256": "bcf126d8aaa05eaaee1b09f3ef5f224a0983a01f089a0ee21f71733b9edbd118"
     },
-    {
-      "path": "wasm/ZstdSharp.wasm",
-      "mediaType": "application/wasm",
-      "bytes": 396565,
-      "sha256": "291ddc007c01eb1b2fc3459778270ff0e9d31cf7a16d307327955b5f9be53955"
-    },
     {
       "path": "wasm/dotnet.boot.js",
       "mediaType": "text/javascript",
-      "bytes": 18023,
-      "sha256": "70860e48b60926393c97b33b3c5b5e921c07993c861ad5273e5317005274ccfd"
+      "bytes": 17861,
+      "sha256": "693025847f303f2ec3bf731150746f4a6e9c28a53418d8b5ee4100beb55ece60"
     },
     {
       "path": "wasm/dotnet.js",
@@ -573,8 +567,8 @@ export default {
     {
       "path": "wasm/dotnet.native.wasm",
       "mediaType": "application/wasm",
-      "bytes": 6307594,
-      "sha256": "97ea2d6f0eae159db5cf4d56d39ff1517148443cf183f74c9de732ac108049a3"
+      "bytes": 6306756,
+      "sha256": "4ea6fd68d413a6c88172935ebcd1a39f2c73ae9644d27efb4b1e11727e141617"
     },
     {
       "path": "wasm/dotnet.runtime.js",

package/generated/wasm-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "packageName": "@drawmotive/textgraph",
-  "packageVersion": "0.2.2-alpha.4",
+  "packageVersion": "0.2.2-alpha.5",
   "abiVersion": "1.0.0",
   "protocolVersion": 1,
   "runtimeModule": "wasm/dotnet.js",
@@ -27,7 +27,7 @@
   },
   "targetFramework": "net10.0",
   "privateSource": {
-    "commit": "be84f251d1a3c5154879ffb1706f550cf2e27b7a",
+    "commit": "f7627ef2646772503fb3d8165ee312d4f411566c",
     "project": "DrawMotive.TextGraph.Bridge"
   },
   "entryAssembly": "wasm/DrawMotive.TextGraph.Bridge.wasm",
@@ -52,7 +52,7 @@
       "path": "wasm/DrawMotive.TextGraph.Bridge.wasm",
       "mediaType": "application/wasm",
       "bytes": 87317,
-      "sha256": "07b7ce97bda54fdd3ca0b163928753955131f3ece8ab112548be849f393b350c"
+      "sha256": "14fa935851250c38939003e847936b5720e95032b8853123e676842f0e58db57"
     },
     {
       "path": "wasm/ExCSS.wasm",
@@ -75,20 +75,20 @@
     {
       "path": "wasm/Graphics.Core.wasm",
       "mediaType": "application/wasm",
-      "bytes": 3978521,
-      "sha256": "f7d2ca7a2f9d93e314d7d2e38234f49197cb5e89081c52bcf4c53e86a53c2ea9"
+      "bytes": 4040985,
+      "sha256": "4640576049a4a9a4d2e6ee28683f4b802196f4178ce98c7acbb15a7f46a70340"
     },
     {
       "path": "wasm/Grpc.Core.Api.wasm",
       "mediaType": "application/wasm",
       "bytes": 7957,
-      "sha256": "820f0b14fea87b381e41316cb1568cadad24b398563fce89f4d9b37e10b8ad8b"
+      "sha256": "5fa5dee84b136e0cf6c1609f9bf8d61836c79622d64f2678feaf2dab49845ee0"
     },
     {
       "path": "wasm/HarfBuzzSharp.wasm",
       "mediaType": "application/wasm",
       "bytes": 30485,
-      "sha256": "21d1c00150aacc23bdc2b8a340da841b907172ac560a948fd15641682eea4e31"
+      "sha256": "00d464ae97a97bebdbb33e8f92382359b8245b65baf06ee2606f6053bab1fb3b"
     },
     {
       "path": "wasm/MagicOnion.Abstractions.wasm",
@@ -214,7 +214,7 @@
       "path": "wasm/Polly.Core.wasm",
       "mediaType": "application/wasm",
       "bytes": 62741,
-      "sha256": "f8ee04f0780f1107c25d5adce6a188387208b9d62c7ac05506c39f0cc3b58f10"
+      "sha256": "757082368c44baa7450a85431f565f29e717b4495d7e29e450a8f08f5f11a8a1"
     },
     {
       "path": "wasm/Polly.wasm",
@@ -238,7 +238,7 @@
       "path": "wasm/RBush.wasm",
       "mediaType": "application/wasm",
       "bytes": 24341,
-      "sha256": "73c0898ade1266d1b3113c9aacd122c1859cfddcdf5a2e6ec02cb89bd0b043df"
+      "sha256": "841fbdeb5770d8fc9fb6fdcbca9fa796fb6e123d32501e5dfc5cdbcb6dd1ab69"
     },
     {
       "path": "wasm/SkiaSharp.HarfBuzz.wasm",
@@ -250,7 +250,7 @@
       "path": "wasm/SkiaSharp.wasm",
       "mediaType": "application/wasm",
       "bytes": 102677,
-      "sha256": "670bad27cab33b129d7219d9ecb08f84eac8030abe64353811aa361143cec921"
+      "sha256": "6d16b6aa7d90253782d1d4b1d8b98a1544b5966fd97aaa1a277d5cdb897c36d2"
     },
     {
       "path": "wasm/Stateless.wasm",
@@ -261,8 +261,8 @@
     {
       "path": "wasm/System.Collections.Concurrent.wasm",
       "mediaType": "application/wasm",
-      "bytes": 39189,
-      "sha256": "05752be3ea6b72ec64966fabeeccec0e4b4521f3df71bf3fd3648f691cb3f7ad"
+      "bytes": 36117,
+      "sha256": "25ea32876f0cf30040f7e050d1ee0036fd89aba213356f3cb3f0ec6a51533882"
     },
     {
       "path": "wasm/System.Collections.Immutable.wasm",
@@ -316,7 +316,7 @@
       "path": "wasm/System.Console.wasm",
       "mediaType": "application/wasm",
       "bytes": 15125,
-      "sha256": "0402a653e9545a0c61b64999f2389e099796a3cd115b1199b36a2867a8aa67fa"
+      "sha256": "c16bce901ec0b1db33de58dc79ed18cc26dd4aa5825e0d72fd51252e399ce080"
     },
     {
       "path": "wasm/System.Diagnostics.StackTrace.wasm",
@@ -333,14 +333,14 @@
     {
       "path": "wasm/System.IO.Compression.Brotli.wasm",
       "mediaType": "application/wasm",
-      "bytes": 5397,
-      "sha256": "178c6225cedf7c0bdc4e6ebb9353688c013cd933aa26eb4dd862e9f2782ec8b6"
+      "bytes": 6933,
+      "sha256": "0dc3c240262506a5eb77eb6202b2a12c37aea973524ba967295c0f3a843d3598"
     },
     {
       "path": "wasm/System.IO.Compression.wasm",
       "mediaType": "application/wasm",
       "bytes": 13077,
-      "sha256": "2c4a4ceef580ee5d6901cf6aaabb9b6d775ba04c28a4e2c52b76bb54c74624b8"
+      "sha256": "b26be90f4d1742f29d4a2c2e73b867842a11cf6364f55b124e0ecc43d4038a96"
     },
     {
       "path": "wasm/System.IO.Pipelines.wasm",
@@ -370,7 +370,7 @@
       "path": "wasm/System.Net.Http.wasm",
       "mediaType": "application/wasm",
       "bytes": 142101,
-      "sha256": "5532cb0efd02b9f2fdd07667ef30cf5afd36aee4e0f06f66f92c1c2720f58b74"
+      "sha256": "011ae07a00434aec7d105fb3a91aeca2dec46c6d50f5f54615d24f7479bfaf9e"
     },
     {
       "path": "wasm/System.Net.Primitives.wasm",
@@ -393,8 +393,8 @@
     {
       "path": "wasm/System.Private.CoreLib.wasm",
       "mediaType": "application/wasm",
-      "bytes": 2177817,
-      "sha256": "b987ff1a51b77c02e481259a0edf55aa7ea6ab4b6a33fc6770c1e4907da69e39"
+      "bytes": 2173721,
+      "sha256": "21a6b449ff6943fe6a380200821c7cc23cfff63a1d550558be4b1d7d8a32428f"
     },
     {
       "path": "wasm/System.Private.Uri.wasm",
@@ -442,13 +442,13 @@
       "path": "wasm/System.Runtime.InteropServices.wasm",
       "mediaType": "application/wasm",
       "bytes": 8981,
-      "sha256": "24ea6123c5010df4583cca0f5565fabed6c8bc89765f926b7c2fe61edbe1ee4b"
+      "sha256": "43ef7629ff33e07595b82613e61335c2d0dee3041296d70313c72f55b087f1f5"
     },
     {
       "path": "wasm/System.Runtime.Intrinsics.wasm",
       "mediaType": "application/wasm",
-      "bytes": 5397,
-      "sha256": "79a92a3b33a4a74323fd61b48b47ee2b47b817f744373c02f8017949799ab6dd"
+      "bytes": 4885,
+      "sha256": "026a2bf529c62658c440610709b367bbc48976d6f64cdfb8bd6e5f48183070c7"
     },
     {
       "path": "wasm/System.Runtime.Loader.wasm",
@@ -472,7 +472,7 @@
       "path": "wasm/System.Runtime.wasm",
       "mediaType": "application/wasm",
       "bytes": 16661,
-      "sha256": "936500e89a8ea4057249ab51af04463554279df097efd77324bd43f5aeef0b63"
+      "sha256": "7f46ae98bd0bdedd838fdee5dd3ccdc5b392e0af6af776c31aa78074809f6ff0"
     },
     {
       "path": "wasm/System.Security.Cryptography.wasm",
@@ -514,7 +514,7 @@
       "path": "wasm/System.Threading.Thread.wasm",
       "mediaType": "application/wasm",
       "bytes": 4885,
-      "sha256": "cfff6ca7df35dc84d7949522d1098e50f311357efb055cceeb25346c82acb3fc"
+      "sha256": "c6636418c82d4aba16a99e82c6aab3a082c7c485a870d092f089c8b5152a2141"
     },
     {
       "path": "wasm/System.Threading.ThreadPool.wasm",
@@ -546,17 +546,11 @@
       "bytes": 4885,
       "sha256": "bcf126d8aaa05eaaee1b09f3ef5f224a0983a01f089a0ee21f71733b9edbd118"
     },
-    {
-      "path": "wasm/ZstdSharp.wasm",
-      "mediaType": "application/wasm",
-      "bytes": 396565,
-      "sha256": "291ddc007c01eb1b2fc3459778270ff0e9d31cf7a16d307327955b5f9be53955"
-    },
     {
       "path": "wasm/dotnet.boot.js",
       "mediaType": "text/javascript",
-      "bytes": 18023,
-      "sha256": "70860e48b60926393c97b33b3c5b5e921c07993c861ad5273e5317005274ccfd"
+      "bytes": 17861,
+      "sha256": "693025847f303f2ec3bf731150746f4a6e9c28a53418d8b5ee4100beb55ece60"
     },
     {
       "path": "wasm/dotnet.js",
@@ -573,8 +567,8 @@
     {
       "path": "wasm/dotnet.native.wasm",
       "mediaType": "application/wasm",
-      "bytes": 6307594,
-      "sha256": "97ea2d6f0eae159db5cf4d56d39ff1517148443cf183f74c9de732ac108049a3"
+      "bytes": 6306756,
+      "sha256": "4ea6fd68d413a6c88172935ebcd1a39f2c73ae9644d27efb4b1e11727e141617"
     },
     {
       "path": "wasm/dotnet.runtime.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawmotive/textgraph",
-  "version": "0.2.2-alpha.4",
+  "version": "0.2.2-alpha.5",
   "description": "Render TextGraph flowcharts and directed graphs as PNG images in Node.js, browsers, React, and Web Workers.",
   "keywords": [
     "textgraph",

package/src/index.d.ts

@@ -65,7 +65,7 @@ export interface TextGraphRuntime {
   readonly abiVersion: string;
   readonly capabilities?: readonly string[];
   validate?(source: string): string | Promise<string>;
-  execute?(requestJson: string, context?: { signal?: AbortSignal }): string | Promise<string>;
+  execute?(requestJson: string, context?: { signal?: AbortSignal; onPreview?(responseJson: string): void }): string | Promise<string>;
   dispose?(): void | Promise<void>;
 }
 
@@ -127,6 +127,8 @@ export interface TextGraphLanguagePack {
 export type TextGraphPngEncoding = 'bytes' | 'base64';
 
 export interface TextGraphRenderPngOptions<Encoding extends TextGraphPngEncoding = TextGraphPngEncoding> {
+  /** Receives a provisional image before optional fonts load; the promise returns the final image. */
+  onPreview?(result: Extract<TextGraphRenderPngResult<Encoding extends 'base64' ? string : Uint8Array>, { success: true }>): void;
   /** Optional language hint for ambiguous Han text, e.g. ja or zh-CN. */
   language?: string;
   /** Defaults to bytes. Base64 contains no data-URL prefix. */
@@ -149,6 +151,8 @@ export type TextGraphRenderPngResult<Png extends Uint8Array | string = Uint8Arra
 
 /** Vector export uses logical diagram units and requires textgraph-render-svg-v1. */
 export interface TextGraphRenderSvgOptions {
+  /** Receives a provisional vector before optional fonts load; the promise returns the final vector. */
+  onPreview?(result: Extract<TextGraphRenderSvgResult, { success: true }>): void;
   /** Optional language hint for ambiguous Han text, e.g. ja or zh-CN. */
   language?: string;
   /** Non-negative padding in diagram units. Defaults to 10. */

package/src/index.js

@@ -38,13 +38,19 @@ export async function initializeTextGraph(options = {}) {
   // Every export format uses the same operation queue and resource-preparing executor.
   const render = async (source, callOptions, normalize, decode, capability, format) => {
     if (instance.state !== 'ready') throw new DrawMotiveError('INSTANCE_DISPOSED', 'The runtime instance is disposing or disposed');
-    const { request, encoding, signal } = normalize(source, callOptions);
+    const { request, encoding, signal, onPreview } = normalize(source, callOptions);
     throwIfAborted(signal);
     if (typeof runtime.execute !== 'function' || !capabilities.includes(capability)) throw new DrawMotiveError('UNSUPPORTED_CAPABILITY', `Runtime does not support ${format} rendering`);
     return instance.mutate(async () => {
       throwIfAborted(signal);
       let response;
-      try { response = await runtime.execute(JSON.stringify(request), { signal }); }
+      const context = { signal };
+      if (onPreview) context.onPreview = json => {
+        throwIfAborted(signal);
+        const preview = decode(json, encoding);
+        if (preview.success) onPreview(preview);
+      };
+      try { response = await runtime.execute(JSON.stringify(request), context); }
       catch (cause) {
         throwIfAborted(signal);
         if (cause instanceof DrawMotiveError || cause?.name === 'AbortError') throw cause;

package/src/react/index.d.ts

@@ -12,8 +12,10 @@ export interface TextGraphProps extends Omit<ImgHTMLAttributes<HTMLImageElement>
   source: string;
   alt?: string;
   /** Defaults to scale 1; the image displays at logical size. */
-  renderOptions?: Omit<TextGraphRenderPngOptions, 'encoding' | 'signal'>;
+  renderOptions?: Omit<TextGraphRenderPngOptions, 'encoding' | 'signal' | 'onPreview'>;
   loading?: ReactNode;
+  /** Shown beside the provisional image until optional fonts finish loading. */
+  fontsLoading?: ReactNode;
 }
 
 export declare function TextGraphProvider(props: TextGraphProviderProps): ReactElement;

package/src/react/index.js

@@ -1,6 +1,6 @@
 'use client';
 
-import { createContext, createElement, useContext, useEffect, useMemo, useState } from 'react';
+import { Fragment, createContext, createElement, useContext, useEffect, useMemo, useState } from 'react';
 import { createRuntimeResource } from './runtime.js';
 
 const RuntimeContext = createContext(null);
@@ -15,12 +15,12 @@ export function TextGraphProvider({ options = defaultOptions, children }) {
 
 /** Renders DSL as an image; only the latest committed input may publish a result. */
 export function TextGraph({ source, alt = 'TextGraph diagram', renderOptions = defaultOptions,
-  loading = 'Rendering diagram…', style, ...imageProps }) {
+  loading = 'Rendering diagram…', fontsLoading = 'Fonts are still loading…', style, ...imageProps }) {
   const shared = useContext(RuntimeContext);
   const resource = useMemo(() => shared ?? createRuntimeResource(defaultOptions), [shared]);
-  const { scale = 1, padding, maxWidth } = renderOptions;
-  const request = useMemo(() => ({ source, scale, padding, maxWidth, resource }),
-    [source, scale, padding, maxWidth, resource]);
+  const { scale = 1, padding, maxWidth, language } = renderOptions;
+  const request = useMemo(() => ({ source, scale, padding, maxWidth, language, resource }),
+    [source, scale, padding, maxWidth, language, resource]);
   const [state, setState] = useState(null);
 
   useEffect(() => {
@@ -30,13 +30,16 @@ export function TextGraph({ source, alt = 'TextGraph diagram', renderOptions = d
       try {
         const runtime = await resource.get();
         if (controller.signal.aborted) return;
-        const result = await runtime.renderPng(source, { scale, padding, maxWidth, encoding: 'base64', signal: controller.signal });
+        const result = await runtime.renderPng(source, { scale, padding, maxWidth, language, encoding: 'base64', signal: controller.signal,
+          onPreview: result => { if (!controller.signal.aborted) setState({ request, result, fontsLoading: true }); },
+        });
         if (!controller.signal.aborted) setState({ request, result });
       } catch (error) {
         if (!controller.signal.aborted) {
           // Host loaders may reject arbitrary values, including null. Keep the
           // failure branch explicit so reporting an error cannot break React render.
-          setState({ request, error: error instanceof Error ? error : new Error(String(error ?? 'Could not render diagram')) });
+          setState(previous => ({ request, result: previous?.request === request ? previous.result : undefined,
+            error: error instanceof Error ? error : new Error(String(error ?? 'Could not render diagram')) }));
         }
       }
     })();
@@ -46,14 +49,17 @@ export function TextGraph({ source, alt = 'TextGraph diagram', renderOptions = d
   // State is keyed by the whole request so old images disappear immediately,
   // even before passive effects clean up the previous asynchronous render.
   if (state?.request !== request) return createElement('span', { role: 'status' }, loading);
-  if (state.error || !state.result.success) {
+  if (!state.result?.success) {
     const message = state.error?.message ?? state.result.diagnostics.map(item => item.message).join('\n');
     return createElement('span', { role: 'alert' }, message || 'Could not render diagram');
   }
   const result = state.result;
   // Density improves sharpness without enlarging the diagram. Native dimensions
   // also preserve logical size when maxWidth lowers the actual render density.
-  return createElement('img', { width: result.displayWidth ?? result.width / scale, height: result.displayHeight ?? result.height / scale, ...imageProps,
+  const image = createElement('img', { width: result.displayWidth ?? result.width / scale, height: result.displayHeight ?? result.height / scale, ...imageProps,
     style: { maxWidth: '100%', ...(imageProps.height == null ? { height: 'auto' } : {}), ...style },
     src: `data:image/png;base64,${result.png}`, alt });
+  if (state.error) return createElement(Fragment, null, image, createElement('span', { role: 'alert' }, state.error.message));
+  if (state.fontsLoading) return createElement(Fragment, null, image, createElement('span', { role: 'status' }, fontsLoading));
+  return image;
 }

package/src/runtime/font-cache.js

@@ -0,0 +1,36 @@
+import { readVerifiedAsset } from './integrity.js';
+import { throwIfAborted } from './lifecycle.js';
+
+const cacheName = 'textgraph-fonts-v1';
+
+/** HTTP fonts are immutable by content hash. Cache verified bytes in browsers
+ * and Workers without requiring host headers or a service worker; local files
+ * stay authoritative. Storage is optional and cannot turn valid I/O into failure. */
+export async function readVerifiedFontAsset(item, options, readAsset) {
+  if (!['http:', 'https:'].includes(item.url?.protocol)) return readVerifiedAsset(item, options, readAsset);
+  const url = new URL(item.url);
+  url.searchParams.set('v', item.asset.sha256);
+  const versioned = { ...item, url };
+  let cache;
+  try { cache = await globalThis.caches?.open(cacheName); } catch { /* Private contexts may deny storage. */ }
+  throwIfAborted(options.signal);
+  let cached;
+  try { cached = await cache?.match(url.href); } catch { /* Read from the configured source instead. */ }
+  throwIfAborted(options.signal);
+  if (cached) {
+    try {
+      const bytes = await readVerifiedAsset(versioned, options, async () => cached);
+      throwIfAborted(options.signal);
+      return bytes;
+    } catch {
+      throwIfAborted(options.signal);
+      // A damaged entry grants no authority: evict and verify the original source.
+      try { await cache.delete(url.href); } catch { /* A new download can still succeed. */ }
+    }
+  }
+  const bytes = await readVerifiedAsset(versioned, options, readAsset);
+  throwIfAborted(options.signal);
+  try { await cache?.put(url.href, new Response(bytes, { headers: { 'Content-Type': 'font/ttf' } })); } catch { /* Quota and storage failures are non-fatal. */ }
+  throwIfAborted(options.signal);
+  return bytes;
+}

package/src/runtime/font-resources.js

@@ -2,7 +2,7 @@ import { DrawMotiveError } from './errors.js';
 import { normalizeFontMetadata } from './language-packs.js';
 import { decodeDiagnostics } from './validation.js';
 import { decodeConfiguration } from './rendering.js';
-import { readVerifiedAsset } from './integrity.js';
+import { readVerifiedFontAsset } from './font-cache.js';
 import { throwIfAborted } from './lifecycle.js';
 
 export const fontCapability = 'textgraph-fonts-v1';
@@ -102,6 +102,7 @@ export function createFontPreparation({ options, readAsset, execute }) {
     const loading = { ...options, signal: context.signal };
     const attempted = new Set();
     let consumed = false;
+    let previewed = false;
     try {
       while (true) {
         throwIfAborted(context.signal);
@@ -110,6 +111,14 @@ export function createFontPreparation({ options, readAsset, execute }) {
         if (!prepared.success) return JSON.stringify({ protocolVersion: 1, success: false, diagnostics: prepared.diagnostics });
         const missing = prepared.fontRuns.filter(run => run.missing && run.language);
         if (!missing.length) break;
+        // Native can render with its installed fallback fonts. Publish that image
+        // before optional I/O; final measurement still runs after installation.
+        if (context.onPreview && !previewed) {
+          const preview = await execute(request);
+          throwIfAborted(context.signal);
+          context.onPreview(preview);
+          previewed = true;
+        }
         const selected = new Set();
         let available = explicit;
         for (const run of missing) {
@@ -126,7 +135,7 @@ export function createFontPreparation({ options, readAsset, execute }) {
         for (const font of selected) {
           attempted.add(font.family);
           throwIfAborted(context.signal);
-          const bytes = await readVerifiedAsset({ asset: { path: `font:${font.family}`, bytes: font.bytes, sha256: font.sha256, mediaType: 'font/ttf' }, url: font.source }, loading,
+          const bytes = await readVerifiedFontAsset({ asset: { path: `font:${font.family}`, bytes: font.bytes, sha256: font.sha256, mediaType: 'font/ttf' }, url: font.source }, loading,
             font.source instanceof Uint8Array ? async () => new Response(font.source) : readAsset);
           throwIfAborted(context.signal);
           fonts.push({ family: font.family, data: fontBase64(bytes), languages: font.languages });

package/src/runtime/render-resources.js

@@ -1,5 +1,6 @@
 import { createRuntimeAssetPlan } from './shared.js';
 import { readVerifiedAsset } from './integrity.js';
+import { readVerifiedFontAsset } from './font-cache.js';
 import { decodeConfiguration } from './rendering.js';
 import { throwIfAborted } from './lifecycle.js';
 import { createFontPreparation, fontBase64 as base64, fontCapability } from './font-resources.js';
@@ -18,9 +19,10 @@ export function createRenderingExecutor({ manifest, options, readAsset, execute
       const selected = new Set([manifest.rendering.theme, ...manifest.rendering.fonts.map(font => font.asset)]);
       const plan = createRuntimeAssetPlan({ manifest: { assets: manifest.assets.filter(asset => selected.has(asset.path)) }, moduleUrl: import.meta.url, resolveAsset: options.resolveAsset });
       const byPath = new Map(plan.map(item => [item.asset.path, item]));
+      const fontPaths = new Set(manifest.rendering.fonts.map(font => font.asset));
       const load = async path => {
         throwIfAborted(context.signal);
-        const bytes = await readVerifiedAsset(byPath.get(path), loadingOptions, readAsset);
+        const bytes = await (fontPaths.has(path) ? readVerifiedFontAsset : readVerifiedAsset)(byPath.get(path), loadingOptions, readAsset);
         throwIfAborted(context.signal);
         return bytes;
       };
@@ -34,7 +36,7 @@ export function createRenderingExecutor({ manifest, options, readAsset, execute
           throwIfAborted(context.signal);
           const item = { asset: { path: `font:${font.family}`, mediaType: 'font/ttf', bytes: font.bytes, sha256: font.sha256 }, url: font.source };
           const bytes = font.coverage
-            ? await readVerifiedAsset(item, loadingOptions, font.source instanceof Uint8Array ? async () => new Response(font.source) : readAsset)
+            ? await readVerifiedFontAsset(item, loadingOptions, font.source instanceof Uint8Array ? async () => new Response(font.source) : readAsset)
             : font.source instanceof Uint8Array ? font.source : new Uint8Array(await (await readAsset(item, loadingOptions)).arrayBuffer());
           throwIfAborted(context.signal);
           fonts.push({ family: font.family, data: base64(bytes), ...(font.languages ? { languages: font.languages } : {}) });

package/src/runtime/rendering.js

@@ -7,30 +7,31 @@ const invalid = message => { throw new DrawMotiveError('INVALID_ARGUMENT', messa
 /** Both export formats share source, logical padding, language and cancellation semantics. */
 function normalizeCommonOptions(source, options) {
   if (typeof source !== 'string' || !options || typeof options !== 'object' || Array.isArray(options)) invalid('Rendering requires a source string and options object');
-  const { padding = 10, signal, language } = options;
+  const { padding = 10, signal, language, onPreview } = options;
+  if (onPreview !== undefined && typeof onPreview !== 'function') invalid('onPreview must be a function');
   if (language !== undefined && (typeof language !== 'string' || !/^[a-z]{2,8}(?:-[A-Za-z0-9]+)*$/.test(language))) invalid('language must be a language tag');
   // The native geometry contract uses float32; reject values lost at that boundary.
   if (!Number.isFinite(padding) || !Number.isFinite(Math.fround(padding)) || padding < 0) invalid('padding must be non-negative and representable as a finite float32');
   validateSignal(signal);
-  return { padding, signal, request: { protocolVersion: 1, operation: 'render', source, ...(language === undefined ? {} : { language }) } };
+  return { padding, signal, onPreview, request: { protocolVersion: 1, operation: 'render', source, ...(language === undefined ? {} : { language }) } };
 }
 
 /** Normalize export settings before queuing; native receives only the render contract. */
 export function normalizeRenderOptions(source, options) {
-  const { padding, signal, request } = normalizeCommonOptions(source, options);
+  const { padding, signal, onPreview, request } = normalizeCommonOptions(source, options);
   const { encoding = 'bytes', scale = 1, maxWidth } = options;
   if (!['bytes', 'base64'].includes(encoding)) invalid('encoding must be bytes or base64');
   // The native geometry contract uses float32; reject values lost at that boundary.
   if (!Number.isFinite(scale) || !Number.isFinite(Math.fround(scale)) || Math.fround(scale) <= 0) invalid('scale must be positive and representable as a finite float32');
   if (maxWidth !== undefined && (!Number.isSafeInteger(maxWidth) || maxWidth <= 0)) invalid('maxWidth must be a positive integer');
-  return { encoding, signal, request: { ...request, export: { format: 'png', scale, padding, ...(maxWidth === undefined ? {} : { maxWidth }) } } };
+  return { encoding, signal, onPreview, request: { ...request, export: { format: 'png', scale, padding, ...(maxWidth === undefined ? {} : { maxWidth }) } } };
 }
 
 /** SVG accepts only logical export settings; PNG density and encoding have no vector meaning. */
 export function normalizeSvgOptions(source, options) {
-  const { padding, signal, request } = normalizeCommonOptions(source, options);
-  if (Reflect.ownKeys(options).some(key => !['padding', 'language', 'signal'].includes(key))) invalid('Unknown SVG rendering option');
-  return { signal, request: { ...request, export: { format: 'svg', padding } } };
+  const { padding, signal, onPreview, request } = normalizeCommonOptions(source, options);
+  if (Reflect.ownKeys(options).some(key => !['padding', 'language', 'signal', 'onPreview'].includes(key))) invalid('Unknown SVG rendering option');
+  return { signal, onPreview, request: { ...request, export: { format: 'svg', padding } } };
 }
 
 /** Accept canonical base64 only; platform atob implementations otherwise tolerate corruption. */