com.robotsquid.squidhub 0.5.0

package/Bridge~/squidhub-bridge.js

@@ -0,0 +1,4 @@
+// GENERATED FILE — do not edit by hand.
+// Source: engine/bridge-entry.js. Regenerate: npm run generate
+// Installs window.SquidHub. Load it BEFORE your engine's bootstrap.
+"use strict";(()=>{var h="squidhub",C=["https://robotsquid.dev","https://robotsquid.com"],N=["saves.get","saves.put","analytics.track","commerce.purchase"];var s=class extends Error{code;retryAfter;constructor(e,t,r){super(t,r?.cause!==void 0?{cause:r.cause}:void 0),this.name="SquidHubError",this.code=e,r?.retryAfter!==void 0&&(this.retryAfter=r.retryAfter)}},g=class extends s{serverCopy;constructor(e){super("CONFLICT","save version conflict \u2014 another device wrote first"),this.name="SaveConflictError",this.serverCopy=e}};var I=new Set,v=!1,R=!1,k=null,H=null;function M(n){try{n.gain.value=v?0:1}catch{}}function x(n){n.querySelectorAll("audio, video").forEach(e=>{e.muted=v})}function V(n=window){if(R)return;R=!0;let e=["AudioContext","webkitAudioContext"];for(let t of e){let r=n[t];if(typeof r!="function")continue;let o=function(...c){let a=new r(...c);try{let y=a.destination,l=a.createGain();l.connect(y),M(l),I.add(l),Object.defineProperty(a,"destination",{configurable:!0,get:()=>l})}catch{}return a};o.prototype=r.prototype,n[t]=o}typeof n.MutationObserver=="function"&&n.document&&(k=new n.MutationObserver(()=>x(n.document)),k.observe(n.document.documentElement,{childList:!0,subtree:!0}))}function P(n){v=n;for(let e of I)M(e);typeof document<"u"&&x(document);try{H?.(v)}catch{}}function $(n){if(!n)throw new s("UNTRUSTED_EMBEDDER","no referrer \u2014 the game must be embedded by the SquidHub portal");let e;try{e=new URL(n).origin}catch(t){throw new s("UNTRUSTED_EMBEDDER",`malformed referrer: ${n}`,{cause:t})}if(!C.includes(e))throw new s("UNTRUSTED_EMBEDDER",`embedder ${e} is not a SquidHub portal \u2014 refusing to hand shake`);return e}function j(n){let t=new URLSearchParams(n.replace(/^#/,"")).get("s");if(!t)throw new s("PROTOCOL","missing launch nonce \u2014 the game was not opened through the SquidHub portal");return t}var A=class{session;#n;#e=new Map;#o=0;#r;constructor(e,t,r){this.session=e,this.#n=t,this.#r=r,t.onmessage=o=>this.#s(o.data)}get connected(){return this.#n!==null}can(e){return this.session.capabilities.includes(e)}close(){for(let[,e]of this.#e)clearTimeout(e.timer),e.reject(new s("NOT_CONNECTED","SDK closed"));this.#e.clear(),this.#n?.close(),this.#n=null}#s(e){if(typeof e!="object"||e===null)return;let t=e;if(t.t===`${h}.audio`&&typeof t.muted=="boolean"){P(t.muted);return}if(typeof t.id!="string")return;let r=this.#e.get(t.id);if(!r)return;if(this.#e.delete(t.id),clearTimeout(r.timer),t.ok===!0){r.resolve(t.r);return}let o=t.e??{};r.reject(new s(o.code??"PROTOCOL",o.message??"request failed",o.retryAfter!==void 0?{retryAfter:o.retryAfter}:void 0))}#t(e,t){let r=this.#n;if(!r)return Promise.reject(new s("NOT_CONNECTED","SDK is not connected"));let o=`r${++this.#o}`;return new Promise((c,a)=>{let y=setTimeout(()=>{this.#e.delete(o),a(new s("TIMEOUT",`${e} timed out`))},this.#r);this.#e.set(o,{resolve:c,reject:a,timer:y}),r.postMessage({id:o,v:1,t:e,p:t})})}saves={get:()=>this.#t("saves.get",{}),put:async(e,t)=>{if(e.byteLength>8388608)throw new s("INVALID",`save is ${e.byteLength} bytes, over the ${8388608} limit`);try{return await this.#t("saves.put",{data:e,...t?.ifVersion!==void 0?{ifVersion:t.ifVersion}:{}})}catch(r){if(r instanceof s&&r.code==="CONFLICT"){let o=await this.saves.get();if(o)throw new g(o)}throw r}}};analytics={track:(e,t)=>{this.#t("analytics.track",{name:e,props:t}).catch(()=>{})}};commerce={purchase:(e,t)=>this.#t("commerce.purchase",{sku:e,idempotencyKey:t})}};async function D(n={},e=globalThis.window){let t=n.handshakeTimeoutMs??15e3,r=n.requestTimeoutMs??2e4;V(e);let o=$(e.document.referrer),c=j(e.location.hash),a=n.helloRetryMs??150;return new Promise((y,l)=>{let p,m=()=>{clearTimeout(b),p!==void 0&&clearInterval(p),e.removeEventListener("message",i)},b=setTimeout(()=>{m(),l(new s("TIMEOUT","portal did not complete the handshake"))},t);function i(u){if(u.origin!==o)return;let f=u.data;if(!f||f.t!==`${h}.ready`||f.v!==1)return;let w=u.ports[0];w&&(m(),w.start?.(),y(new A(f.session,w,r)))}e.addEventListener("message",i);let d=()=>e.parent.postMessage({t:`${h}.hello`,v:1,nonce:c},o);d(),p=setInterval(d,a)})}var B="SquidHub",_=32768;function G(n){let e="";for(let t=0;t<n.length;t+=_)e+=String.fromCharCode(...n.subarray(t,t+_));return btoa(e)}function J(n){let e=atob(n),t=new Uint8Array(e.length);for(let r=0;r<e.length;r++)t[r]=e.charCodeAt(r);return t}function O(n){return n instanceof Uint8Array?G(n):Array.isArray(n)?n.map(O):n&&typeof n=="object"?Object.fromEntries(Object.entries(n).map(([e,t])=>[e,O(t)])):n}function F(n,e){let t=n[e];if(typeof t!="number"||!Number.isInteger(t))throw new s("INVALID",`${e} must be an integer, got ${JSON.stringify(t)}`);return t}function E(n,e){let t=n[e];if(typeof t!="string")throw new s("INVALID",`${e} must be a string, got ${JSON.stringify(t)}`);return t}function W(n,e){try{return J(E(n,e))}catch(t){throw new s("INVALID",`${e} is not valid base64`,{cause:t})}}function K(n,e){let t=n[e];if(t==null)return;if(typeof t!="object"||Array.isArray(t))throw new s("INVALID",`${e} must be an object`);let r={};for(let[o,c]of Object.entries(t)){if(typeof c!="string"&&typeof c!="number"&&typeof c!="boolean")throw new s("INVALID",`${e}.${o} must be a string, number or boolean`);r[o]=c}return r}var X={"saves.get":n=>n.saves.get(),"saves.put":(n,e)=>n.saves.put(W(e,"data"),e.ifVersion===void 0?void 0:{ifVersion:F(e,"ifVersion")}),"analytics.track":(n,e)=>(n.analytics.track(E(e,"name"),K(e,"props")),null),"commerce.purchase":(n,e)=>n.commerce.purchase(E(e,"sku"),E(e,"idempotencyKey"))};function Y(n){return N.includes(n)}function U(n){return n instanceof s?n.code:"PROTOCOL"}function z(n){let e=n instanceof s?n:void 0;return JSON.stringify({ok:!1,code:U(n),message:n instanceof Error?n.message:String(n),...e?.retryAfter!==void 0?{retryAfter:e.retryAfter}:{},...n instanceof g?{serverCopy:O(n.serverCopy)}:{}})}function T(n={},e=globalThis){let t=null,r="connecting",o="",c=D(n).then(i=>(t=i,r="ready",i),i=>{throw r="failed",o=`${U(i)}: ${i instanceof Error?i.message:String(i)}`,i});c.catch(()=>{});let a=new Map,y=0,l=64;function p(i,d){if(a.size>=l){let u=a.keys().next();u.done||a.delete(u.value)}a.set(i,d)}async function m(i,d){try{if(!Y(i))throw new s("INVALID",`unknown verb ${i}`);let u;try{u=JSON.parse(d||"{}")??{}}catch(q){throw new s("INVALID","payload is not valid JSON",{cause:q})}let f=await c,w=await X[i](f,u);return JSON.stringify({ok:!0,value:O(w)??null})}catch(u){return z(u)}}let b={status:()=>r,error:()=>o,session:()=>t?JSON.stringify(t.session):"",invoke(i,d="{}"){let u=`c${++y}`;return m(i,d).then(f=>p(u,f)),u},notify(i,d="{}"){m(i,d)},poll(i){let d=a.get(i);return d===void 0?"":(a.delete(i),d)},close(){t?.close()}};return e[B]=b,b}T();})();

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.5.0
+
+First release. Wraps `@squidhub/game-sdk` 0.5.0.
+
+- `SquidHub.Sdk` — saves, analytics and commerce from C#, with the `.jslib`
+  half included and linked for WebGL.
+- The page bridge ships prebuilt. No npm, no esbuild, no bundling step.
+- A post-build step rewrites the exported `index.html` so it survives the
+  platform's CSP: every inline script is hoisted to an external file and the
+  bridge is injected ahead of the Unity loader. Works with the stock Default
+  and Minimal templates — there is no template to choose.
+- A pre-build step refuses builds that cannot run on the platform (pthreads on,
+  `.jslib` not linked, bridge missing) instead of letting them fail in a
+  browser twenty minutes later.
+- ⚠️ **Save conflicts are now resolvable from Unity.** The `.jslib` flattened an
+  error to code + message and discarded the rest, so a `CONFLICT` arrived in C#
+  with no server copy — leaving a Unity game unable to merge, which is the one
+  thing the platform cannot do on its behalf. `SquidHubException.ServerCopy`
+  carries it now.
+- `SquidHub.Sdk` now compiles and no-ops outside WebGL, so pressing Play no
+  longer throws `EntryPointNotFoundException`. It reports failure; it never
+  fakes a session.

package/Editor/RobotSquid.SquidHub.Editor.asmdef

@@ -0,0 +1,18 @@
+{
+    "name": "RobotSquid.SquidHub.Editor",
+    "rootNamespace": "SquidHub.Editor",
+    "references": [
+        "RobotSquid.SquidHub"
+    ],
+    "includePlatforms": [
+        "Editor"
+    ],
+    "excludePlatforms": [],
+    "allowUnsafeCode": false,
+    "overrideReferences": false,
+    "precompiledReferences": [],
+    "autoReferenced": true,
+    "defineConstraints": [],
+    "versionDefines": [],
+    "noEngineReferences": false
+}

package/Editor/RobotSquid.SquidHub.Editor.asmdef.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 430031ce25b37214b5af31dc4154467f
+AssemblyDefinitionImporter:
+  externalObjects: {}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/Editor/SquidHubAudit.cs

@@ -0,0 +1,125 @@
+// Everything that must be true before a build can run on SquidHub.
+//
+// ⚠️ Each of these fails QUIETLY at runtime if it is wrong: a missing bridge is
+// a handshake that times out after fifteen seconds, an unlinked .jslib is a
+// DllImport that resolves to nothing, and pthreads is a SharedArrayBuffer error
+// from deep inside the engine. Catching them at build time is the whole point
+// of this file.
+using System.Collections.Generic;
+using System.Linq;
+using UnityEditor;
+using UnityEditor.Build;
+
+namespace SquidHub.Editor
+{
+    internal sealed class Finding
+    {
+        public bool Fatal;
+        public string Message;
+    }
+
+    internal static class SquidHubAudit
+    {
+        /// <summary>Escape hatch, added to the WebGL scripting define symbols.</summary>
+        public const string AllowThreadsDefine = "SQUIDHUB_ALLOW_THREADS";
+
+        public static List<Finding> Run()
+        {
+            var findings = new List<Finding>();
+
+            if (SquidHubPackage.FindBridge() == null)
+            {
+                Fatal(findings,
+                    "squidhub-bridge.js is missing from the package (Bridge~/). The build " +
+                    "would ship with no window.SquidHub, and every game would hang on the " +
+                    "handshake for 15 seconds and then fail. Reinstall the package.");
+            }
+
+            CheckJslib(findings);
+            CheckThreads(findings);
+            CheckCompression(findings);
+
+            return findings;
+        }
+
+        // ⚠️ A .jslib that is not marked compatible with WebGL is not an error
+        // Unity reports in any useful way — the DllImports simply do not link.
+        // Assert on the importer rather than trusting the .meta we shipped.
+        private static void CheckJslib(List<Finding> findings)
+        {
+            var importer = AssetImporter.GetAtPath(SquidHubPackage.JslibAssetPath) as PluginImporter;
+            if (importer == null)
+            {
+                Warn(findings,
+                    "Could not read the plugin importer for " + SquidHubPackage.JslibAssetPath +
+                    ". If the build fails to link SquidHubInvoke, select that file and tick " +
+                    "WebGL under Platform settings.");
+                return;
+            }
+
+            if (!importer.GetCompatibleWithPlatform(BuildTarget.WebGL))
+            {
+                Fatal(findings,
+                    "SquidHub.jslib is not marked compatible with WebGL, so the " +
+                    "[DllImport(\"__Internal\")] entry points will not link. Select " +
+                    SquidHubPackage.JslibAssetPath + " and tick WebGL under Platform settings.");
+            }
+        }
+
+        private static void CheckThreads(List<Finding> findings)
+        {
+            if (!PlayerSettings.WebGL.threadsSupport) return;
+
+            if (AllowsThreads())
+            {
+                Warn(findings,
+                    "pthreads is enabled and " + AllowThreadsDefine + " is set. This build " +
+                    "needs SharedArrayBuffer, so it can only run on the isolated tier — which " +
+                    "carries no ads. Talk to your SquidHub representative before shipping it.");
+                return;
+            }
+
+            Fatal(findings,
+                "pthreads is enabled (Player Settings > WebGL > Enable Native C/C++ " +
+                "Multithreading). SquidHub's default tier is not cross-origin isolated, so " +
+                "SharedArrayBuffer does not exist and this build cannot start. Turn it off. " +
+                "If you genuinely need threads, ask about the isolated tier and add " +
+                AllowThreadsDefine + " to the WebGL scripting define symbols to silence this.");
+        }
+
+        private static void CheckCompression(List<Finding> findings)
+        {
+            var format = PlayerSettings.WebGL.compressionFormat;
+
+            if (format == WebGLCompressionFormat.Disabled)
+            {
+                Warn(findings,
+                    "Compression is disabled. squidhub-release records Content-Encoding from " +
+                    "the file suffix at upload, so Brotli costs you nothing at runtime and " +
+                    "saves the player most of the download.");
+            }
+
+            // ⚠️ Not an error — just weight. The platform serves the correct
+            // Content-Encoding, so the JS decompressor never has to run.
+            if (PlayerSettings.WebGL.decompressionFallback)
+            {
+                Warn(findings,
+                    "Decompression Fallback is on. squidhub-release strips the .br suffix and " +
+                    "records Content-Encoding: br in R2, so the browser decompresses natively " +
+                    "and the bundled JS decompressor is dead weight. Turning it off is safe here.");
+            }
+        }
+
+        private static bool AllowsThreads()
+        {
+            var defines = PlayerSettings.GetScriptingDefineSymbols(NamedBuildTarget.WebGL);
+            return defines.Split(';').Select(d => d.Trim()).Contains(AllowThreadsDefine);
+        }
+
+        private static void Fatal(List<Finding> list, string message) =>
+            list.Add(new Finding { Fatal = true, Message = message });
+
+        private static void Warn(List<Finding> list, string message) =>
+            list.Add(new Finding { Fatal = false, Message = message });
+    }
+}

package/Editor/SquidHubAudit.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: b69b996a13d4d79deefbbfde630afb09
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/Editor/SquidHubBuildProcessor.cs

@@ -0,0 +1,115 @@
+// The whole of the integration, from the publisher's point of view: install the
+// package, press Build, get something the platform will serve.
+//
+// The pre-build half refuses builds that cannot possibly run. The post-build
+// half writes the bridge in and makes the HTML CSP-safe.
+using System.IO;
+using System.Linq;
+using System.Text;
+using UnityEditor;
+using UnityEditor.Build;
+using UnityEditor.Build.Reporting;
+using UnityEngine;
+
+namespace SquidHub.Editor
+{
+    /// <summary>Refuses a build that could not run on SquidHub, before it is made.</summary>
+    internal sealed class SquidHubBuildPreprocessor : IPreprocessBuildWithReport
+    {
+        public int callbackOrder => 0;
+
+        public void OnPreprocessBuild(BuildReport report)
+        {
+            if (report.summary.platform != BuildTarget.WebGL) return;
+
+            var findings = SquidHubAudit.Run();
+            foreach (var finding in findings.Where(f => !f.Fatal))
+                Debug.LogWarning("SquidHub: " + finding.Message);
+
+            var fatal = findings.Where(f => f.Fatal).ToList();
+            if (fatal.Count == 0) return;
+
+            var message = new StringBuilder("SquidHub: this build cannot run on the platform.\n");
+            foreach (var f in fatal) message.Append("\n  • ").Append(f.Message).Append('\n');
+
+            // ⚠️ Throwing here fails the build. That is the point: every one of
+            // these produces a game that loads and then does nothing, which is
+            // far more expensive to diagnose than a refused build.
+            throw new BuildFailedException(message.ToString());
+        }
+    }
+
+    /// <summary>Installs the bridge and rewrites index.html so the CSP will run it.</summary>
+    internal sealed class SquidHubBuildPostprocessor : IPostprocessBuildWithReport
+    {
+        public int callbackOrder => 0;
+
+        public void OnPostprocessBuild(BuildReport report)
+        {
+            if (report.summary.platform != BuildTarget.WebGL) return;
+
+            var outDir = report.summary.outputPath;
+            if (string.IsNullOrEmpty(outDir) || !Directory.Exists(outDir))
+            {
+                Debug.LogError("SquidHub: build output directory not found at '" + outDir +
+                               "'. The bridge was NOT installed and this build will not run.");
+                return;
+            }
+
+            var indexPath = Path.Combine(outDir, "index.html");
+            if (!File.Exists(indexPath))
+            {
+                Debug.LogError("SquidHub: no index.html in the build output. The bridge was NOT " +
+                               "installed and this build will not run.");
+                return;
+            }
+
+            var log = new StringBuilder("SquidHub: WebGL build prepared\n");
+
+            if (!InstallBridge(outDir, log)) return;
+
+            var result = SquidHubHtml.Apply(File.ReadAllText(indexPath), SquidHubPackage.BridgeFileName);
+
+            foreach (var extracted in result.Extracted)
+            {
+                File.WriteAllText(Path.Combine(outDir, extracted.Key), extracted.Value);
+                log.Append("  ✓ hoisted an inline script → ").Append(extracted.Key).Append('\n');
+            }
+
+            if (result.Extracted.Count == 0)
+                log.Append("  · no inline scripts to hoist\n");
+
+            File.WriteAllText(indexPath, result.Html);
+            foreach (var note in result.Notes) log.Append("  ✓ ").Append(note).Append('\n');
+
+            log.Append("\nPush it with:\n  node src/cli.mjs push --game <slug> --dir ")
+               .Append(outDir).Append(" --env=dev --verify");
+
+            Debug.Log(log.ToString());
+        }
+
+        private static bool InstallBridge(string outDir, StringBuilder log)
+        {
+            var source = SquidHubPackage.FindBridge();
+            if (source == null)
+            {
+                Debug.LogError("SquidHub: squidhub-bridge.js is missing from the package. This " +
+                               "build has no window.SquidHub and every handshake will time out.");
+                return false;
+            }
+
+            var destination = Path.Combine(outDir, SquidHubPackage.BridgeFileName);
+            File.Copy(source, destination, true);
+
+            // ⚠️ Files in Library/PackageCache are commonly read-only, and
+            // File.Copy carries the attribute across. Left alone, the NEXT build
+            // into this directory fails on the overwrite.
+            var attributes = File.GetAttributes(destination);
+            if ((attributes & FileAttributes.ReadOnly) != 0)
+                File.SetAttributes(destination, attributes & ~FileAttributes.ReadOnly);
+
+            log.Append("  ✓ wrote ").Append(SquidHubPackage.BridgeFileName).Append('\n');
+            return true;
+        }
+    }
+}

package/Editor/SquidHubBuildProcessor.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: ab81305096e6d6dd98994e428be9c6c4
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/Editor/SquidHubHtml.cs

@@ -0,0 +1,126 @@
+// Rewrites an exported index.html into one the platform's CSP will actually run.
+//
+// squidhub-gamehost serves `script-src 'self' 'wasm-unsafe-eval' blob:` with no
+// 'unsafe-inline'. Unity's templates — including the stock Default and Minimal
+// ones — inline their bootstrap, and the failure is silent: the page loads, all
+// the markup is there, and nothing runs. The only signal is a CSP violation in
+// the console.
+//
+// ⚠️ Pure text in, pure text out, no UnityEditor types. That is deliberate: it
+// is the one piece of this package with real logic, so it stays readable and
+// runnable outside a build.
+using System;
+using System.Collections.Generic;
+using System.Text.RegularExpressions;
+
+namespace SquidHub.Editor
+{
+    internal static class SquidHubHtml
+    {
+        internal sealed class Result
+        {
+            public string Html;
+            public bool Changed;
+            /// <summary>Filename → contents, for each inline block that was hoisted out.</summary>
+            public readonly List<KeyValuePair<string, string>> Extracted =
+                new List<KeyValuePair<string, string>>();
+            public readonly List<string> Notes = new List<string>();
+        }
+
+        private static readonly Regex ScriptTag = new Regex(
+            @"<script\b([^>]*)>(.*?)</script\s*>",
+            RegexOptions.IgnoreCase | RegexOptions.Singleline | RegexOptions.CultureInvariant);
+
+        private static readonly Regex SrcAttr = new Regex(
+            @"\bsrc\s*=", RegexOptions.IgnoreCase | RegexOptions.CultureInvariant);
+
+        private static readonly Regex TypeAttr = new Regex(
+            @"\btype\s*=\s*(""([^""]*)""|'([^']*)'|([^\s>]+))",
+            RegexOptions.IgnoreCase | RegexOptions.CultureInvariant);
+
+        // ⚠️ Anything NOT in here is data, not code — `application/json`,
+        // `text/template` and friends are never executed, so CSP does not care
+        // and hoisting them would break the page that reads them by id.
+        private static readonly HashSet<string> ExecutableTypes =
+            new HashSet<string>(StringComparer.OrdinalIgnoreCase)
+            {
+                "", "module",
+                "text/javascript", "application/javascript",
+                "text/ecmascript", "application/ecmascript",
+            };
+
+        public static Result Apply(string html, string bridgeFileName)
+        {
+            var result = new Result { Html = html };
+
+            // ⚠️ Idempotent. A rebuild into a directory that was already
+            // processed must not stack a second bridge tag or renumber the
+            // hoisted files out from under the HTML that references them.
+            if (html.IndexOf(bridgeFileName, StringComparison.OrdinalIgnoreCase) >= 0)
+            {
+                result.Notes.Add("already processed — left alone");
+                return result;
+            }
+
+            var index = 0;
+            var rewritten = ScriptTag.Replace(html, match =>
+            {
+                var attrs = match.Groups[1].Value;
+                var body = match.Groups[2].Value;
+
+                if (SrcAttr.IsMatch(attrs)) return match.Value;          // already external
+                if (string.IsNullOrWhiteSpace(body)) return match.Value; // nothing to hoist
+                if (!IsExecutable(attrs)) return match.Value;            // data, not code
+
+                var name = "squidhub-inline-" + index++ + ".js";
+                result.Extracted.Add(new KeyValuePair<string, string>(name, body));
+
+                // ⚠️ Attributes are carried across verbatim. Dropping a
+                // `type="module"` here would turn a deferred module into a
+                // classic script and silently reorder execution.
+                var carried = attrs.TrimEnd();
+                return "<script" + carried + " src=\"" + name + "\"></script>";
+            });
+
+            var tag = "<script src=\"" + bridgeFileName + "\"></script>";
+            result.Html = InsertBridge(rewritten, tag, result);
+            result.Changed = !ReferenceEquals(result.Html, html) && result.Html != html;
+            return result;
+        }
+
+        private static bool IsExecutable(string attrs)
+        {
+            var m = TypeAttr.Match(attrs);
+            if (!m.Success) return true; // no type attribute at all == classic script
+            var value = m.Groups[2].Success ? m.Groups[2].Value
+                      : m.Groups[3].Success ? m.Groups[3].Value
+                      : m.Groups[4].Value;
+            return ExecutableTypes.Contains(value.Trim());
+        }
+
+        // ⚠️ Before the FIRST script in the document, not merely before the
+        // loader. installBridge() patches AudioContext.destination on the
+        // instance, so it only catches contexts created after it runs — land
+        // after the engine boots and the portal's mute button is inert.
+        private static string InsertBridge(string html, string tag, Result result)
+        {
+            var at = html.IndexOf("<script", StringComparison.OrdinalIgnoreCase);
+            if (at >= 0)
+            {
+                result.Notes.Add("bridge injected before the first script");
+                return html.Substring(0, at) + tag + "\n    " + html.Substring(at);
+            }
+
+            foreach (var close in new[] { "</head>", "</body>" })
+            {
+                at = html.IndexOf(close, StringComparison.OrdinalIgnoreCase);
+                if (at < 0) continue;
+                result.Notes.Add("no script tags found — bridge injected before " + close);
+                return html.Substring(0, at) + "    " + tag + "\n" + html.Substring(at);
+            }
+
+            result.Notes.Add("no script tags and no </head> or </body> — bridge prepended");
+            return tag + "\n" + html;
+        }
+    }
+}

package/Editor/SquidHubHtml.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: db08e9ede2c0b7b71a088d972ce8bfaa
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/Editor/SquidHubMenu.cs

@@ -0,0 +1,43 @@
+// The same audit the build runs, on demand — so a publisher can find out what is
+// wrong without waiting for a WebGL build to finish first.
+using System.Linq;
+using UnityEditor;
+using UnityEngine;
+
+namespace SquidHub.Editor
+{
+    internal static class SquidHubMenu
+    {
+        [MenuItem("SquidHub/Check WebGL Settings", priority = 0)]
+        private static void Check()
+        {
+            var findings = SquidHubAudit.Run();
+            if (findings.Count == 0)
+            {
+                EditorUtility.DisplayDialog("SquidHub",
+                    "Ready to build.\n\nThe bridge is present, SquidHub.jslib is linked for " +
+                    "WebGL, and nothing in Player Settings would stop this game running on " +
+                    "the platform.", "OK");
+                return;
+            }
+
+            foreach (var finding in findings)
+            {
+                if (finding.Fatal) Debug.LogError("SquidHub: " + finding.Message);
+                else Debug.LogWarning("SquidHub: " + finding.Message);
+            }
+
+            var fatal = findings.Count(f => f.Fatal);
+            EditorUtility.DisplayDialog("SquidHub",
+                fatal > 0
+                    ? fatal + " problem(s) would fail the build, and " + (findings.Count - fatal) +
+                      " warning(s) are worth reading. Details are in the Console."
+                    : findings.Count + " warning(s). Details are in the Console.",
+                "OK");
+        }
+
+        [MenuItem("SquidHub/Documentation", priority = 20)]
+        private static void Documentation() =>
+            Application.OpenURL("https://www.npmjs.com/package/@squidhub/game-sdk");
+    }
+}

package/Editor/SquidHubMenu.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 803000a5ee41dab5bfcd018f5af945c2
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/Editor/SquidHubPackage.cs

@@ -0,0 +1,48 @@
+// Locating our own files on disk, from Editor code.
+//
+// ⚠️ The bridge lives in `Bridge~/`, and the trailing tilde is load-bearing:
+// Unity ignores such folders entirely, so the file is never imported, never
+// given a .meta, and — the actual reason — never handed to Unity's own
+// JavaScript handling. It ships in the package like any other file; it simply
+// is not an asset. That means it must be read from DISK, not the AssetDatabase.
+using System.IO;
+using UnityEditor.PackageManager;
+
+namespace SquidHub.Editor
+{
+    internal static class SquidHubPackage
+    {
+        public const string Name = "com.robotsquid.squidhub";
+
+        /// <summary>The bridge script's path on disk, or null if it is missing.</summary>
+        public static string FindBridge()
+        {
+            foreach (var root in Roots())
+            {
+                if (string.IsNullOrEmpty(root)) continue;
+                var candidate = Path.Combine(root, "Bridge~", BridgeFileName);
+                if (File.Exists(candidate)) return candidate;
+            }
+            return null;
+        }
+
+        /// <summary>What the bridge is called once it is sitting in a build.</summary>
+        public const string BridgeFileName = "squidhub-bridge.js";
+
+        /// <summary>The .jslib's AssetDatabase path — a package path, not an Assets one.</summary>
+        public const string JslibAssetPath =
+            "Packages/" + Name + "/Runtime/Plugins/WebGL/SquidHub.jslib";
+
+        // ⚠️ Two roots, because resolvedPath covers a registry install (which
+        // lives in the global package cache) while the literal Packages/ path
+        // covers an embedded or local one. Neither alone covers both.
+        private static string[] Roots()
+        {
+            string resolved = null;
+            var info = PackageInfo.FindForAssembly(typeof(SquidHubPackage).Assembly);
+            if (info != null) resolved = info.resolvedPath;
+
+            return new[] { resolved, Path.GetFullPath(Path.Combine("Packages", Name)) };
+        }
+    }
+}

package/Editor/SquidHubPackage.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 3075668b6a2faefd57f78d251a414b56
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/Editor.meta

@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: c52e4341272685d27b443bb48b810773
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) RobotSquid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# SquidHub for Unity
+
+Cloud saves, analytics and the coin economy for Unity WebGL games on
+[SquidHub](https://robotsquid.dev).
+
+Install it, press Build. There is no bundling step, no WebGL template to pick
+and nothing to copy into `Assets/`.
+
+## Install
+
+Add the registry to `Packages/manifest.json`:
+
+```jsonc
+{
+  "scopedRegistries": [
+    {
+      "name": "RobotSquid",
+      "url": "https://registry.npmjs.org",
+      "scopes": ["com.robotsquid"]
+    }
+  ]
+}
+```
+
+Then **Window > Package Manager > My Registries > SquidHub > Install**.
+
+Unity 2021.3 or newer.
+
+## Use it
+
+```csharp
+using System.Collections.Generic;
+using SquidHub;
+
+async void Start()
+{
+    await Sdk.WaitForReadyAsync();          // throws if the portal refuses
+
+    var json = await Sdk.SavesGetAsync();   // JSON; parse with your own library
+    // `data` inside it is base64 — Sdk.FromBase64(...) gives you the bytes.
+
+    Sdk.AnalyticsTrack("level_done", new Dictionary<string, object> { ["level"] = 3 });
+
+    await Sdk.SavesPutAsync(bytes, ifVersion: version);
+}
+```
+
+Responses come back as JSON strings deliberately: your project already carries a
+JSON library, and a second one shipped in here would be a worse one.
+
+The full API — capabilities, save conflicts, error codes, the manifest — is
+documented in [`@squidhub/game-sdk`](https://www.npmjs.com/package/@squidhub/game-sdk).
+This package is a wrapper around it and shares its behaviour exactly.
+
+⚠️ **Handle `CONFLICT` on `SavesPutAsync`.** It is not an edge case — it is what
+happens whenever a player has your game open in two places, which is the
+situation cloud saves exist for. The server's copy rides along on the error so
+you can merge without a second round trip. The platform stores opaque bytes and
+cannot merge for you.
+
+## What happens when you build
+
+Nothing to configure. On a WebGL build this package:
+
+1. **Refuses the build** if it could not possibly run — pthreads enabled, the
+   `.jslib` not linked for WebGL, the bridge missing. Each of those otherwise
+   fails silently in a browser rather than loudly in the Editor.
+2. **Writes `squidhub-bridge.js`** into the output and injects it ahead of the
+   Unity loader.
+3. **Hoists every inline `<script>`** out of `index.html` into an external file.
+
+Step 3 is the one that matters. `squidhub-gamehost` serves
+`script-src 'self' 'wasm-unsafe-eval' blob:` with **no `'unsafe-inline'`**, and
+every stock Unity template inlines its bootstrap. Left alone, the page loads,
+all the markup is there, and nothing runs — the only signal is a CSP violation
+in the console. This is the single most common first-integration failure, and
+you should never see it.
+
+Then push the folder:
+
+```sh
+node src/cli.mjs push --game <slug> --dir <BuildFolder> --env=dev --verify
+```
+
+## In the Editor
+
+`Sdk` compiles on every platform and reports `Status() == "failed"` anywhere
+that is not a WebGL build — pressing Play does not throw.
+
+⚠️ **It never simulates a session.** There is no offline player, no fake save
+and no pretend balance, because a game built against a player who cannot exist
+gets its first honest answer from production. Your game must start when a
+platform call fails; treat every verb as something that can fail and keep a
+local fallback.
+
+Run **SquidHub > Check WebGL Settings** any time to audit the project without
+waiting for a build.
+
+## Player Settings
+
+The package checks these for you, but for reference:
+
+| Setting | Value | Why |
+|---|---|---|
+| Native C/C++ Multithreading | **off** | SquidHub's default tier is not cross-origin isolated, so `SharedArrayBuffer` does not exist. A pthreads build cannot start. Ask about the isolated tier if you genuinely need threads — it carries no ads |
+| Compression Format | Brotli | `squidhub-release` strips the `.br` suffix and records `Content-Encoding: br` in R2, so the browser decompresses natively |
+| Decompression Fallback | off | The header is already correct, so the bundled JS decompressor is dead weight |
+
+## Things that will otherwise bite
+
+⚠️ **Your game only works when the portal launches it.** The launch nonce
+arrives in the URL fragment (`#s=…`), so opening `index.html` directly, or
+reloading without the fragment, fails the handshake with `UNTRUSTED_EMBEDDER`.
+That is intended, not a bug to work around.
+
+⚠️ **No external resources, at all.** The CSP is `default-src 'self' blob:
+data:`. A CDN font, a remote texture or a third-party analytics snippet is
+blocked at load and shows up as a console error, not as a missing style.
+Everything must ship inside the build.
+
+⚠️ **Do not write your own rotate prompt or call `screen.orientation.lock()`.**
+Declare the orientations you support in your `manifest.json` and the portal
+draws the prompt outside your frame. Two prompts fight, and yours is the one the
+player sees first.
+
+⚠️ **The mute button is the portal's, but the muting happens in your frame.** A
+cross-origin iframe has no `muted` property, so the SDK interposes a gain node
+on your `AudioContext`. It works without you doing anything — but only because
+the bridge is injected ahead of the loader, which is why step 2 above is not
+merely tidy. Declare `"sound": true` in your manifest or no button appears.
+
+⚠️ **Editing `manifest.json` alone changes nothing.** It is excluded from the
+build hash, so a manifest-only re-upload registers no new version and your edit
+is discarded. Change a real file and rebuild.
+
+## ⚠️ Status
+
+**The Unity path has never been run against the platform.** The HTML rewriting
+is unit-tested, the bridge is covered by the SDK's own suite, and the C#
+compiles — but no Unity build has completed a handshake with the portal. The
+JavaScript and Godot paths are tested; this one is not. Expect to shake out
+problems, and tell us what you find.
+
+## Support
+
+Contact your SquidHub publisher representative.
+
+MIT licensed.

package/Runtime/Plugins/WebGL/SquidHub.jslib

@@ -0,0 +1,67 @@
+// GENERATED FILE — do not edit by hand.
+// Source: squidhub-contracts/schemas.json (protocol v1)
+// Regenerate: npm run generate
+//
+// Drop this in Assets/Plugins/WebGL/. Unity links [DllImport("__Internal")]
+// against it at build time; without it the C# wrapper does not resolve.
+//
+// ⚠️ Strings returned to C# must be allocated in the Emscripten heap, because
+// Unity frees them on the C# side. Returning a JS string hands over a pointer
+// into nothing.
+//
+// ⚠️ The result envelope is split HERE rather than in C#. A JSON parser is free
+// in JavaScript and would be a liability in a generated C# file, so the parts
+// cross as "ok\u001f<valueJson>" or "err\u001f<code>\u001f<message>".
+//
+// ⚠️ Every function using the $-prefixed helper must declare it in __deps.
+// Emscripten dead-strips JS-only library members otherwise, and the failure is
+// a ReferenceError at runtime in an exported build — not at build time.
+mergeInto(LibraryManager.library, {
+  SquidHubStatus__deps: ["$squidHubString"],
+  SquidHubStatus: function () {
+    return squidHubString(window.SquidHub ? window.SquidHub.status() : "failed");
+  },
+
+  SquidHubLastError__deps: ["$squidHubString"],
+  SquidHubLastError: function () {
+    return squidHubString(
+      window.SquidHub ? window.SquidHub.error() : "SquidHub bridge is not on the page",
+    );
+  },
+
+  SquidHubSession__deps: ["$squidHubString"],
+  SquidHubSession: function () {
+    return squidHubString(window.SquidHub ? window.SquidHub.session() : "");
+  },
+
+  SquidHubInvoke__deps: ["$squidHubString"],
+  SquidHubInvoke: function (verb, payload) {
+    return squidHubString(window.SquidHub.invoke(UTF8ToString(verb), UTF8ToString(payload)));
+  },
+
+  SquidHubNotify: function (verb, payload) {
+    if (window.SquidHub) window.SquidHub.notify(UTF8ToString(verb), UTF8ToString(payload));
+  },
+
+  SquidHubPoll__deps: ["$squidHubString"],
+  SquidHubPoll: function (id) {
+    var raw = window.SquidHub.poll(UTF8ToString(id));
+    if (!raw) return squidHubString("");
+    var res = JSON.parse(raw);
+    if (res.ok) return squidHubString("ok\u001f" + JSON.stringify(res.value === undefined ? null : res.value));
+    // ⚠️ The server's copy rides along on a save conflict and MUST cross with
+    // the error. Only the game can merge its own save format, so dropping it
+    // here left a Unity game with a CONFLICT it had no way to resolve — while
+    // the JS and Godot paths merged from the same envelope.
+    var parts = ["err", res.code || "PROTOCOL", res.message || "request failed"];
+    if (res.serverCopy !== undefined) parts.push(JSON.stringify(res.serverCopy));
+    return squidHubString(parts.join("\u001f"));
+  },
+
+  $squidHubString: function (str) {
+    var size = lengthBytesUTF8(str) + 1;
+    var buffer = _malloc(size);
+    stringToUTF8(str, buffer, size);
+    return buffer;
+  },
+});

package/Runtime/Plugins/WebGL/SquidHub.jslib.meta

@@ -0,0 +1,32 @@
+fileFormatVersion: 2
+guid: 2349bb197ece0d2ae59334e6a8c4e95a
+PluginImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  iconMap: {}
+  executionOrder: {}
+  defineConstraints: []
+  isPreloaded: 0
+  isOverridable: 0
+  isExplicitlyReferenced: 0
+  validateReferences: 1
+  platformData:
+  - first:
+      Any: 
+    second:
+      enabled: 0
+      settings: {}
+  - first:
+      Editor: Editor
+    second:
+      enabled: 0
+      settings:
+        DefaultValueInitialized: true
+  - first:
+      WebGL: WebGL
+    second:
+      enabled: 1
+      settings: {}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/Runtime/Plugins/WebGL.meta

@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: a94574f0b6c08e281912afc3b95bd222
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/Runtime/Plugins.meta

@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: 2a43955d02c22fdc8263b5ded54df53d
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/Runtime/RobotSquid.SquidHub.asmdef

@@ -0,0 +1,14 @@
+{
+    "name": "RobotSquid.SquidHub",
+    "rootNamespace": "SquidHub",
+    "references": [],
+    "includePlatforms": [],
+    "excludePlatforms": [],
+    "allowUnsafeCode": false,
+    "overrideReferences": false,
+    "precompiledReferences": [],
+    "autoReferenced": true,
+    "defineConstraints": [],
+    "versionDefines": [],
+    "noEngineReferences": false
+}

package/Runtime/RobotSquid.SquidHub.asmdef.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 964d39955ff854f50ad64738413b6546
+AssemblyDefinitionImporter:
+  externalObjects: {}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/Runtime/SquidHub.cs

@@ -0,0 +1,247 @@
+// GENERATED FILE — do not edit by hand.
+// Source: squidhub-contracts/schemas.json (protocol v1)
+// Regenerate: npm run generate
+//
+// Usage:
+//   await Sdk.WaitForReadyAsync();
+//   var json = await Sdk.SavesGetAsync();
+//
+// ⚠️ Requires SquidHub.jslib alongside it and a bundled entry script on the
+// page calling installBridge() from @squidhub/game-sdk. The wrapper does not
+// contain the protocol; it marshals to window.SquidHub. The
+// com.robotsquid.squidhub UPM package ships all three and wires the page up at
+// build time — prefer it to copying these files in by hand.
+//
+// ⚠️ Only the WebGL player can reach the bridge. This compiles everywhere —
+// see the stubs below — but reports "failed" off WebGL rather than pretending.
+// Build without pthreads: SharedArrayBuffer requires cross-origin isolation,
+// which SquidHub's default tier does not enable.
+//
+// ⚠️ UNVERIFIED. No Unity build exists in this workspace, so unlike the JS
+// bridge — which is covered by the SDK's own suite — this path has never been
+// run. Treat it as a starting point and cover it with an L4 run before
+// promising it to a publisher.
+//
+// Responses come back as JSON strings for the project's own JSON library to
+// read. Deliberate: Unity projects already carry one, and shipping a parser in
+// a generated file would be a second, worse parser to maintain.
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.Runtime.InteropServices;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace SquidHub
+{
+    public static class Sdk
+    {
+#if UNITY_WEBGL && !UNITY_EDITOR
+        [DllImport("__Internal")] private static extern string SquidHubStatus();
+        [DllImport("__Internal")] private static extern string SquidHubLastError();
+        [DllImport("__Internal")] private static extern string SquidHubSession();
+        [DllImport("__Internal")] private static extern string SquidHubInvoke(string verb, string payloadJson);
+        [DllImport("__Internal")] private static extern void SquidHubNotify(string verb, string payloadJson);
+        [DllImport("__Internal")] private static extern string SquidHubPoll(string id);
+#else
+        // ⚠️ Play mode, and every non-WebGL player, has no browser and no
+        // bridge. Without these stubs the DllImports above throw
+        // EntryPointNotFoundException the first time anyone presses Play, which
+        // reads as "the SDK is broken" rather than "there is no portal here".
+        //
+        // ⚠️ They report failure; they never simulate a session. A fake
+        // player would let a game be built against someone who cannot exist,
+        // and the first honest answer would arrive from production.
+        private const string NoBridge =
+            "SquidHub is only available in a WebGL build launched by the portal.";
+
+        private static string SquidHubStatus() => "failed";
+        private static string SquidHubLastError() => NoBridge;
+        private static string SquidHubSession() => "";
+        private static string SquidHubInvoke(string verb, string payloadJson) => "editor";
+        private static void SquidHubNotify(string verb, string payloadJson) { }
+
+        // ⚠️ Must be non-empty, or InvokeAsync spins forever on a poll that
+        // never settles. UNAVAILABLE is the contract code for "not served here".
+        private static string SquidHubPoll(string id) =>
+            "err\u001fUNAVAILABLE\u001f" + NoBridge;
+#endif
+
+        private const char Separator = '\u001f';
+
+        /// <summary>Handshake state: connecting, ready or failed.</summary>
+        public static string Status() => SquidHubStatus();
+
+        /// <summary>SessionView as JSON, or "" until the handshake completes.</summary>
+        public static string Session() => SquidHubSession();
+
+        /// <summary>Resolves when the portal handshake completes; throws if it is refused.</summary>
+        public static async Task WaitForReadyAsync()
+        {
+            while (true)
+            {
+                var state = SquidHubStatus();
+                if (state == "ready") return;
+                if (state == "failed") throw new SquidHubException(SquidHubLastError(), "UNTRUSTED_EMBEDDER");
+                await Task.Yield();
+            }
+        }
+
+        // ⚠️ Polled rather than awaited. The bridge is a JS promise; nothing on
+        // the C# side can await one, and a retained callback would have to
+        // survive a domain reload.
+        private static async Task<string> InvokeAsync(string verb, string payloadJson)
+        {
+            var id = SquidHubInvoke(verb, payloadJson);
+            while (true)
+            {
+                var raw = SquidHubPoll(id);
+                if (!string.IsNullOrEmpty(raw))
+                {
+                    // "ok<US><valueJson>", or
+                    // "err<US><code><US><message>[<US><serverCopyJson>]" — split
+                    // by the jslib so this side never parses JSON.
+                    //
+                    // ⚠️ Bounded at 4 so a message that somehow contained the
+                    // separator cannot shift the payload out of position.
+                    var parts = raw.Split(new[] { Separator }, 4, StringSplitOptions.None);
+                    if (parts[0] == "ok") return parts.Length > 1 ? parts[1] : "null";
+                    throw new SquidHubException(
+                        parts.Length > 2 ? parts[2] : "request failed",
+                        parts.Length > 1 ? parts[1] : "PROTOCOL",
+                        parts.Length > 3 ? parts[3] : null);
+                }
+                await Task.Yield();
+            }
+        }
+
+        /// <summary>Base64 for the crossing only — the platform still stores raw bytes.</summary>
+        private static string ToBase64(byte[] bytes) => Convert.ToBase64String(bytes ?? Array.Empty<byte>());
+
+        /// <summary>Decodes a base64 field out of a response.</summary>
+        public static byte[] FromBase64(string b64) =>
+            string.IsNullOrEmpty(b64) ? Array.Empty<byte>() : Convert.FromBase64String(b64);
+
+        /// <summary>saves.get — capability: saves</summary>
+        /// <remarks>Returns the response as JSON. <c>data</c> is base64 — decode with FromBase64.</remarks>
+        /// <exception cref="SquidHubException">The platform refused the call; Code carries the reason.</exception>
+        public static Task<string> SavesGetAsync()
+        {
+            var payload = new Dictionary<string, object>();
+            return InvokeAsync("saves.get", JsonWriter.Write(payload));
+        }
+
+        /// <summary>saves.put — capability: saves</summary>
+        /// <remarks>Returns the response as JSON, for the project's own JSON library to read.</remarks>
+        /// <exception cref="SquidHubException">The platform refused the call; Code carries the reason.</exception>
+        public static Task<string> SavesPutAsync(byte[] data, int? ifVersion = null)
+        {
+            var payload = new Dictionary<string, object>();
+            payload["data"] = ToBase64(data);
+            if (ifVersion != null) payload["ifVersion"] = ifVersion;
+            return InvokeAsync("saves.put", JsonWriter.Write(payload));
+        }
+
+        /// <summary>analytics.track — capability: analytics</summary>
+        /// <remarks>Fire-and-forget by contract: never reports a failure.</remarks>
+        public static void AnalyticsTrack(string name, Dictionary<string, object> props = null)
+        {
+            var payload = new Dictionary<string, object>();
+            payload["name"] = name;
+            if (props != null) payload["props"] = props;
+            SquidHubNotify("analytics.track", JsonWriter.Write(payload));
+        }
+
+        /// <summary>commerce.purchase — capability: commerce.spend</summary>
+        /// <remarks>Returns the response as JSON, for the project's own JSON library to read.</remarks>
+        /// <exception cref="SquidHubException">The platform refused the call; Code carries the reason.</exception>
+        public static Task<string> CommercePurchaseAsync(string sku, string idempotencyKey)
+        {
+            var payload = new Dictionary<string, object>();
+            payload["sku"] = sku;
+            payload["idempotencyKey"] = idempotencyKey;
+            return InvokeAsync("commerce.purchase", JsonWriter.Write(payload));
+        }
+    }
+
+    /// <summary>
+    /// Writes the flat payloads this contract defines — primitives, plus one
+    /// level of nesting for analytics props. ⚠️ Not a general JSON writer, and
+    /// deliberately so: anything richer belongs in the project's own library.
+    /// </summary>
+    internal static class JsonWriter
+    {
+        public static string Write(Dictionary<string, object> fields)
+        {
+            var sb = new StringBuilder("{");
+            var first = true;
+            foreach (var kv in fields)
+            {
+                if (!first) sb.Append(',');
+                first = false;
+                WriteString(sb, kv.Key);
+                sb.Append(':');
+                WriteValue(sb, kv.Value);
+            }
+            return sb.Append('}').ToString();
+        }
+
+        private static void WriteValue(StringBuilder sb, object value)
+        {
+            switch (value)
+            {
+                case null: sb.Append("null"); break;
+                case string s: WriteString(sb, s); break;
+                case bool b: sb.Append(b ? "true" : "false"); break;
+                case Dictionary<string, object> d: sb.Append(Write(d)); break;
+                case IFormattable n: sb.Append(n.ToString(null, CultureInfo.InvariantCulture)); break;
+                default: WriteString(sb, value.ToString()); break;
+            }
+        }
+
+        private static void WriteString(StringBuilder sb, string value)
+        {
+            sb.Append('"');
+            foreach (var c in value)
+            {
+                switch (c)
+                {
+                    case '"': sb.Append("\\\""); break;
+                    case '\\': sb.Append("\\\\"); break;
+                    case '\n': sb.Append("\\n"); break;
+                    case '\r': sb.Append("\\r"); break;
+                    case '\t': sb.Append("\\t"); break;
+                    default:
+                        if (c < ' ') sb.Append("\\u").Append(((int)c).ToString("x4", CultureInfo.InvariantCulture));
+                        else sb.Append(c);
+                        break;
+                }
+            }
+            sb.Append('"');
+        }
+    }
+
+    public class SquidHubException : Exception
+    {
+        /// <summary>Platform error code — RATE_LIMITED, CONFLICT, DENIED and so on.</summary>
+        public string Code { get; }
+
+        /// <summary>
+        /// On Code == "CONFLICT", the server's copy of the save as JSON —
+        /// <c>data</c> base64, alongside its <c>version</c>. Null otherwise.
+        /// </summary>
+        /// <remarks>
+        /// ⚠️ Merging is yours. The platform stores opaque bytes and cannot
+        /// merge for you, and a game that catches CONFLICT and writes anyway
+        /// loses a player's progress the first time they play on two devices.
+        /// </remarks>
+        public string ServerCopy { get; }
+
+        public SquidHubException(string message, string code = "PROTOCOL", string serverCopy = null)
+            : base(message)
+        {
+            Code = code;
+            ServerCopy = serverCopy;
+        }
+    }
+}

package/Runtime/SquidHub.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: b816cffd5d7a0b926d09277d3be3c3b7
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/Runtime.meta

@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: a9a0cec8749b770d981cb1859d6c53a5
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "com.robotsquid.squidhub",
+  "version": "0.5.0",
+  "displayName": "SquidHub",
+  "description": "Cloud saves, analytics and the coin economy for Unity WebGL games published on SquidHub. Installs the C# wrapper, the .jslib half and the page bridge, and rewrites the exported index.html so it survives the platform's CSP.",
+  "unity": "2021.3",
+  "license": "MIT",
+  "author": {
+    "name": "RobotSquid",
+    "url": "https://robotsquid.dev"
+  },
+  "keywords": [
+    "squidhub",
+    "webgl",
+    "sdk",
+    "games",
+    "cloud-saves"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RobotSquid/SquidHub.git",
+    "directory": "squidhub-unity"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "files": [
+    "Runtime",
+    "Runtime.meta",
+    "Editor",
+    "Editor.meta",
+    "Bridge~",
+    "CHANGELOG.md",
+    "LICENSE.md"
+  ],
+  "dependencies": {}
+}