camox 0.69.0 → 0.72.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "camox",
-  "version": "0.69.0",
+  "version": "0.72.0",
   "license": "MIT",
   "bin": {
     "camox": "./bin/camox.mjs"
@@ -148,9 +148,9 @@
     "unhead": "^3.4.3",
     "yaml": "^2.9.0",
     "zod": "^4.6.7",
-    "@camox/api-contract": "0.69.0",
-    "@camox/ui": "0.69.0",
-    "@camox/cli": "0.69.0"
+    "@camox/ui": "0.72.0",
+    "@camox/api-contract": "0.72.0",
+    "@camox/cli": "0.72.0"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "1.3.0",
@@ -162,6 +162,7 @@
     "@types/react-dom": "^19.3.0",
     "happy-dom": "^21.0.1",
     "oxc-transform-react": "^0.152.0",
+    "playwright-core": "1.64.1",
     "tailwindcss": "^4.3.3",
     "tsrs": "0.20.1-ts7.1.0-beta",
     "tsx": "^4.23.15",
@@ -203,6 +204,7 @@
     "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",
     "test": "tsx --test \"src/**/*.test.ts\" \"src/**/*.test.tsx\"",
+    "test:browser": "tsx --test --test-concurrency=1 \"src/**/*.browser-test.ts\"",
     "test:inline": "tsx --test src/core/lib/inlineText.test.tsx src/core/components/lexical/inlineEditing.test.tsx",
     "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

@@ -45,6 +45,6 @@ Use the platform. Build tabs, dialogs, carousels, menus and disclosures from nat
 
 ## Content
 
-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, make it as a content change once Camox has discovered the new definition. Singleton pages and derived routes are declared in code, never created as Pages.
+Code definitions do not place blocks on Pages, assign layouts, or write content. When the request includes placement, assignment, or content, make it as a content change once Camox has discovered the new definition. Singleton pages and derived routes are declared in code, never created as Pages.
 
 A request can cross boundaries. Load an additional reference only once that need is established.

package/skills/camox/references/artifacts.md

@@ -12,23 +12,23 @@ A definition that would fit one place on one site, or settings bolted on only to
 
 ```tsx
 content: (field) => ({
-  heading: field.string({ default: "How it works" }),
+  heading: field.string({ title: "Heading" }),
   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.
+- Agents write sources as content, never in the definition. 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" }),
+  label: field.string({ title: "Label" }),
   gauge: field.artifact({ size: "fill", data: ["label", "tone"] }),
 }),
 settings: (setting) => ({
-  tone: setting.enum({ default: "calm", options: { calm: "Calm", bold: "Bold" } }),
+  tone: setting.enum({ options: { calm: "Calm", bold: "Bold" } }),
 }),
 ```
 
@@ -56,7 +56,8 @@ The source is content, not code: set it as the artifact field's value, like any
   ```
 
 - **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.
+- **Motion that plays on its own goes through the Timeline** (`camox.timeline`, below): no CSS animations, CSS transitions, Web Animations or timers that move the artifact by themselves. CSS transitions stay fine for feedback to a visitor's hover or press, and so do libraries you can drive from `render(t)`.
+- **Respect `prefers-reduced-motion`.** The Timeline does it for you (it shows its poster). For any other motion, such as a hover transition, use the native media query, in CSS (`@media (prefers-reduced-motion: reduce)`) and in scripts (`matchMedia`), by stopping or simplifying it.
 - **Link fonts from Google Fonts**, with a `<link>` to the family's `css2` stylesheet in the source's own `<head>`, as the website's Document does. The sandbox gives the page an opaque origin, and Google Fonts sends the CORS headers that needs. A font file the website serves itself loads only when its server sends `Access-Control-Allow-Origin: *` for it.
 
 ## The `camox` runtime
@@ -133,6 +134,89 @@ window.camox.onTheme(draw);
 - **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.
 
+### Motion: `camox.timeline`
+
+An artifact that moves on its own declares a Timeline: how long its animation lasts, whether it loops, its named beats (Marks), and a `render(t)` function that draws the artifact at any time `t`, in milliseconds, from `t` alone. Call it once, synchronously, from the source (never after an `await`):
+
+```js
+const meter = document.querySelector(".meter");
+camox.timeline({
+  duration: 12000, // ms
+  loop: true, // false: plays once and holds its last frame
+  marks: { typed: 1200, payoff: 4800, settled: 5500 },
+  poster: "settled", // the Mark whose frame stands for the artifact
+  render(t) {
+    meter.style.width = camox.interpolate(t, [4800, 5500], [0, 64], { ease: "arrive" }) + "%";
+  },
+});
+camox.type(document.querySelector(".query"), "Revenue by region", { at: 200, cps: 18 });
+camox.count(document.querySelector(".total"), {
+  from: 0,
+  to: 1280,
+  at: 4800,
+  duration: 700,
+  format: (value) => "$" + Math.round(value).toLocaleString("en-US"),
+});
+```
+
+- **`render(t)` draws from `t` alone.** It's called inside `requestAnimationFrame`, synchronously, and must give the same frame for the same `t` whatever came before: never keep state between calls, never read the clock, and never read layout. Write only what changed.
+- **On the website**, the runtime calls `render` on every animation frame with real time. A looping Timeline wraps at `duration`: `t = duration` is the next loop's start, so its last frame is `duration - 1`. Make the last frame lead back into the first, so the loop restarts without a jump. A Timeline that doesn't loop holds its last frame.
+- **When it plays.** A looping Timeline plays from the moment the artifact loads. One that doesn't loop waits until its frame first comes into the viewport, plays once and holds its last frame, so visitors don't miss it. Both pause while the frame is out of the viewport and resume where they were when it comes back.
+- **Its first frame is drawn at once.** `camox.timeline` draws `t = 0` (Tracks and `render`) before it returns, before the artifact is revealed, so it never shows unfinished. Build the elements `render` and the Tracks use before calling it; the `type` and `count` helpers, called right after, are drawn at once too.
+- **Reduced motion shows the poster.** For visitors who prefer reduced motion, the Timeline shows its poster's frame and never plays: name as `poster` the Mark whose frame tells the story on its own. Without one, it shows the last frame of a Timeline that doesn't loop, or the first of one that loops.
+- **`look` sees it exactly.** Camox's agent captures any Moment of the Timeline at once: a Mark, a Mark plus a delay, or a time. Place each Mark where its beat is visible, as its transition settles, not where the transition starts: the frame at a Mark shows the beat, and a Mark at the start of an entrance shows the frame before it, which reads as a beat that comes late.
+- **`look` reports what escapes it**, beside its images: CSS animations, CSS transitions that nothing a visitor did started, Web Animations the source made and left playing (a paused one whose `currentTime` `render(t)` sets, as a seekable library does, is on the Timeline), timers still running, Tracks the runtime skipped, Tracks on the same element and property that overlap, and a loop cut, where a looping Timeline's last frame differs from its first (what Tracks show and what `render` wrote, on what's visible at either end). An element hidden at both ends can reset freely. Fix each finding rather than working around it.
+- Marks are times from `0` to `duration`. `poster` names one of them: the frame for reduced motion.
+- **Movement and fades are Tracks**, not `render` (below).
+- An artifact that never calls `camox.timeline` behaves as before, with nothing to seek.
+
+#### Tracks: movement and fades
+
+Anything that moves or fades is a Track: the runtime plays Tracks as Web Animations on the compositor, so they stay smooth while the website's page is busy loading, where motion written from `render` stutters, most of all on phones. Declare them in `tracks`:
+
+```js
+const card = document.querySelector(".card");
+camox.timeline({
+  duration: 8000,
+  loop: true,
+  marks: { shown: 1300, gone: 6000 },
+  tracks: [
+    // In, hold, out: Tracks of one element and property play as one sequence.
+    {
+      el: card,
+      at: 400,
+      duration: 900,
+      ease: "arrive",
+      keyframes: { transform: ["translateY(24px)", "none"], opacity: [0, 1] },
+    },
+    {
+      el: card,
+      at: 5400,
+      duration: 600,
+      ease: "travel",
+      keyframes: { transform: ["none", "translateY(-24px)"], opacity: [1, 0] },
+    },
+  ],
+});
+```
+
+- A Track has its element `el`, its start `at` and its `duration` in ms, an `ease` (`"linear"`, the default, `"travel"` or `"arrive"`, the same curves as `interpolate`'s), and its `keyframes`: for `transform` and `opacity` only, each `[from, to]`. Anything else (colors, sizes, text) goes in `render`.
+- A Track must end by the Timeline's `duration`. Before its first Track, an element shows that Track's `from`; between Tracks it holds the last `to`; after its last Track it holds its `to`. Make the value at the loop's end match its start.
+- Several Tracks on one element and property must not overlap in time: give them one after the other.
+- A Track the runtime can't play (another property, an unknown `ease`, an end past `duration`) is skipped, so the rest of the artifact still plays, and `look` reports it.
+- **Size-based keyframes:** `keyframes` can be a function of the artifact's size, `({ width, height }) => keyframes`, in CSS pixels. The runtime calls it again when the frame is resized, keeping the current time: `keyframes: ({ width }) => ({ transform: ["none", "translateX(" + width / 2 + "px)"] })`.
+- Don't animate a Track's element and property anywhere else, in CSS or from `render`.
+
+Helpers for `render`:
+
+- `camox.interpolate(t, [inStart, inEnd], [outStart, outEnd], { ease })` maps `t` from one range to the other, clamped at both ends. `ease` is `"linear"` (the default), `"travel"` (`cubic-bezier(0.45, 0, 0.1, 1)`, for something moving from one place to another) or `"arrive"` (`cubic-bezier(0.25, 0.8, 0.25, 1)`, for something coming in and settling), or a function of the progress from `0` to `1`.
+- `camox.random(seed)` gives a number from `0` to `1` for a number or a string, always the same for the same seed. Use it instead of `Math.random()` for anything `render` draws, such as `camox.random(index)` per particle.
+
+Typed text and rolling numbers have their own helpers. Call them once each, after `camox.timeline` and outside `render`: the Timeline draws them at every `t`, before `render`, so they restart with each loop and land exactly where `look` seeks. They write only what changed, and add no style of their own: the element keeps the website's font, size and color.
+
+- `camox.type(el, text, { at, cps })` types `text` into `el`, starting at `at` ms (default `0`), `cps` characters a second (default `20`). It replaces what `el` holds with the typed text and a caret in the text's own line, right after the last character, in the text's color, whatever `el`'s layout (even a flex row with a gap). The first character shows at `at`, then one more every `1000 / cps` ms, so the whole text is in at `at + (length - 1) * 1000 / cps`. The caret is solid while typing, until `at + length * 1000 / cps`, one character's time after the last, and blinks before and after. Never draw a caret of your own.
+- `camox.count(el, { from, to, at, duration, ease, format })` rolls the number in `el` from `from` (default `0`) to `to`, over `duration` ms (default `1000`) from `at` (default `0`), eased with `ease` (`"arrive"` by default; the same names as `interpolate`). It shows `from` before `at` and holds `to` after. `format(value)` returns the text to show; without it, the number is shown with the decimals of `from` and `to`, grouped in the visitor's locale. Give `el` `font-variant-numeric: tabular-nums` so the digits don't jitter as they roll.
+
 ### `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:

package/skills/camox/references/block-definitions.md

@@ -16,7 +16,7 @@ const myBlock = createBlock({
   title: "My Block",
   description: "A page introduction with an editable heading.",
   content: (field) => ({
-    title: field.string({ default: "Welcome" }),
+    title: field.string({ title: "Title" }),
   }),
   toReact: MyBlockComponent,
   toTitle: ({ content }) => content.title,
@@ -45,7 +45,7 @@ For DOM listeners, scrolling, scripts, widgets, or JavaScript-driven animation,
 | `description`      | yes      | Agent guidance on placement, expected content, and tone.                                       |
 | `content`          | yes      | `(field) => ({ ... })`: field names mapped to `field.*` builders for editable content.         |
 | `settings`         | no       | `(setting) => ({ ... })`: settings-panel options; only `setting.enum` and `setting.boolean`.   |
-| `layoutOnly`       | no       | If true, restricts placement to layouts and hides the type from the add-block picker.          |
+| `layoutOnly`       | no       | If true, restricts placement to layouts.                                                       |
 | `synced`           | no       | Defaults to false. Shares content/settings across placements; see below.                       |
 | `toReact`          | yes      | Named React function component. Receives `{ content, settings }` as props.                     |
 | `toTitle`          | yes      | `({ content, settings }) => ...` one-line title; see below.                                    |
@@ -58,7 +58,7 @@ For DOM listeners, scrolling, scripts, widgets, or JavaScript-driven animation,
 
 For shared navbar/footer data across layouts, use `layoutOnly: true, synced: true`. These flags are independent: synced blocks can also be ordinary page-content blocks.
 
-- Editing any placement updates the shared content everywhere. New placements reuse existing data rather than resetting to defaults.
+- Editing any placement updates the shared content everywhere. New placements reuse the shared content.
 - Position, layout slot, and deletion remain per placement; deleting one placement leaves the others.
 - Enabling syncing on an existing type applies the oldest placement's data to all placements. Disabling it leaves independently editable copies.
 
@@ -119,7 +119,9 @@ Only Boolean/Enum settings support these conditionals. A repeater's `settings` r
 
 ## Content Field Types
 
-`content` and a repeater's `content` receive a `field` builder; `settings` receive a `setting` builder. Each builder only offers what its context accepts: `field` has no `enum` or `boolean`, and `setting` has nothing else. Supply defaults for scalar fields; images/files get automatic placeholders (empty images paint with the stylesheet's `--camox-placeholder` and `--camox-placeholder-ink`), lists use `defaultItems`, and repeaters use their item schemas and bounds.
+`content` and a repeater's `content` receive a `field` builder; `settings` receive a `setting` builder. Each builder only offers what its context accepts: `field` has no `enum` or `boolean`, and `setting` has nothing else.
+
+A definition declares a block's shape, never its content: the agent writes every field's content when it places the block. A field nobody has written reads as the empty value of its kind: `""` for strings, embeds, icons and artifacts, an empty link, `null` for an image, file or reference, no items for lists and repeaters, `false` for a boolean setting, and an enum setting's first option. So render well with any content, including empty optional fields: a short or long title, a missing subtitle, one repeatable item or many. An empty image paints Camox's placeholder with the stylesheet's `--camox-placeholder` and `--camox-placeholder-ink`; an empty file, image list or file list renders nothing.
 
 ### field.string
 
@@ -127,7 +129,6 @@ Inline-editable text supporting formatting and links while remaining a string. S
 
 ```tsx
 field.string({
-  default: "Hello world",
   title: "Heading", // Optional label
   maxLength: 280, // Optional
   minLength: 1, // Optional
@@ -143,34 +144,33 @@ Choose one Iconify collection in Vite config:
 camox({ projectId: "01a15fff-627b-7fa1-938b-93ab659c1acc", icons: "lucide" });
 ```
 
-Declare a non-nullable icon with a required, prefixed default, then render inline SVG:
+Declare an icon field, then render inline SVG:
 
 ```tsx
 // In content:
-icon: field.icon({ default: "lucide:zap", title: "Icon" })
+icon: field.icon({ title: "Icon" })
 
 // In the component (also supported as <item.Icon> inside repeaters):
 <block.Icon name="icon" className="size-6 text-brand" />
 <block.Icon name="icon" aria-label="Fast" />
 ```
 
-Icons are decorative unless given `aria-label` or `aria-labelledby`. Clicking an icon in preview opens the searchable collection picker. Values remain namespaced strings; editors cannot select another collection or an empty value.
+Icons are decorative unless given `aria-label` or `aria-labelledby`. Clicking an icon in preview opens the searchable collection picker. Values are namespaced strings such as `"lucide:zap"`; editors cannot select another collection or clear the icon.
 
 Run `pnpm exec camox typegen` **before TypeScript checking in CI**, for example `camox typegen && tsc --noEmit`. This resolves Vite config without starting a server. It generates `src/camox/icons.gen.d.ts`; ensure your tsconfig includes it. Dev and build regenerate it automatically. Generation requires network access to the pinned Iconify snapshot.
 
-Camox resolves selected SVGs from that same versioned snapshot and serves them through its API. Server rendering preloads selected/default SVGs into hydration data; no visitor requests to Iconify and no rebuild is needed when content changes. Only the editor fetches collection metadata and picker previews, not a whole SVG catalog.
+Camox resolves selected SVGs from that same versioned snapshot and serves them through its API. Server rendering preloads selected SVGs into hydration data; no visitor requests to Iconify and no rebuild is needed when content changes. Only the editor fetches collection metadata and picker previews, not a whole SVG catalog.
 
 Collection licenses still apply. SVG responses retain author/license attribution. Include any copyright notices, license text, or attribution required by your chosen collection in your site's distributed notices; Iconify does not relicense the icons. Changing collections or migrating existing icon values is not supported in v1.
 
 ### setting.boolean and setting.enum
 
-Settings only: configuration choices are never block or repeater content. Enum defaults must match an option key.
+Settings only: configuration choices are never block or repeater content. An unset enum reads as its first option, so list the most common or neutral one first. An unset boolean reads as `false`, so name it for what turning it on does (`showBackground`, not `hideBackground`).
 
 ```tsx
 settings: (setting) => ({
-  showBackground: setting.boolean({ default: false, title: "Show background" }),
+  showBackground: setting.boolean({ title: "Show background" }),
   alignment: setting.enum({
-  default: "left",
     options: { left: "Left", center: "Center", right: "Right" },
     title: "Alignment",
   }),
@@ -182,10 +182,7 @@ settings: (setting) => ({
 Text, destination, and new-tab toggle. Curated page links store page IDs; singleton links store fixed URLs using the existing `type: "external"` representation, which also supports site-relative URLs: `{ type: "external", href: "/pokedex", text: "Pokédex", newTab: false }`. Both page kinds appear in Studio's destination picker. Inline `[Pokédex](/pokedex)` links stay in the current tab.
 
 ```tsx
-field.link({
-  default: { text: "Learn more", href: "/", newTab: false },
-  title: "CTA",
-});
+field.link({ title: "CTA" });
 ```
 
 ### Images and files
@@ -194,19 +191,18 @@ Files support MIME filtering. Render each type with its matching helper; asset l
 
 ```tsx
 field.image({ title: "Cover photo" });
-field.imageList({ defaultItems: 6, title: "Gallery images" });
+field.imageList({ title: "Gallery images" });
 field.file({ accept: ["application/pdf"], title: "PDF Document" });
-field.fileList({ accept: ["application/pdf"], defaultItems: 0, title: "Documents" });
+field.fileList({ accept: ["application/pdf"], title: "Documents" });
 ```
 
 ### field.embed
 
-A URL validated against a regex. A nonmatching default throws at definition time.
+A URL validated against a regex. Content that doesn't match is rejected.
 
 ```tsx
 field.embed({
   pattern: "https:\\/\\/(www\\.)?(youtube\\.com|youtu\\.be)\\/.+",
-  default: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
   title: "YouTube URL",
 });
 ```
@@ -222,16 +218,16 @@ field.artifact({ size: "fill", data: ["headline", "variant"] }); // shares sibli
 
 ### field.repeater
 
-Structured items with their own content, optional settings, and required `toTitle` and `toMarkdown`. `minItems` must be at least 1; repeaters cannot be empty. Nest repeaters in an item's `content` when needed.
+Structured items with their own content, optional settings, and required `toTitle` and `toMarkdown`. `minItems` must be at least 1: editors can't remove the last item. A block whose repeater was never written has no items, so render well with none. Nest repeaters in an item's `content` when needed.
 
 ```tsx
 field.repeater({
   content: (field) => ({
-    name: field.string({ default: "Feature" }),
-    description: field.string({ default: "Description" }),
+    name: field.string({ title: "Name" }),
+    description: field.string({ title: "Description" }),
   }),
   settings: (setting) => ({
-    highlighted: setting.boolean({ default: false, title: "Highlighted" }),
+    highlighted: setting.boolean({ title: "Highlighted" }),
   }),
   minItems: 1,
   maxItems: 10,
@@ -279,7 +275,7 @@ Place a repeater's token where its items' nodes go, such as an FAQ's questions:
 
 ```tsx
 items: field.repeater({
-  content: (field) => ({ question: field.string({ default: "Why?" }), answer: field.string({ default: "Because" }) }),
+  content: (field) => ({ question: field.string({ title: "Question" }), answer: field.string({ title: "Answer" }) }),
   minItems: 1,
   maxItems: 20,
   toTitle: ({ content }) => content.question,

package/skills/camox/references/dom-integrations.md

@@ -2,7 +2,7 @@
 
 Use this reference for block DOM listeners, scrolling, browser scripts, and third-party widgets. It can be read independently of [Block Definitions](block-definitions.md); read that reference only if also changing the block schema or field rendering API.
 
-**Do not use component-global `window` or `document` to target a block's DOM.** Camox preview (including block thumbnails) renders blocks into an iframe through a React portal, but component code executes in the editor's JavaScript realm. Global scroll listeners observe the editor; scripts appended to the global document load there instead of beside your block.
+**Do not use component-global `window` or `document` to target a block's DOM.** Camox preview renders blocks into an iframe through a React portal, but component code executes in the editor's JavaScript realm. Global scroll listeners observe the editor; scripts appended to the global document load there instead of beside your block.
 
 Use `getElementContext` from `camox/dom` inside an effect or event handler, passing a rendered element. It returns `{ window, document }` from the element's `ownerDocument` and `defaultView`, or `null` for a missing element or a document without a window. It never falls back to globals, requires no provider, and works in regular rendering too. Don't access DOM APIs during SSR.
 

package/skills/camox/references/layout-definitions.md

@@ -23,7 +23,6 @@ const myLayout = createLayout({
   blocks: {
     before: [navbarBlock],
     after: [footerBlock],
-    initial: [() => import("../blocks/hero")],
   },
   toReact: MyLayoutComponent,
   toTitle: ({ page, project }) => `${page.title} | ${project.name}`,
@@ -50,7 +49,7 @@ export { myLayout as layout };
 | `id`               | yes      | Unique kebab-case identifier matching the filename without extension.                                  |
 | `title`            | yes      | CMS display name.                                                                                      |
 | `description`      | yes      | Guidance for users and agents on which pages suit this layout.                                         |
-| `blocks`           | yes      | `before`, `after`, and optional `initial` arrays; see layout slot rules below.                         |
+| `blocks`           | yes      | `before` and `after` arrays; see layout slot rules below.                                              |
 | `toReact`          | yes      | Named function component receiving the context and `{ children }` as props.                            |
 | `toTitle`          | yes      | `(context) => string`: the head title, `og:title`, and the Markdown front matter's `title`.            |
 | `toDescription`    | yes      | `(context) => string \| undefined`: the head description and `og:description`. May return `undefined`. |
@@ -68,20 +67,12 @@ Every `to*` option receives the same context object, and none receives another o
 
 Singleton and derived layouts also receive `data` and `params`, and record pages `content`; see [Routed layouts](routed-layouts.md#metadata-and-markdown).
 
-## Layout Slots — `before`, `after`, and `initial`
+## Layout Slots — `before` and `after`
 
 - `before` and `after` require blocks with `layoutOnly: true`. Either array may be empty.
 - Render groups with `<myLayout.BeforeBlocks />` and `<myLayout.AfterBlocks />`, not individual blocks. Array order controls rendering order; edit the config to add or reorder blocks.
 - For identical navbar/footer content across layouts, also set `synced: true`. `layoutOnly` restricts a block to layout slots; it does not enable syncing. See [Synced blocks](block-definitions.md#synced-blocks-synced-optional) for sharing and existing-placement behavior.
-
-## Initial Blocks — `blocks.initial` (optional)
-
-`initial` seeds the homepage at project creation, using block defaults in array order. It does not populate existing Pages.
-
-- List each block as an import of its module, `() => import("../blocks/hero")`, never a statically imported block. Layouts load on every page, so a static import would ship the block to every visitor.
-- Accepts only blocks with `layoutOnly` omitted or `false`.
-- At most one layout per app may define `initial`; multiple definitions cause a startup error.
-- Without `initial`, Camox seeds an empty homepage using the first curated layout. Apps with only singleton/derived layouts do not seed a curated homepage.
+- A slot's new blocks start with no content when the layout syncs. Fill them as a [content change](../SKILL.md#content) once Camox has discovered the layout.
 
 ## OG Image — `toImage` (optional)
 

package/skills/camox/references/routed-layouts.md

@@ -53,7 +53,7 @@ function PokedexPage() {
 - `loader` is optional. Return `{ kind: "data", data }`, synchronously or asynchronously. `layout.useData()` infers and returns the unwrapped `data`, not the envelope. It runs server-side for document requests and client navigation; the entire envelope travels through JSON to hydration. Keep data JSON-serializable (no functions, symbols, BigInt, or cyclic objects). Without a loader, `useData()` returns `undefined`. The loader also receives `locale`, the page's locale tag; Camox renders its data untranslated (see [Localization](localization.md#loaders)).
 - Before/after blocks must be `layoutOnly: true`. Put editable headings, introductions, and other bespoke content in these blocks; keep structural application UI in the component. See [Block Definitions](block-definitions.md).
 - For a navbar or footer whose content must stay identical across different layouts, also set `synced: true` in its `createBlock` options. `layoutOnly: true` alone only restricts placement. See [Synced blocks](block-definitions.md#synced-blocks-synced-optional) for sharing behavior.
-- No `children` slot or `blocks.initial`: editors do not compose or create these pages.
+- No `children` slot: editors do not compose or create these pages.
 - No curated page record is created. Never create, duplicate, move, or assign a singleton as a Page.
 - Studio lists singletons as directly navigable pages with block editing, without deletion or URL/layout controls. They also appear in link destination pickers (including inline text links), “Go to page” actions, and the runtime sitemap. Derived pages appear in the sitemap only when their layout declares `routes` (see [Route discovery](#route-discovery)).
 - Singleton links are saved as fixed internal URLs, not synthetic database page IDs: link fields use `{ type: "external", href: "/pokedex", text: "Pokédex", newTab: false }` (the existing URL representation), while inline text uses `[Pokédex](/pokedex)`. Renaming a code-owned URL requires updating links or adding a redirect. Curated-page links retain their page-ID references.
@@ -65,7 +65,7 @@ function PokedexPage() {
 
 ## Derived routes
 
-Use the same file-based form with `kind: "derived"`, for example `createLayout("pokemon.$name")`. Its required `loader: ({ params }) => ...` receives typed `params.name` and returns `{ kind: "data", data }`. Read its unwrapped data through `layout.useData()`. Use `throw notFound()` (imported from `camox/createLayout`) for a missing record; other loader errors remain server errors. Like singletons, derived routes have before/after blocks but no page-owned `children` or `blocks.initial`. Unlike singletons, curated URLs retain precedence over derived routes.
+Use the same file-based form with `kind: "derived"`, for example `createLayout("pokemon.$name")`. Its required `loader: ({ params }) => ...` receives typed `params.name` and returns `{ kind: "data", data }`. Read its unwrapped data through `layout.useData()`. Use `throw notFound()` (imported from `camox/createLayout`) for a missing record; other loader errors remain server errors. Like singletons, derived routes have before/after blocks but no page-owned `children`. Unlike singletons, curated URLs retain precedence over derived routes.
 
 ### Route discovery
 

package/skills/camox-expand/SKILL.md

@@ -51,11 +51,11 @@ Stop suggesting when the next idea would be filler; there is no target count. Th
 
 Make only these kinds of change:
 
-- **New Block Definitions**, following [Block Definitions](../camox/references/block-definitions.md), [Localized code](../camox/SKILL.md#localized-code) (every visible text in fields, internal links through `useLocalizedHref` without a locale prefix), and Camoxify's rules on [styling](../camoxify/SKILL.md#use-the-existing-styling-stack), [genericity and default content](../camoxify/SKILL.md#keep-definitions-generic), [repeaters](../camoxify/SKILL.md#model-repetition-not-a-fixed-screenshot), [Settings](../camoxify/SKILL.md#use-settings-for-constrained-choices), and [formatted text](../camoxify/SKILL.md#keep-formatted-text-in-one-field).
-- **New Settings on existing Block Definitions**, with defaults that leave current rendering unchanged. Existing content schemas stay exactly as they are. Before editing the block, capture it at desktop and mobile on a Page that places it, on the running dev server; step 6 compares against this capture.
+- **New Block Definitions**, following [Block Definitions](../camox/references/block-definitions.md), [Localized code](../camox/SKILL.md#localized-code) (every visible text in fields, internal links through `useLocalizedHref` without a locale prefix), and Camoxify's rules on [styling](../camoxify/SKILL.md#use-the-existing-styling-stack), [genericity](../camoxify/SKILL.md#keep-definitions-generic), [repeaters](../camoxify/SKILL.md#model-repetition-not-a-fixed-screenshot), [Settings](../camoxify/SKILL.md#use-settings-for-constrained-choices), and [formatted text](../camoxify/SKILL.md#keep-formatted-text-in-one-field).
+- **New Settings on existing Block Definitions** whose unset value (`false`, or an enum's first option) leaves current rendering unchanged, since existing blocks read it. Existing content schemas stay exactly as they are. Before editing the block, capture it at desktop and mobile on a Page that places it, on the running dev server; step 6 compares against this capture.
 - **Description edits.** A new block's `description` says when to choose it over its siblings. Edit the siblings' descriptions so each one names what sets it apart, and the Agent can choose between them.
 
-New blocks live only in code, plus one review Page in the development draft: create it with the CLI (see [Managing Pages and Blocks](../camox-cli/references/cli-content.md)) and place each new block on it with its default content. Leave every other Page, layouts, and publishing alone. This rules out new Layout-only Blocks: a Page can't hold them, and they only sync once a layout uses them. An existing Layout-only Block that gains a Setting is captured and checked on a Page whose layout uses it.
+New blocks live only in code, plus one review Page in the development draft: create it with the CLI (see [Managing Pages and Blocks](../camox-cli/references/cli-content.md)) and place each new block on it with representative content. Leave every other Page, layouts, and publishing alone. This rules out new Layout-only Blocks: a Page can't hold them, and they only sync once a layout uses them. An existing Layout-only Block that gains a Setting is captured and checked on a Page whose layout uses it.
 
 ## 6. Verify
 
@@ -66,5 +66,5 @@ The run is complete when:
 - every approved item is built, and every rejected one is deleted,
 - the review Page is deleted once the operator has reviewed it,
 - the project's `check` script passes, and so does `vp lint --type-aware --type-check`, since `vp check` skips type errors unless the project's Vite config sets `lint.options.typeCheck`,
-- every new block renders correctly with its default content at desktop and mobile on the review Page,
-- every existing block that gained a Setting renders the same as its capture with default Settings.
+- every new block renders correctly with its review content, and with its optional fields empty, at desktop and mobile on the review Page,
+- every existing block that gained a Setting renders the same as its capture with the new Setting unset.

package/skills/camoxify/SKILL.md

@@ -47,9 +47,9 @@ Express layout, spacing, typography, colors, responsive behavior, and interactiv
 
 ## Keep definitions generic
 
-Block names, schemas, rendering, and **default content** must work on other pages. Use `feature-grid`, not `acme-homepage-features`. Defaults are neutral examples, not the reference's copy, links, assets, or item data.
+Block names, schemas, and rendering must work on other pages. Use `feature-grid`, not `acme-homepage-features`.
 
-Apply reference-specific content **only to instances through the CLI**, never by changing definition defaults or hardcoding it in JSX.
+Apply reference-specific content **only to instances through the CLI**, never in the definition or hardcoded in JSX.
 
 Keep the result translatable, following [Localized code](../camox/SKILL.md#localized-code): every visible text in the shell, navigation and footer included, lives in blocks, and internal links go through `useLocalizedHref`, written without a locale prefix.
 
@@ -63,7 +63,7 @@ Choose bounds from real constraints, not the number of items visible in the refe
 
 Before adding a `content` field, ask whether the editor is writing free-form content or choosing from known options. For configuration choices such as alignment, theme, size, or variant, use `settings` with `setting.enum`. For on/off choices such as showing a background or enabling autoplay, use `settings` with `setting.boolean`.
 
-Do not model these choices as `content` fields using `field.string`, even if rendering code could interpret strings such as `"left"`, `"dark"`, or `"true"`. Editors should choose a valid option or toggle a setting, not type a magic string. Reserve `content`'s `field.string` for genuinely free-form text, such as headings and descriptions. Enum defaults must match an option key.
+Do not model these choices as `content` fields using `field.string`, even if rendering code could interpret strings such as `"left"`, `"dark"`, or `"true"`. Editors should choose a valid option or toggle a setting, not type a magic string. Reserve `content`'s `field.string` for genuinely free-form text, such as headings and descriptions.
 
 ## Keep formatted text in one field
 
@@ -81,7 +81,7 @@ Use inline formatting and `textStyle`, including highlights, instead of fields s
 
 Follow the [Camox CLI workflow](../camox-cli/SKILL.md) to assign layouts, place blocks, and populate content, including shared navigation/footer content. Don't publish unless asked.
 
-Compare the rendered site with the reference at desktop and mobile sizes. Verify that fields remain editable and that longer text and different repeater counts still work. Fix the reusable implementation, not just the one captured arrangement.
+Compare the rendered site with the reference at desktop and mobile sizes. Verify that fields remain editable and that longer text, empty optional fields, and different repeater counts still work. Fix the reusable implementation, not just the one captured arrangement.
 
 In multi-page runs, give this full check to every page that introduced or changed a definition, and to each page family's representative page. Compare the remaining pages with their source at desktop size. The run is complete when every page in `camoxify-progress.md` is verified.
 

package/dist/features/canvas/canvasInsertionSeams.js

@@ -1,44 +0,0 @@
-//#region src/features/canvas/canvasInsertionSeams.ts
-/** Main block wrappers publish insertion permissions, including layout boundaries.
-* Detached block targets and fields deliberately do not publish this metadata. */
-function readBlockInsertion(element) {
-	const value = element.getAttribute("data-camox-block-insertion");
-	if (!value) return;
-	try {
-		const insertion = JSON.parse(value);
-		if (!insertion || typeof insertion.position !== "string" || typeof insertion.before !== "boolean" || typeof insertion.after !== "boolean" || insertion.afterPosition !== void 0 && insertion.afterPosition !== null && typeof insertion.afterPosition !== "string") return;
-		return insertion;
-	} catch {
-		return;
-	}
-}
-/** Walk boundaries, not blocks: the bottom of one block and the top of its
-* successor describe ONE insertion seam, even when both permit insertion. */
-function canvasInsertionSeams(targets) {
-	const blocks = targets.filter((target) => target.insertion && target.bounds.width > 0 && target.bounds.height > 0);
-	const seams = [];
-	for (let index = 0; index <= blocks.length; index++) {
-		const previous = blocks[index - 1];
-		const next = blocks[index];
-		const anchor = previous?.insertion?.after ? previous : next?.insertion?.before ? next : null;
-		if (!anchor?.insertion) continue;
-		const insertPosition = anchor === previous ? "after" : "before";
-		const { position, afterPosition } = anchor.insertion;
-		const y = previous && next ? (previous.bounds.y + previous.bounds.height + next.bounds.y) / 2 : anchor.bounds.y + (insertPosition === "after" ? anchor.bounds.height : 0);
-		seams.push({
-			key: `${previous?.element.getAttribute("data-camox-block-id") ?? "start"}:${next?.element.getAttribute("data-camox-block-id") ?? "end"}`,
-			x: anchor.bounds.x + anchor.bounds.width / 2,
-			y,
-			request: {
-				type: "CAMOX_ADD_BLOCK_REQUEST",
-				blockPosition: position,
-				insertPosition,
-				...afterPosition !== void 0 ? { afterPosition } : {}
-			}
-		});
-	}
-	return seams;
-}
-
-//#endregion
-export { canvasInsertionSeams, readBlockInsertion };