camox 0.44.0 → 0.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "camox",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "license": "MIT",
   "bin": {
     "camox": "./bin/camox.mjs"
@@ -12,6 +12,10 @@
   ],
   "type": "module",
   "exports": {
+    "./createCollection": {
+      "types": "./dist/core/createCollection.d.ts",
+      "import": "./dist/core/createCollection.js"
+    },
     "./dom": {
       "types": "./dist/core/dom.d.ts",
       "import": "./dist/core/dom.js"
@@ -56,10 +60,6 @@
       "types": "./dist/features/vite/vite.d.ts",
       "import": "./dist/features/vite/vite.js"
     },
-    "./metadata": {
-      "types": "./dist/features/metadata/sitemap.d.ts",
-      "import": "./dist/features/metadata/sitemap.js"
-    },
     "./_internal/pageServer": {
       "types": "./dist/features/runtime/pageServer.d.ts",
       "import": "./dist/features/runtime/pageServer.js"
@@ -81,87 +81,76 @@
       "import": "./dist/features/runtime/runtime.js"
     },
     "./_internal/imageResponse": {
-      "workerd": {
-        "types": "./dist/features/og/imageResponse.workerd.d.ts",
-        "import": "./dist/features/og/imageResponse.workerd.js"
-      },
-      "worker": {
-        "types": "./dist/features/og/imageResponse.workerd.d.ts",
-        "import": "./dist/features/og/imageResponse.workerd.js"
-      },
-      "deno": {
-        "types": "./dist/features/og/imageResponse.workerd.d.ts",
-        "import": "./dist/features/og/imageResponse.workerd.js"
-      },
-      "default": {
-        "types": "./dist/features/og/imageResponse.node.d.ts",
-        "import": "./dist/features/og/imageResponse.node.js"
-      }
+      "types": "./dist/features/og/imageResponse.d.ts",
+      "import": "./dist/features/og/imageResponse.js"
+    },
+    "./worker": {
+      "types": "./dist/features/runtime/worker.d.ts",
+      "import": "./dist/features/runtime/worker.js"
     },
     "./studio.css": "./dist/studio.css"
   },
   "dependencies": {
-    "@base-ui/react": "^1.4.1",
+    "@base-ui/react": "^1.9.0",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/modifiers": "^9.0.0",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
-    "@lexical/link": "^0.41.0",
-    "@lexical/markdown": "^0.41.0",
-    "@lexical/react": "^0.41.0",
-    "@lexical/rich-text": "^0.41.0",
-    "@orpc/client": "^1.14.3",
-    "@orpc/tanstack-query": "^1.14.3",
-    "@shikijs/core": "^4.1.0",
-    "@shikijs/engine-javascript": "^4.1.0",
-    "@shikijs/langs": "^4.1.0",
-    "@shikijs/themes": "^4.1.0",
-    "@sinclair/typebox": "^0.34.49",
-    "@takumi-rs/image-response": "^0.70.4",
-    "@takumi-rs/wasm": "^0.70.4",
-    "@tanstack/react-form": "^1.32.0",
-    "@tanstack/react-query-devtools": "^5.100.11",
-    "@tanstack/react-virtual": "^3.14.13",
-    "@unhead/react": "^3.1.7",
-    "@xstate/store": "3.17.1",
-    "@xstate/store-react": "^1.0.1",
-    "better-auth": "^1.6.11",
-    "fractional-indexing": "^3.2.0",
-    "hono": "^4.12.19",
-    "lexical": "^0.41.0",
-    "lucide-react": "^0.476.0",
-    "marked": "^18.0.13",
-    "partysocket": "^1.1.19",
-    "react": "^19.2.6",
+    "@lexical/link": "^0.52.0",
+    "@lexical/markdown": "^0.52.0",
+    "@lexical/react": "^0.52.0",
+    "@lexical/rich-text": "^0.52.0",
+    "@lexical/utils": "^0.52.0",
+    "@orpc/client": "^1.15.7",
+    "@orpc/tanstack-query": "^1.15.7",
+    "@shikijs/core": "^4.5.0",
+    "@shikijs/engine-javascript": "^4.5.0",
+    "@shikijs/langs": "^4.5.0",
+    "@shikijs/themes": "^4.5.0",
+    "@sinclair/typebox": "^0.34.52",
+    "@takumi-rs/image-response": "^2.16.3",
+    "@tanstack/react-form": "^1.33.5",
+    "@tanstack/react-query-devtools": "^5.104.3",
+    "@tanstack/react-virtual": "^3.14.20",
+    "@unhead/react": "^3.4.3",
+    "@xstate/store": "4.3.0",
+    "@xstate/store-react": "^2.1.0",
+    "better-auth": "^1.7.10",
+    "fractional-indexing": "^4.0.0",
+    "hono": "^4.13.13",
+    "lexical": "^0.52.0",
+    "lucide-react": "^1.57.0",
+    "marked": "^18.1.1",
+    "partysocket": "^1.3.0",
+    "react": "^19.3.1",
     "react-compiler-runtime": "^1.0.0",
-    "react-dom": "^19.2.6",
+    "react-dom": "^19.3.1",
     "react-og-preview": "^0.2.0",
-    "shiki": "^4.1.0",
-    "unhead": "^3.1.7",
-    "zod": "^4.4.3",
-    "@camox/api-contract": "0.44.0",
-    "@camox/cli": "0.44.0",
-    "@camox/ui": "0.44.0"
+    "shiki": "^4.5.0",
+    "unhead": "^3.4.3",
+    "zod": "^4.6.7",
+    "@camox/api-contract": "0.45.0",
+    "@camox/ui": "0.45.0",
+    "@camox/cli": "0.45.0"
   },
   "devDependencies": {
-    "@babel/core": "^7.29.0",
-    "@orpc/server": "^1.14.3",
-    "@rollup/plugin-babel": "^7.0.0",
-    "@tailwindcss/cli": "^4.3.0",
-    "@types/babel__core": "^7.20.5",
+    "@earendil-works/pi-ai": "1.3.0",
+    "@earendil-works/pi-durable": "1.3.0",
+    "@orpc/server": "^1.15.7",
+    "@tailwindcss/cli": "^4.3.3",
     "@types/node": "^24.12.4",
-    "@types/react": "^19.0.8",
-    "@types/react-dom": "^19.2.3",
-    "@typescript/native-preview": "7.0.0-dev.20260412.1",
-    "babel-plugin-react-compiler": "^1.0.0",
-    "happy-dom": "^20.14.5",
-    "tailwindcss": "^4.3.0",
-    "tsx": "^4.22.2",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "happy-dom": "^21.0.1",
+    "oxc-transform-react": "^0.152.0",
+    "tailwindcss": "^4.3.3",
+    "tsx": "^4.23.15",
     "tw-animate-css": "^1.4.0",
-    "vite": "npm:@voidzero-dev/vite-plus-core@latest",
-    "vite-plus": "^0.1.21"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.3.0",
+    "vite-plus": "1.3.0"
   },
   "peerDependencies": {
+    "@cloudflare/vite-plugin": "^1.64.0",
     "@tanstack/react-query": "^5.95.0",
     "@tanstack/react-router": "^1.166.2",
     "@tanstack/react-router-ssr-query": "^1.166.2",
@@ -170,14 +159,22 @@
   "nx": {
     "tags": [
       "type:pkg"
-    ]
+    ],
+    "targets": {
+      "test": {
+        "dependsOn": [
+          "^build"
+        ]
+      }
+    }
   },
   "scripts": {
     "dev": "mkdir -p .dev && cp ./src/features/preview/studio-overlays.css ./.dev/studio-overlays.css && tailwindcss -i ./src/studio.css -o ./.dev/studio.css --watch",
     "build": "vp pack && tailwindcss -i ./src/studio.css -o ./dist/studio.css --minify && cp ./src/features/preview/studio-overlays.css ./dist/studio-overlays.css",
     "build:watch": "vp pack --watch",
-    "lint": "vp lint",
+    "test": "tsx --test \"src/**/*.test.ts\" \"src/**/*.test.tsx\"",
     "test:inline": "tsx --test src/core/lib/inlineText.test.tsx src/core/components/lexical/inlineEditing.test.tsx",
-    "check": "tsgo --noEmit && vp lint --fix"
+    "test:images": "tsx --test src/core/lib/imagePlaceholder.test.tsx src/core/createBlock.test.tsx",
+    "test:content": "tsx --test src/features/content/content.test.tsx src/features/content/delete-collection-item.test.tsx"
   }
 }

package/skills/camox/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: camox
-description: Use when working in a Camox codebase with Block Definitions, Layout Definitions, Pages, Block content, the Camox CLI, publishing, or Environments. Applies to code-defined site structure and agent-driven content changes.
+description: Use when working in a Camox codebase with Block Definitions, Layout Definitions, Pages, Block content, the Camox CLI, or publishing. Applies to code-defined site structure and agent-driven content changes.
 ---
 
 # Camox
@@ -11,13 +11,22 @@ Read only the references needed for the current task. Do not preload every refer
 
 - Create a block or change its schema or field rendering API in `src/blocks/`:
   [Block Definitions](references/block-definitions.md).
-- Create or change a curated layout (a reusable shell for editor-created pages), including shared navbar/footer placement:
+- Create or change a curated layout (a reusable shell for editor-created pages), including navbar/footer layout slots:
   [Layout Definitions](references/layout-definitions.md).
 - Create or change a singleton page (a code-owned fixed URL) or derived route (a code-owned data-driven route) in `src/layouts/`:
   [Routed layouts](references/routed-layouts.md).
 - Share content across layouts with `synced: true`, independently of `layoutOnly`:
   [Synced blocks](references/block-definitions.md#synced-blocks-synced-optional).
 
+## Localized code
+
+Every block, layout and component renders in every locale the project publishes:
+
+- Put every visible text in blocks, layout blocks included. Camox translates block content, never JSX.
+- Pass internal links through `useLocalizedHref` from `camox/navigation`, and write paths without a locale prefix.
+
+For a locale switcher, a loader fetching localized data, or the details of either rule: [Localization](references/localization.md).
+
 ## Specialized block work
 
 - DOM listeners, scrolling, browser scripts, or third-party widgets:
@@ -25,6 +34,8 @@ Read only the references needed for the current task. Do not preload every refer
   Preview DOM lives in an iframe; component globals target the editor.
 - Customize inline text/link formatting or highlights:
   [Field styling](references/field-styling.md).
+- Bespoke visuals or widgets as code (animations, 3D scenes, interactive widgets), declaring `field.artifact` or writing an artifact source:
+  [Artifacts](references/artifacts.md).
 
 For specialized changes to an existing block, read the specialist reference directly. Also read Block Definitions only if creating a block or changing its schema or other field rendering APIs.
 
@@ -32,16 +43,10 @@ For specialized changes to an existing block, read the specialist reference dire
 
 For any CLI operation, first read [CLI common guidance](references/cli-common.md), then only the relevant command reference:
 
-- Pages, metadata, layout assignments, Block instances, content, ordering, or publishing:
+- Pages, metadata, layout assignments, Blocks, content, or ordering:
   [CLI Content](references/cli-content.md).
-- List comments on a Page or resolve a comment by its ID:
-  [CLI Content — Comments](references/cli-content.md#comments).
-- Production targeting or environment replication:
-  [CLI Environments](references/cli-environments.md).
-
-## Addressing feedback
-
-When asked to address feedback on a Page, read [CLI common guidance](references/cli-common.md) and [CLI Content — Comments](references/cli-content.md#comments), plus the relevant references for each change. Run `{{CAMOX_CMD}} comments list --page-id <PAGE_ID>` to load the Page's comments. For each unresolved comment, inspect its message and target, then find the relevant Page, Block, item, or field with the CLI (and its code definition if applicable). Make the required changes using the CLI for content and code for definitions. Only after addressing a comment, run `{{CAMOX_CMD}} comments resolve --page-id <PAGE_ID> --id <COMMENT_UUID>`. Leave comments you could not address unresolved and explain why. Re-list the Page's comments to verify their status. Do not publish draft changes unless requested.
+- Where the CLI writes, publishing or discarding the development draft, or its status:
+  [CLI Publishing](references/cli-publishing.md).
 
 Code definitions do not place blocks on existing Pages or assign their layouts; `blocks.initial` only seeds the initial homepage. When the request includes placement or assignment on existing Pages, follow with the relevant CLI workflow. Singleton pages and derived routes are declared in code, not created through the pages CLI.
 

package/skills/camox/references/artifacts.md

@@ -0,0 +1,179 @@
+# Artifacts
+
+An **artifact** is a field whose content is a self-contained web page (its **artifact source**), usually written by an agent and rendered in a sandboxed `<iframe>`. Artifacts hold bespoke visuals and interactions that blocks can't express: animated SVGs, 3D scenes, small interactive widgets.
+
+## Artifact or block?
+
+Pick an artifact when the element is really code: a one-off visual whose value is in how it moves or responds, which editors would never restructure. Pick a block for anything editors write, reorder, or reuse: headings, copy, links, images, lists, cards. Keep that content in the block's fields, around the artifact, so editors and agents can still read and change it.
+
+A definition that would fit one place on one site, or settings bolted on only to make a visual look reusable, is the signal for an artifact. Text that matters for SEO or Markdown belongs in fields, never inside the source: Camox treats the source as opaque and only reads its `<title>`.
+
+## Declare and render
+
+```tsx
+content: (field) => ({
+  heading: field.string({ default: "How it works" }),
+  visual: field.artifact({ size: "fill", title: "Diagram" }),
+}),
+```
+
+- `size` (required): `"fill"` fills a container whose size the block controls, for example with an aspect ratio; `"content"` is for frames whose height follows their page, such as calculators. See [Size to the content](#size-to-the-content).
+- `data` (optional): sibling content fields and settings shared with the artifact as **Artifact Data**, so editors can change what it shows without touching its source. Inside a repeater item, the siblings are the item's own fields and settings. The names are type-checked; artifacts, repeaters and references can't be listed. See [`camox.data`](#camoxdata).
+- `default` (optional): a starting source. Leave it out; agents write sources as content. An empty artifact renders nothing on the website and a placeholder in the studio preview.
+- Artifacts work in block content and repeater items, so also in layout and synced blocks. Collection records can't hold them.
+
+```tsx
+content: (field) => ({
+  label: field.string({ default: "Uptime" }),
+  gauge: field.artifact({ size: "fill", data: ["label", "tone"] }),
+}),
+settings: (setting) => ({
+  tone: setting.enum({ default: "calm", options: { calm: "Calm", bold: "Bold" } }),
+}),
+```
+
+```tsx
+<div className="aspect-video">
+  <block.Artifact name="visual">
+    {(props) => <iframe {...props} className="size-full" />}
+  </block.Artifact>
+</div>
+```
+
+Spread the props onto your own `<iframe>`: they carry `srcDoc`, `sandbox="allow-scripts"`, `allow="fullscreen; clipboard-write"`, `title`, `loading="lazy"`, a `ref` that connects the frame to the `camox` runtime, and for `size: "content"` a `style` with the frame's height. Don't replace the `ref`, and don't set a height on a `"content"` frame. Repeater items use `item.Artifact`. `block.Field` rejects artifact fields.
+
+## Write a source
+
+Write the source to a local file and push it with `blocks edit --id <ID> --field-file <NAME>=<PATH>` (or `blocks create`), then check it with `camox preview`; see [Set string fields from files](cli-content.md#set-string-fields-from-files). `blocks describe` lists artifact fields with `fieldType: "Artifact"` and their `size`. Artifacts that share Artifact Data also list the sibling names in `data`, and the exact shape of `camox.data` as JSON Schema in `dataSchema`: write the source against it.
+
+- **Under 256 KB.** Larger writes are rejected. Load libraries from a CDN instead of inlining them.
+- **Import from esm.sh with exact pinned versions**, so the artifact never changes under the website:
+
+  ```html
+  <script type="module">
+    import { animate } from "https://esm.sh/motion@12.23.12";
+  </script>
+  ```
+
+- **A meaningful `<title>`.** It names the frame for screen readers and is the artifact's Markdown Representation. Without one, the artifact is called "Untitled artifact", and `blocks create` and `blocks edit` return a warning.
+- **Respect `prefers-reduced-motion`** with the native media query, in CSS (`@media (prefers-reduced-motion: reduce)`) and in scripts (`matchMedia`), by stopping or simplifying motion.
+- **Fonts on the website's own domain need CORS headers.** The sandbox gives the page an opaque origin, so self-hosted fonts load only when the server sends `Access-Control-Allow-Origin: *` for them.
+
+## The `camox` runtime
+
+Camox injects a small runtime at the top of every source, before anything in it runs. It's how an artifact receives what its sandbox hides from it. `window.camox` always exists, so use it directly, without feature detection.
+
+Never implement your own `postMessage` protocol with the page. The website and the studio talk to artifacts only through `camox`, and nothing on the page listens for other messages.
+
+### `camox.data`
+
+The artifact's Artifact Data: an object with one entry per name in the field's `data`, matching the `dataSchema` that `blocks describe` shows. It's `{}` for artifacts that share no data. It's available from the first render, so the first paint can already show the right labels and values.
+
+Values are normalized:
+
+- Text fields are strings, as stored (inline Markdown, such as `**bold**`, is kept).
+- Links are `{ text, href, newTab }`, with page links already resolved to their path.
+- Images are `{ url, alt }`, files `{ url, filename }`, and image and file lists are arrays of those.
+- Embeds and icons are strings, enum settings their option key, and boolean settings booleans.
+
+### `camox.onData(callback)`
+
+Calls `callback` with the new `camox.data` each time it changes, for example when an editor edits a listed field in the studio, without reloading the frame. It isn't called on subscribe, and it returns a function that unsubscribes. Render from `camox.data` first, then re-render in the callback:
+
+```js
+const render = (data) => {
+  document.querySelector("h2").textContent = data.label;
+  document.body.dataset.tone = data.tone;
+};
+render(window.camox.data);
+window.camox.onData(render);
+```
+
+### `camox.studio`
+
+`null` on the website. Inside the studio, an object describing where the artifact is shown:
+
+- `editing`: `true` while editors can edit the artifact's block, on the Canvas.
+- `canvas`: `true` on the Canvas, where pages and blocks are laid out side by side.
+
+```js
+const editing = window.camox.studio?.editing === true;
+```
+
+Read it when you act rather than once at startup: it's `null` until the frame connects, and it changes when the editor shows or hides the Canvas. Use it to stay calm while someone is editing, for example by not autoplaying sound.
+
+### Theme: `camox.theme` and `camox.onTheme`
+
+Artifacts match the website automatically. The website's theme tokens (its CSS custom properties, named by each website; for instance `--canvas` or `--brand`) are applied to the artifact's `:root`, with the values of the color scheme where the artifact sits on the page: inside a block with the `dark` class, an artifact gets the dark color scheme's values. When the color scheme around the artifact changes, for example when a visitor switches the website to its dark color scheme, the tokens are applied again. Read the website's stylesheet for the tokens it defines and what each is for. Style with the tokens and CSS needs nothing else:
+
+```css
+body {
+  background: var(--canvas);
+  color: var(--ink);
+}
+```
+
+`camox.theme` holds the same tokens for scripts:
+
+- `tokens`: each token's raw value, such as `{ "--brand": "oklch(0.55 0.2 260)", "--radius": "0.5rem" }`.
+- `colors`: each color token as sRGB channels from 0 to 255, such as `{ "--brand": { r: 37, g: 99, b: 235 } }`, including tokens written in `oklch()`. Use these for canvas, three.js or WebGL, which can't read CSS variables.
+
+`camox.onTheme(callback)` calls `callback(theme)` whenever the tokens change, and returns a function that unsubscribes. It isn't called for the theme the artifact already has, so draw once with `camox.theme`, then on each change:
+
+```js
+const draw = ({ colors }) => {
+  const { r, g, b } = colors["--brand"];
+  material.color.setRGB(r / 255, g / 255, b / 255, THREE.SRGBColorSpace);
+};
+draw(window.camox.theme);
+window.camox.onTheme(draw);
+```
+
+- **The body starts hidden.** It stays invisible until the first theme arrives, so the artifact never shows in the wrong colors. If no theme comes, it shows after a short timeout. Don't fight this by forcing `visibility` on `body`.
+- **Never use `prefers-color-scheme`** to pick light or dark. Inside the frame it follows the visitor's OS, not the website, which may be dark on a light OS or the reverse. Rely on the tokens.
+- **Fonts.** The website's font stylesheets and preconnect links from its document definition are loaded before your source, so its fonts work from the first render. Use the website's font family names, or the tokens that hold them.
+
+### `camox.onViewport(callback)`
+
+Scroll-driven animations follow where the frame sits in the page's viewport. The first call subscribes; it returns a function that unsubscribes. The callback receives:
+
+- `progress`: `0` when the frame's top enters at the bottom of the viewport, `1` when its bottom leaves at the top, `0.5` when the frame is centered.
+- `visibleRatio`: the share of the frame inside the viewport, from `0` to `1`.
+
+```js
+const stop = window.camox.onViewport(({ progress, visibleRatio }) => {
+  scene.rotation.y = progress * Math.PI * 2;
+  if (visibleRatio === 0) pauseRendering();
+});
+```
+
+While subscribed, the runtime also sets `--camox-progress` on `:root`, so CSS alone can scrub with scroll. Subscribe once, even with an empty callback, to get it:
+
+```html
+<style>
+  .orbit {
+    transform: rotate(calc(var(--camox-progress, 0) * 1turn));
+  }
+</style>
+<script>
+  window.camox.onViewport(() => {});
+</script>
+```
+
+Updates arrive at most once per animation frame, only while the frame is near the viewport, and only when the values change. After the frame leaves the viewport, the last update is `visibleRatio: 0`, with `progress` at `0` or `1`. Artifacts that never subscribe get nothing and cost nothing. Don't read the frame's own scroll position or listen to `scroll` inside it: the artifact can't see the page scroll.
+
+### Size to the content
+
+With `size: "content"`, the runtime measures the height of the artifact's `<html>` element and the frame follows it as the content changes, so the page never shows a scrollbar inside the frame. Let the document grow with its content: never give `html` or `body` a height in viewport or percentage units (`100vh`, `100%`), which would tie the content's height to the frame's. With `size: "fill"`, the block sizes the frame and the artifact never resizes it.
+
+### `camox.navigate(href)`
+
+Navigates the website, for example from a widget's call to action. Internal paths such as `/pricing` go through the website's client router; external URLs open in a new tab. Only `http` and `https` URLs work.
+
+```js
+button.addEventListener("click", () => window.camox.navigate("/pricing?plan=pro"));
+```
+
+It only works right after a real click or key press in the artifact. Calls from timers, scroll callbacks or page load do nothing, so an artifact can't redirect visitors on its own. The sandbox blocks popups and navigating the website: a plain `<a href>` would only load inside the frame, and `window.open` does nothing. Use `camox.navigate` instead.
+
+The runtime API has no stability guarantee while Camox is pre-1.0.