claude-artifact-framework 0.2.0 → 0.3.0

package/README.md

@@ -0,0 +1,185 @@
+# 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.3.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.3.0/dist/index.esm.js";
+</script>
+```
+
+Pin a version (`@0.3.0`) for reproducible artifacts, or drop the version
+(`claude-artifact-framework/dist/...`) to always get the latest release.
+
+### Inside a React artifact
+
+A React artifact loads external code the same way any artifact does — by
+injecting a classic `<script>` tag, not by importing a module URL. Hand the
+framework the React the artifact already imported, so there is only ever one
+React on the page:
+
+```jsx
+import React, { useState, useEffect } from "react";
+
+const KIT = "https://cdn.jsdelivr.net/npm/claude-artifact-framework/dist/index.global.js";
+
+function load(src) {
+  return new Promise((resolve, reject) => {
+    if (document.querySelector(`script[src="${src}"]`)) return resolve();
+    const tag = document.createElement("script");
+    tag.src = src;
+    tag.onload = resolve;
+    tag.onerror = reject;
+    document.head.appendChild(tag);
+  });
+}
+
+export default function Artifact() {
+  const [App, setApp] = useState(null);
+
+  useEffect(() => {
+    load(KIT).then(() => {
+      ArtifactKit.useReact(React);
+      setApp(() => ArtifactKit.createApp({
+        title: "Mortgage calculator",
+        theme: { seed: "#0c8b8d" },
+        blocks: [
+          { fields: [
+            { key: "amount", label: "Amount",   type: "money",   value: 300000 },
+            { key: "rate",   label: "Rate",     type: "percent", value: 5.5 },
+            { key: "years",  label: "Term",     type: "number",  value: 30, min: 1, max: 40 },
+          ]},
+          { output: (d) => {
+            const i = d.rate / 100 / 12, n = d.years * 12;
+            const payment = d.amount * i / (1 - Math.pow(1 + i, -n));
+            return [{ label: "Monthly payment", value: payment, format: "money", big: true }];
+          }},
+        ],
+      }));
+    });
+  }, []);
+
+  return App ? <App /> : null;
+}
+```
+
+`useReact` is the one thing the framework asks for, and only because a runtime
+may keep React in a private module registry the bundle can't reach. If React is
+already on `globalThis`, it is picked up automatically and the call is a no-op.
+
+### The `records` layout — a full CRUD app from a declaration
+
+For "list of things" apps (expenses, habits, notes, todos), declare what a
+record is and the whole lifecycle — list, add, edit, delete, empty state,
+selection, persistence — is framework-owned:
+
+```js
+ArtifactKit.createApp({
+  title: "Gastos",
+  theme: { seed: "#c2410c" },
+  layout: "records",
+  records: {
+    label: "expense",
+    fields: [
+      { key: "concepto",  label: "Concepto",  type: "text", required: true },
+      { key: "monto",     label: "Monto",     type: "money", value: 0, min: 0 },
+      { key: "categoria", label: "Categoría", type: "select", options: ["comida", "transporte", "otros"] },
+    ],
+    subtitle: (r) => r.categoria || "sin categoría",
+    summary: (all) => [
+      { label: "Total",  value: all.reduce((s, r) => s + (Number(r.monto) || 0), 0), format: "money", big: true },
+      { label: "Gastos", value: all.length, format: "number" },
+    ],
+  },
+});
+```
+
+"Add" creates the record from field defaults and opens it (no draft object to
+lose); detail fields edit the record in place through the same debounced
+persistence path as everything else. `id` is assigned by the framework and
+reserved. Optional: `title(r)` / `subtitle(r)` for rows, `sort(a, b)`,
+`summary(records)` for stats above the list, `empty` for the empty-state text.
+
+## `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.