claude-artifact-framework 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,96 @@
+# claude-artifact-framework
+
+Utilities for building apps inside Claude Artifacts: platform storage, reactive
+state, and other primitives verified against the real runtime. Zero
+dependencies, no build step — drop it into an artifact straight from a CDN.
+
+## Usage via CDN
+
+Everything is served through [jsDelivr](https://www.jsdelivr.com/), which
+mirrors npm packages automatically.
+
+### As a global script (`<script>` tag)
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.2.0/dist/index.global.js"></script>
+<script>
+  const { storage, createStore, createPersistedStore, createSharedStore } = ArtifactKit;
+</script>
+```
+
+### As an ES module
+
+```html
+<script type="module">
+  import {
+    storage,
+    createStore,
+    createPersistedStore,
+    createSharedStore,
+  } from "https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.2.0/dist/index.esm.js";
+</script>
+```
+
+Pin a version (`@0.2.0`) for reproducible artifacts, or drop the version
+(`claude-artifact-framework/dist/...`) to always get the latest release.
+
+## `storage`
+
+Thin wrapper over `window.storage`, the persistence API Claude injects into a
+**published** Chat Artifact. Values are JSON-serialized for you. Two scopes:
+personal (`storage.*`, one copy per viewer) and shared (`storage.shared.*`,
+one copy for every viewer of the artifact).
+
+```js
+await storage.set("theme", "dark");
+await storage.get("theme", "light"); // "dark" — second arg is the fallback
+await storage.list();                // ["theme", ...]
+await storage.delete("theme");
+
+await storage.shared.set("board", { count: 0 });
+await storage.shared.get("board", null);
+
+storage.available(); // false in draft mode / outside a Chat Artifact
+```
+
+## `createStore(initialState)`
+
+In-memory reactive store. No persistence.
+
+```js
+const counter = createStore(0);
+counter.subscribe((value) => console.log("count is now", value));
+counter.set((n) => n + 1);
+counter.get(); // 1
+```
+
+## `createPersistedStore(key, initialState, options?)`
+
+Same as `createStore`, but loads from `storage` once on creation and saves
+(debounced) on every change. Personal scope only.
+
+```js
+const prefs = createPersistedStore("prefs", { theme: "light" });
+await prefs.ready;           // resolves once the initial load finishes
+prefs.set({ theme: "dark" }); // persisted automatically
+```
+
+`options.debounceMs` (default `300`) controls how long to wait after the last
+change before writing to storage.
+
+## `createSharedStore(key, initialState, options?)`
+
+Same as `createPersistedStore`, but backed by `storage.shared` and polled on
+an interval, so every viewer of a published artifact converges on the same
+state.
+
+```js
+const board = createSharedStore("board", { count: 0 }, { pollMs: 2000 });
+await board.ready;
+board.set({ count: board.get().count + 1 }); // pushed to every viewer
+board.stop(); // stop polling, e.g. on teardown
+```
+
+Conflict handling is last-write-wins: if two viewers change the same key
+within one poll window, whichever write reaches storage last overwrites the
+other. There is no merge/CRDT logic.

package/dist/index.esm.js

@@ -47,7 +47,63 @@ function scope(shared) {
   };
 }
 var storage = { ...scope(false), shared: scope(true), available };
+
+// src/state.js
+function makeStore(initialState) {
+  let state = initialState;
+  const subscribers = /* @__PURE__ */ new Set();
+  function get() {
+    return state;
+  }
+  function set(next) {
+    state = typeof next === "function" ? next(state) : next;
+    subscribers.forEach((fn) => fn(state));
+  }
+  function subscribe(fn) {
+    subscribers.add(fn);
+    return () => subscribers.delete(fn);
+  }
+  return { get, set, subscribe };
+}
+function debounce(fn, ms) {
+  let timer;
+  return (...args) => {
+    clearTimeout(timer);
+    timer = setTimeout(() => fn(...args), ms);
+  };
+}
+function createStore(initialState) {
+  return makeStore(initialState);
+}
+function createPersistedStore(key, initialState, { debounceMs = 300 } = {}) {
+  const store = makeStore(initialState);
+  const persist = debounce((value) => storage.set(key, value), debounceMs);
+  const ready = storage.get(key, initialState).then((loaded) => store.set(loaded));
+  store.subscribe(persist);
+  return { ...store, ready };
+}
+function createSharedStore(key, initialState, { pollMs = 2e3, debounceMs = 300 } = {}) {
+  const store = makeStore(initialState);
+  const persist = debounce((value) => storage.shared.set(key, value), debounceMs);
+  let applyingRemote = false;
+  store.subscribe((value) => {
+    if (!applyingRemote) persist(value);
+  });
+  async function poll() {
+    const remote = await storage.shared.get(key, initialState);
+    if (JSON.stringify(remote) === JSON.stringify(store.get())) return;
+    applyingRemote = true;
+    store.set(remote);
+    applyingRemote = false;
+  }
+  const ready = poll();
+  const timer = setInterval(poll, pollMs);
+  return { ...store, ready, stop: () => clearInterval(timer) };
+}
 export {
+  createPersistedStore,
+  createSharedStore,
+  createStore,
   storage
 };
 //# sourceMappingURL=index.esm.js.map

package/dist/index.esm.js.map

@@ -1,7 +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;",
+  "sources": ["../src/storage.js", "../src/state.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", "// state.js \u2014 small reactive stores for artifact UI state, layered on storage.js.\n//\n// Three tiers, each a superset of the previous:\n//   createStore           in-memory only, no persistence\n//   createPersistedStore  loads from storage once, saves (debounced) on every\n//                         change \u2014 personal scope, single viewer\n//   createSharedStore     same, but polls storage.shared so every viewer of a\n//                         published artifact converges on the same state\n//\n// createSharedStore is last-write-wins with no merge: if two viewers change\n// the same key inside one poll window, whichever write lands last on the\n// server wins and the other is silently overwritten on the next poll. Fine\n// for \"everyone sees the same board/list\", not a CRDT.\n\nimport { storage } from \"./storage.js\";\n\nfunction makeStore(initialState) {\n  let state = initialState;\n  const subscribers = new Set();\n\n  function get() {\n    return state;\n  }\n\n  function set(next) {\n    state = typeof next === \"function\" ? next(state) : next;\n    subscribers.forEach((fn) => fn(state));\n  }\n\n  function subscribe(fn) {\n    subscribers.add(fn);\n    return () => subscribers.delete(fn);\n  }\n\n  return { get, set, subscribe };\n}\n\nfunction debounce(fn, ms) {\n  let timer;\n  return (...args) => {\n    clearTimeout(timer);\n    timer = setTimeout(() => fn(...args), ms);\n  };\n}\n\nexport function createStore(initialState) {\n  return makeStore(initialState);\n}\n\nexport function createPersistedStore(key, initialState, { debounceMs = 300 } = {}) {\n  const store = makeStore(initialState);\n  const persist = debounce((value) => storage.set(key, value), debounceMs);\n\n  const ready = storage.get(key, initialState).then((loaded) => store.set(loaded));\n  store.subscribe(persist);\n\n  return { ...store, ready };\n}\n\nexport function createSharedStore(key, initialState, { pollMs = 2000, debounceMs = 300 } = {}) {\n  const store = makeStore(initialState);\n  const persist = debounce((value) => storage.shared.set(key, value), debounceMs);\n  let applyingRemote = false;\n\n  store.subscribe((value) => {\n    if (!applyingRemote) persist(value);\n  });\n\n  async function poll() {\n    const remote = await storage.shared.get(key, initialState);\n    if (JSON.stringify(remote) === JSON.stringify(store.get())) return;\n    applyingRemote = true;\n    store.set(remote);\n    applyingRemote = false;\n  }\n\n  const ready = poll();\n  const timer = setInterval(poll, pollMs);\n\n  return { ...store, ready, stop: () => clearInterval(timer) };\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/index.global.js

@@ -1,2 +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);})();
+var ArtifactKit=(()=>{var d=Object.defineProperty;var m=Object.getOwnPropertyDescriptor;var v=Object.getOwnPropertyNames;var J=Object.prototype.hasOwnProperty;var N=(t,e)=>{for(var r in e)d(t,r,{get:e[r],enumerable:!0})},O=(t,e,r,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let o of v(e))!J.call(t,o)&&o!==r&&d(t,o,{get:()=>e[o],enumerable:!(n=m(e,o))||n.enumerable});return t};var x=t=>O(d({},"__esModule",{value:!0}),t);var E={};N(E,{createPersistedStore:()=>y,createSharedStore:()=>h,createStore:()=>p,storage:()=>a});function u(){return typeof window<"u"&&typeof window.storage=="object"&&window.storage!==null}function w(t){return{async get(e,r=void 0){if(!u())return r;try{let n=await window.storage.get(e,t);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(e,r,{raw:n=!1}={}){if(!u())throw new Error("window.storage is not available (is this a Code Artifact rather than a published Chat Artifact?)");let o=n?r:JSON.stringify(r);if(typeof o!="string")throw new Error("window.storage only accepts strings \u2014 the value must be JSON-serializable");return window.storage.set(e,o,t)},async delete(e){if(u())try{await window.storage.delete(e,t)}catch{}},async list(e){if(!u())return[];try{return(await window.storage.list(e,t))?.keys||[]}catch{return[]}}}}var a={...w(!1),shared:w(!0),available:u};function l(t){let e=t,r=new Set;function n(){return e}function o(s){e=typeof s=="function"?s(e):s,r.forEach(f=>f(e))}function c(s){return r.add(s),()=>r.delete(s)}return{get:n,set:o,subscribe:c}}function g(t,e){let r;return(...n)=>{clearTimeout(r),r=setTimeout(()=>t(...n),e)}}function p(t){return l(t)}function y(t,e,{debounceMs:r=300}={}){let n=l(e),o=g(s=>a.set(t,s),r),c=a.get(t,e).then(s=>n.set(s));return n.subscribe(o),{...n,ready:c}}function h(t,e,{pollMs:r=2e3,debounceMs:n=300}={}){let o=l(e),c=g(i=>a.shared.set(t,i),n),s=!1;o.subscribe(i=>{s||c(i)});async function f(){let i=await a.shared.get(t,e);JSON.stringify(i)!==JSON.stringify(o.get())&&(s=!0,o.set(i),s=!1)}let b=f(),S=setInterval(f,r);return{...o,ready:b,stop:()=>clearInterval(S)}}return x(E);})();
 //# sourceMappingURL=index.global.js.map

package/dist/index.global.js.map

@@ -1,7 +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"]
+  "sources": ["../src/index.js", "../src/storage.js", "../src/state.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\";\nexport { createStore, createPersistedStore, createSharedStore } from \"./state.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", "// state.js \u2014 small reactive stores for artifact UI state, layered on storage.js.\n//\n// Three tiers, each a superset of the previous:\n//   createStore           in-memory only, no persistence\n//   createPersistedStore  loads from storage once, saves (debounced) on every\n//                         change \u2014 personal scope, single viewer\n//   createSharedStore     same, but polls storage.shared so every viewer of a\n//                         published artifact converges on the same state\n//\n// createSharedStore is last-write-wins with no merge: if two viewers change\n// the same key inside one poll window, whichever write lands last on the\n// server wins and the other is silently overwritten on the next poll. Fine\n// for \"everyone sees the same board/list\", not a CRDT.\n\nimport { storage } from \"./storage.js\";\n\nfunction makeStore(initialState) {\n  let state = initialState;\n  const subscribers = new Set();\n\n  function get() {\n    return state;\n  }\n\n  function set(next) {\n    state = typeof next === \"function\" ? next(state) : next;\n    subscribers.forEach((fn) => fn(state));\n  }\n\n  function subscribe(fn) {\n    subscribers.add(fn);\n    return () => subscribers.delete(fn);\n  }\n\n  return { get, set, subscribe };\n}\n\nfunction debounce(fn, ms) {\n  let timer;\n  return (...args) => {\n    clearTimeout(timer);\n    timer = setTimeout(() => fn(...args), ms);\n  };\n}\n\nexport function createStore(initialState) {\n  return makeStore(initialState);\n}\n\nexport function createPersistedStore(key, initialState, { debounceMs = 300 } = {}) {\n  const store = makeStore(initialState);\n  const persist = debounce((value) => storage.set(key, value), debounceMs);\n\n  const ready = storage.get(key, initialState).then((loaded) => store.set(loaded));\n  store.subscribe(persist);\n\n  return { ...store, ready };\n}\n\nexport function createSharedStore(key, initialState, { pollMs = 2000, debounceMs = 300 } = {}) {\n  const store = makeStore(initialState);\n  const persist = debounce((value) => storage.shared.set(key, value), debounceMs);\n  let applyingRemote = false;\n\n  store.subscribe((value) => {\n    if (!applyingRemote) persist(value);\n  });\n\n  async function poll() {\n    const remote = await storage.shared.get(key, initialState);\n    if (JSON.stringify(remote) === JSON.stringify(store.get())) return;\n    applyingRemote = true;\n    store.set(remote);\n    applyingRemote = false;\n  }\n\n  const ready = poll();\n  const timer = setInterval(poll, pollMs);\n\n  return { ...store, ready, stop: () => clearInterval(timer) };\n}\n"],
+  "mappings": "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",
+  "names": ["index_exports", "__export", "createPersistedStore", "createSharedStore", "createStore", "storage", "available", "scope", "shared", "key", "fallback", "res", "value", "raw", "payload", "prefix", "storage", "makeStore", "initialState", "state", "subscribers", "get", "set", "next", "fn", "subscribe", "debounce", "ms", "timer", "args", "createStore", "createPersistedStore", "key", "debounceMs", "store", "persist", "value", "storage", "ready", "loaded", "createSharedStore", "pollMs", "applyingRemote", "poll", "remote"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-artifact-framework",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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",

package/src/index.js

@@ -3,3 +3,4 @@
 // config, no separate entry points, both dist bundles pick it up automatically.
 
 export { storage } from "./storage.js";
+export { createStore, createPersistedStore, createSharedStore } from "./state.js";

package/src/state.js

@@ -0,0 +1,81 @@
+// state.js — small reactive stores for artifact UI state, layered on storage.js.
+//
+// Three tiers, each a superset of the previous:
+//   createStore           in-memory only, no persistence
+//   createPersistedStore  loads from storage once, saves (debounced) on every
+//                         change — personal scope, single viewer
+//   createSharedStore     same, but polls storage.shared so every viewer of a
+//                         published artifact converges on the same state
+//
+// createSharedStore is last-write-wins with no merge: if two viewers change
+// the same key inside one poll window, whichever write lands last on the
+// server wins and the other is silently overwritten on the next poll. Fine
+// for "everyone sees the same board/list", not a CRDT.
+
+import { storage } from "./storage.js";
+
+function makeStore(initialState) {
+  let state = initialState;
+  const subscribers = new Set();
+
+  function get() {
+    return state;
+  }
+
+  function set(next) {
+    state = typeof next === "function" ? next(state) : next;
+    subscribers.forEach((fn) => fn(state));
+  }
+
+  function subscribe(fn) {
+    subscribers.add(fn);
+    return () => subscribers.delete(fn);
+  }
+
+  return { get, set, subscribe };
+}
+
+function debounce(fn, ms) {
+  let timer;
+  return (...args) => {
+    clearTimeout(timer);
+    timer = setTimeout(() => fn(...args), ms);
+  };
+}
+
+export function createStore(initialState) {
+  return makeStore(initialState);
+}
+
+export function createPersistedStore(key, initialState, { debounceMs = 300 } = {}) {
+  const store = makeStore(initialState);
+  const persist = debounce((value) => storage.set(key, value), debounceMs);
+
+  const ready = storage.get(key, initialState).then((loaded) => store.set(loaded));
+  store.subscribe(persist);
+
+  return { ...store, ready };
+}
+
+export function createSharedStore(key, initialState, { pollMs = 2000, debounceMs = 300 } = {}) {
+  const store = makeStore(initialState);
+  const persist = debounce((value) => storage.shared.set(key, value), debounceMs);
+  let applyingRemote = false;
+
+  store.subscribe((value) => {
+    if (!applyingRemote) persist(value);
+  });
+
+  async function poll() {
+    const remote = await storage.shared.get(key, initialState);
+    if (JSON.stringify(remote) === JSON.stringify(store.get())) return;
+    applyingRemote = true;
+    store.set(remote);
+    applyingRemote = false;
+  }
+
+  const ready = poll();
+  const timer = setInterval(poll, pollMs);
+
+  return { ...store, ready, stop: () => clearInterval(timer) };
+}