claude-artifact-framework 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alejandro Cuartas
+
+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/dist/index.esm.js

@@ -0,0 +1,53 @@
+// src/storage.js
+function available() {
+  return typeof window !== "undefined" && typeof window.storage === "object" && window.storage !== null;
+}
+function scope(shared) {
+  return {
+    async get(key, fallback = void 0) {
+      if (!available()) return fallback;
+      try {
+        const res = await window.storage.get(key, shared);
+        if (res?.value === void 0 || res?.value === null) return fallback;
+        try {
+          return JSON.parse(res.value);
+        } catch {
+          return res.value;
+        }
+      } catch {
+        return fallback;
+      }
+    },
+    async set(key, value, { raw = false } = {}) {
+      if (!available()) {
+        throw new Error("window.storage is not available (is this a Code Artifact rather than a published Chat Artifact?)");
+      }
+      const payload = raw ? value : JSON.stringify(value);
+      if (typeof payload !== "string") {
+        throw new Error("window.storage only accepts strings \u2014 the value must be JSON-serializable");
+      }
+      return window.storage.set(key, payload, shared);
+    },
+    async delete(key) {
+      if (!available()) return;
+      try {
+        await window.storage.delete(key, shared);
+      } catch {
+      }
+    },
+    async list(prefix) {
+      if (!available()) return [];
+      try {
+        const res = await window.storage.list(prefix, shared);
+        return res?.keys || [];
+      } catch {
+        return [];
+      }
+    }
+  };
+}
+var storage = { ...scope(false), shared: scope(true), available };
+export {
+  storage
+};
+//# sourceMappingURL=index.esm.js.map

package/dist/index.esm.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/storage.js"],
+  "sourcesContent": ["// storage.js \u2014 wrapper over window.storage (Chat Artifacts, published only).\n//\n// Verified empirically against the real runtime: get/set/delete/list all\n// take (key, shared = false) and return a Promise resolving to\n// { key, value, shared, \"@type\": \"...StorageXResponse\" }. Confirmed:\n//   - values must be strings (a raw object throws \"Invalid payload content\")\n//   - shared=true/false is a real, working scope switch\n//   - failures (including \"key not found\") all throw the same generic\n//     message with no distinguishing `code` \u2014 there is no reliable way to\n//     tell \"empty\" from \"backend error\" from the error alone.\n\nfunction available() {\n  return typeof window !== \"undefined\" && typeof window.storage === \"object\" && window.storage !== null;\n}\n\nfunction scope(shared) {\n  return {\n    async get(key, fallback = undefined) {\n      if (!available()) return fallback;\n      try {\n        const res = await window.storage.get(key, shared);\n        if (res?.value === undefined || res?.value === null) return fallback;\n        try {\n          return JSON.parse(res.value);\n        } catch {\n          return res.value; // not JSON \u2014 a plain string written via set(key, value, { raw: true })\n        }\n      } catch {\n        // See file header: this same catch fires for \"key does not exist\"\n        // and for a real backend failure. Treating both as \"no value\" is\n        // the safer default for a read path, at the cost of hiding outages.\n        return fallback;\n      }\n    },\n\n    async set(key, value, { raw = false } = {}) {\n      if (!available()) {\n        throw new Error(\"window.storage is not available (is this a Code Artifact rather than a published Chat Artifact?)\");\n      }\n      const payload = raw ? value : JSON.stringify(value);\n      if (typeof payload !== \"string\") {\n        throw new Error(\"window.storage only accepts strings \u2014 the value must be JSON-serializable\");\n      }\n      return window.storage.set(key, payload, shared);\n    },\n\n    async delete(key) {\n      if (!available()) return;\n      try {\n        await window.storage.delete(key, shared);\n      } catch {\n        // same ambiguity as get() \u2014 silently a no-op if the key never existed\n      }\n    },\n\n    async list(prefix) {\n      if (!available()) return [];\n      try {\n        const res = await window.storage.list(prefix, shared);\n        return res?.keys || [];\n      } catch {\n        return [];\n      }\n    },\n  };\n}\n\n// storage.get/set/delete/list operate on the per-viewer (personal) scope.\n// storage.shared.* are the same four methods against the shared scope, where\n// every viewer of the artifact reads and writes the same state.\nexport const storage = { ...scope(false), shared: scope(true), available };\n"],
+  "mappings": ";AAWA,SAAS,YAAY;AACnB,SAAO,OAAO,WAAW,eAAe,OAAO,OAAO,YAAY,YAAY,OAAO,YAAY;AACnG;AAEA,SAAS,MAAM,QAAQ;AACrB,SAAO;AAAA,IACL,MAAM,IAAI,KAAK,WAAW,QAAW;AACnC,UAAI,CAAC,UAAU,EAAG,QAAO;AACzB,UAAI;AACF,cAAM,MAAM,MAAM,OAAO,QAAQ,IAAI,KAAK,MAAM;AAChD,YAAI,KAAK,UAAU,UAAa,KAAK,UAAU,KAAM,QAAO;AAC5D,YAAI;AACF,iBAAO,KAAK,MAAM,IAAI,KAAK;AAAA,QAC7B,QAAQ;AACN,iBAAO,IAAI;AAAA,QACb;AAAA,MACF,QAAQ;AAIN,eAAO;AAAA,MACT;AAAA,IACF;AAAA,IAEA,MAAM,IAAI,KAAK,OAAO,EAAE,MAAM,MAAM,IAAI,CAAC,GAAG;AAC1C,UAAI,CAAC,UAAU,GAAG;AAChB,cAAM,IAAI,MAAM,kGAAkG;AAAA,MACpH;AACA,YAAM,UAAU,MAAM,QAAQ,KAAK,UAAU,KAAK;AAClD,UAAI,OAAO,YAAY,UAAU;AAC/B,cAAM,IAAI,MAAM,gFAA2E;AAAA,MAC7F;AACA,aAAO,OAAO,QAAQ,IAAI,KAAK,SAAS,MAAM;AAAA,IAChD;AAAA,IAEA,MAAM,OAAO,KAAK;AAChB,UAAI,CAAC,UAAU,EAAG;AAClB,UAAI;AACF,cAAM,OAAO,QAAQ,OAAO,KAAK,MAAM;AAAA,MACzC,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,IAEA,MAAM,KAAK,QAAQ;AACjB,UAAI,CAAC,UAAU,EAAG,QAAO,CAAC;AAC1B,UAAI;AACF,cAAM,MAAM,MAAM,OAAO,QAAQ,KAAK,QAAQ,MAAM;AACpD,eAAO,KAAK,QAAQ,CAAC;AAAA,MACvB,QAAQ;AACN,eAAO,CAAC;AAAA,MACV;AAAA,IACF;AAAA,EACF;AACF;AAKO,IAAM,UAAU,EAAE,GAAG,MAAM,KAAK,GAAG,QAAQ,MAAM,IAAI,GAAG,UAAU;",
+  "names": []
+}

package/dist/index.global.js

@@ -0,0 +1,2 @@
+var ArtifactKit=(()=>{var i=Object.defineProperty;var w=Object.getOwnPropertyDescriptor;var c=Object.getOwnPropertyNames;var l=Object.prototype.hasOwnProperty;var d=(e,t)=>{for(var r in t)i(e,r,{get:t[r],enumerable:!0})},f=(e,t,r,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let a of c(t))!l.call(e,a)&&a!==r&&i(e,a,{get:()=>t[a],enumerable:!(n=w(t,a))||n.enumerable});return e};var g=e=>f(i({},"__esModule",{value:!0}),e);var y={};d(y,{storage:()=>u});function o(){return typeof window<"u"&&typeof window.storage=="object"&&window.storage!==null}function s(e){return{async get(t,r=void 0){if(!o())return r;try{let n=await window.storage.get(t,e);if(n?.value===void 0||n?.value===null)return r;try{return JSON.parse(n.value)}catch{return n.value}}catch{return r}},async set(t,r,{raw:n=!1}={}){if(!o())throw new Error("window.storage is not available (is this a Code Artifact rather than a published Chat Artifact?)");let a=n?r:JSON.stringify(r);if(typeof a!="string")throw new Error("window.storage only accepts strings \u2014 the value must be JSON-serializable");return window.storage.set(t,a,e)},async delete(t){if(o())try{await window.storage.delete(t,e)}catch{}},async list(t){if(!o())return[];try{return(await window.storage.list(t,e))?.keys||[]}catch{return[]}}}}var u={...s(!1),shared:s(!0),available:o};return g(y);})();
+//# sourceMappingURL=index.global.js.map

package/dist/index.global.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.js", "../src/storage.js"],
+  "sourcesContent": ["// Barrel file \u2014 every module lives in its own src/<name>.js and gets one\n// export line here. Nothing else needs to change to add a module: no build\n// config, no separate entry points, both dist bundles pick it up automatically.\n\nexport { storage } from \"./storage.js\";\n", "// storage.js \u2014 wrapper over window.storage (Chat Artifacts, published only).\n//\n// Verified empirically against the real runtime: get/set/delete/list all\n// take (key, shared = false) and return a Promise resolving to\n// { key, value, shared, \"@type\": \"...StorageXResponse\" }. Confirmed:\n//   - values must be strings (a raw object throws \"Invalid payload content\")\n//   - shared=true/false is a real, working scope switch\n//   - failures (including \"key not found\") all throw the same generic\n//     message with no distinguishing `code` \u2014 there is no reliable way to\n//     tell \"empty\" from \"backend error\" from the error alone.\n\nfunction available() {\n  return typeof window !== \"undefined\" && typeof window.storage === \"object\" && window.storage !== null;\n}\n\nfunction scope(shared) {\n  return {\n    async get(key, fallback = undefined) {\n      if (!available()) return fallback;\n      try {\n        const res = await window.storage.get(key, shared);\n        if (res?.value === undefined || res?.value === null) return fallback;\n        try {\n          return JSON.parse(res.value);\n        } catch {\n          return res.value; // not JSON \u2014 a plain string written via set(key, value, { raw: true })\n        }\n      } catch {\n        // See file header: this same catch fires for \"key does not exist\"\n        // and for a real backend failure. Treating both as \"no value\" is\n        // the safer default for a read path, at the cost of hiding outages.\n        return fallback;\n      }\n    },\n\n    async set(key, value, { raw = false } = {}) {\n      if (!available()) {\n        throw new Error(\"window.storage is not available (is this a Code Artifact rather than a published Chat Artifact?)\");\n      }\n      const payload = raw ? value : JSON.stringify(value);\n      if (typeof payload !== \"string\") {\n        throw new Error(\"window.storage only accepts strings \u2014 the value must be JSON-serializable\");\n      }\n      return window.storage.set(key, payload, shared);\n    },\n\n    async delete(key) {\n      if (!available()) return;\n      try {\n        await window.storage.delete(key, shared);\n      } catch {\n        // same ambiguity as get() \u2014 silently a no-op if the key never existed\n      }\n    },\n\n    async list(prefix) {\n      if (!available()) return [];\n      try {\n        const res = await window.storage.list(prefix, shared);\n        return res?.keys || [];\n      } catch {\n        return [];\n      }\n    },\n  };\n}\n\n// storage.get/set/delete/list operate on the per-viewer (personal) scope.\n// storage.shared.* are the same four methods against the shared scope, where\n// every viewer of the artifact reads and writes the same state.\nexport const storage = { ...scope(false), shared: scope(true), available };\n"],
+  "mappings": "kbAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,aAAAE,ICWA,SAASC,GAAY,CACnB,OAAO,OAAO,OAAW,KAAe,OAAO,OAAO,SAAY,UAAY,OAAO,UAAY,IACnG,CAEA,SAASC,EAAMC,EAAQ,CACrB,MAAO,CACL,MAAM,IAAIC,EAAKC,EAAW,OAAW,CACnC,GAAI,CAACJ,EAAU,EAAG,OAAOI,EACzB,GAAI,CACF,IAAMC,EAAM,MAAM,OAAO,QAAQ,IAAIF,EAAKD,CAAM,EAChD,GAAIG,GAAK,QAAU,QAAaA,GAAK,QAAU,KAAM,OAAOD,EAC5D,GAAI,CACF,OAAO,KAAK,MAAMC,EAAI,KAAK,CAC7B,MAAQ,CACN,OAAOA,EAAI,KACb,CACF,MAAQ,CAIN,OAAOD,CACT,CACF,EAEA,MAAM,IAAID,EAAKG,EAAO,CAAE,IAAAC,EAAM,EAAM,EAAI,CAAC,EAAG,CAC1C,GAAI,CAACP,EAAU,EACb,MAAM,IAAI,MAAM,kGAAkG,EAEpH,IAAMQ,EAAUD,EAAMD,EAAQ,KAAK,UAAUA,CAAK,EAClD,GAAI,OAAOE,GAAY,SACrB,MAAM,IAAI,MAAM,gFAA2E,EAE7F,OAAO,OAAO,QAAQ,IAAIL,EAAKK,EAASN,CAAM,CAChD,EAEA,MAAM,OAAOC,EAAK,CAChB,GAAKH,EAAU,EACf,GAAI,CACF,MAAM,OAAO,QAAQ,OAAOG,EAAKD,CAAM,CACzC,MAAQ,CAER,CACF,EAEA,MAAM,KAAKO,EAAQ,CACjB,GAAI,CAACT,EAAU,EAAG,MAAO,CAAC,EAC1B,GAAI,CAEF,OADY,MAAM,OAAO,QAAQ,KAAKS,EAAQP,CAAM,IACxC,MAAQ,CAAC,CACvB,MAAQ,CACN,MAAO,CAAC,CACV,CACF,CACF,CACF,CAKO,IAAMQ,EAAU,CAAE,GAAGT,EAAM,EAAK,EAAG,OAAQA,EAAM,EAAI,EAAG,UAAAD,CAAU",
+  "names": ["index_exports", "__export", "storage", "available", "scope", "shared", "key", "fallback", "res", "value", "raw", "payload", "prefix", "storage"]
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "claude-artifact-framework",
+  "version": "0.1.0",
+  "description": "Utilities for building apps inside Claude Artifacts: platform storage, chat tool-calling loops, and other primitives verified against the real runtime.",
+  "type": "module",
+  "main": "./dist/index.esm.js",
+  "module": "./dist/index.esm.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.esm.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "build:watch": "node scripts/build.mjs --watch",
+    "prepublishOnly": "npm run build",
+    "release": "bash scripts/publish.sh"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0"
+  },
+  "license": "MIT",
+  "author": "Alejandro Cuartas",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alejoair/claude-artifact-framework.git"
+  }
+}

package/src/index.js

@@ -0,0 +1,5 @@
+// Barrel file — every module lives in its own src/<name>.js and gets one
+// export line here. Nothing else needs to change to add a module: no build
+// config, no separate entry points, both dist bundles pick it up automatically.
+
+export { storage } from "./storage.js";

package/src/storage.js

@@ -0,0 +1,71 @@
+// storage.js — wrapper over window.storage (Chat Artifacts, published only).
+//
+// Verified empirically against the real runtime: get/set/delete/list all
+// take (key, shared = false) and return a Promise resolving to
+// { key, value, shared, "@type": "...StorageXResponse" }. Confirmed:
+//   - values must be strings (a raw object throws "Invalid payload content")
+//   - shared=true/false is a real, working scope switch
+//   - failures (including "key not found") all throw the same generic
+//     message with no distinguishing `code` — there is no reliable way to
+//     tell "empty" from "backend error" from the error alone.
+
+function available() {
+  return typeof window !== "undefined" && typeof window.storage === "object" && window.storage !== null;
+}
+
+function scope(shared) {
+  return {
+    async get(key, fallback = undefined) {
+      if (!available()) return fallback;
+      try {
+        const res = await window.storage.get(key, shared);
+        if (res?.value === undefined || res?.value === null) return fallback;
+        try {
+          return JSON.parse(res.value);
+        } catch {
+          return res.value; // not JSON — a plain string written via set(key, value, { raw: true })
+        }
+      } catch {
+        // See file header: this same catch fires for "key does not exist"
+        // and for a real backend failure. Treating both as "no value" is
+        // the safer default for a read path, at the cost of hiding outages.
+        return fallback;
+      }
+    },
+
+    async set(key, value, { raw = false } = {}) {
+      if (!available()) {
+        throw new Error("window.storage is not available (is this a Code Artifact rather than a published Chat Artifact?)");
+      }
+      const payload = raw ? value : JSON.stringify(value);
+      if (typeof payload !== "string") {
+        throw new Error("window.storage only accepts strings — the value must be JSON-serializable");
+      }
+      return window.storage.set(key, payload, shared);
+    },
+
+    async delete(key) {
+      if (!available()) return;
+      try {
+        await window.storage.delete(key, shared);
+      } catch {
+        // same ambiguity as get() — silently a no-op if the key never existed
+      }
+    },
+
+    async list(prefix) {
+      if (!available()) return [];
+      try {
+        const res = await window.storage.list(prefix, shared);
+        return res?.keys || [];
+      } catch {
+        return [];
+      }
+    },
+  };
+}
+
+// storage.get/set/delete/list operate on the per-viewer (personal) scope.
+// storage.shared.* are the same four methods against the shared scope, where
+// every viewer of the artifact reads and writes the same state.
+export const storage = { ...scope(false), shared: scope(true), available };