claude-artifact-framework 0.8.0 → 0.8.1

package/README.md

@@ -20,7 +20,7 @@ mirrors npm packages automatically.
 ### As a global script (`<script>` tag)
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.8.0/dist/index.global.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.8.1/dist/index.global.js"></script>
 <script>
   ArtifactKit.useReact(React); // hand over the page's React once
   const App = ArtifactKit.createApp({ title: "Mi app", blocks: [ /* ... */ ] });
@@ -38,11 +38,11 @@ mirrors npm packages automatically.
     createStore,
     createPersistedStore,
     createSharedStore,
-  } from "https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.8.0/dist/index.esm.js";
+  } from "https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.8.1/dist/index.esm.js";
 </script>
 ```
 
-Pin a version (`@0.8.0`) for reproducible artifacts, or drop the version
+Pin a version (`@0.8.1`) for reproducible artifacts, or drop the version
 (`claude-artifact-framework/dist/...`) to always get the latest release.
 
 ### Inside a React artifact
@@ -436,6 +436,59 @@ records: {
 }
 ```
 
+### Writing `custom` blocks that work
+
+`custom: (ctx) => ...` runs **during React render**. The rules below come
+from measured failures — each one is a way a model has actually broken a
+custom block:
+
+- **Return a string or a React element — never a DOM element.**
+  `document.createElement(...)` as a return value is not renderable (React
+  error #31, contained in the block). To use a library that *writes into*
+  an element (QRCode, pdf.js, chart libs), give it a ref:
+
+```js
+custom: (ctx) => {
+  const ref = React.useRef(null);
+  React.useEffect(() => {
+    if (!ref.current || !ctx.data.texto) return;
+    ref.current.innerHTML = "";
+    new QRCode(ref.current, { text: ctx.data.texto, width: 220, height: 220 });
+  }, [ctx.data.texto]);
+  return React.createElement("div", { ref });
+}
+```
+
+- **React hooks are allowed** inside custom (`React.useState`,
+  `React.useEffect`, `React.useRef`) — it runs in a component's render, and
+  `React` is available as a global.
+- **State has exactly two homes.** Persistent or visible to other blocks →
+  `ctx.update((d) => { d.x = ... })` (the whole app re-renders and it's
+  saved). Ephemeral UI state → `React.useState`. **Never `createStore` for
+  UI state** — stores do not re-render the app; a parse result stored there
+  will compute correctly and never appear on screen.
+- **Async work over an uploaded file**: an effect keyed on the file, local
+  state for the result:
+
+```js
+custom: (ctx) => {
+  const file = ctx.files.archivo;
+  const [rows, setRows] = React.useState(null);
+  React.useEffect(() => {
+    if (!file) { setRows(null); return; }
+    file.text().then((t) => setRows(t.trim().split("\n").map((l) => l.split(","))));
+  }, [file]);
+  if (!file) return "Subí un archivo para analizarlo.";
+  if (!rows) return "Analizando…";
+  return React.createElement(/* tu tabla */);
+}
+```
+
+- Custom re-renders whenever `data` or `view` change; it receives the full
+  `ctx` (`data`, `update`, `view`, `files`, `viewerId`, `colors`, `go`,
+  `back`) and lives inside the block error boundary — a bug in your custom
+  code shows a named error in its slot, never a blank app.
+
 ## API reference
 
 Everything an app can declare, in one place.

package/package.json

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