camox 0.68.0 → 0.71.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "camox",
-  "version": "0.68.0",
+  "version": "0.71.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.68.0",
-    "@camox/cli": "0.68.0",
-    "@camox/ui": "0.68.0"
+    "@camox/api-contract": "0.71.0",
+    "@camox/cli": "0.71.0",
+    "@camox/ui": "0.71.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/references/artifacts.md

@@ -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: