@uniweb/runtime 1.3.3 → 1.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
@@ -44,7 +44,7 @@
     "esbuild": "^0.21.0 || ^0.23.0 || ^0.24.0 || ^0.25.0 || ^0.27.0 || ^0.28.0",
     "vite": "^7.3.1",
     "vitest": "^4.1.7",
-    "@uniweb/build": "1.13.1"
+    "@uniweb/build": "1.13.6"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/carry-animations.js

@@ -0,0 +1,50 @@
+/**
+ * A page's CSS animations carry on across the browser's first render.
+ *
+ * ⭐ The browser renders over a prerendered page rather than hydrating it (`createRoot`, `index.jsx`),
+ * and a CSS animation's clock belongs to its element. So the commit that replaces the page restarts
+ * every animation in it, and a page's first commit usually lands while its entrance is still running:
+ * a hero already on screen would drop back to invisible and play again. `uniweb dev` never prerenders,
+ * so a foundation's author never sees it.
+ *
+ * Each animation of the new page takes as its start the moment the old page was first painted, which
+ * is when its twin started, so it goes on from where its twin was. The observer fires after the commit
+ * and before the browser paints, so no frame shows a restart. It disconnects at that first commit, so
+ * a later navigation is left as it was.
+ *
+ * ⭐ The time of first paint rather than the old animations' own start times, read before the commit:
+ * an animation that has ended with no fill is gone from `getAnimations()`, and its twin would play
+ * again.
+ *
+ * ⛔ Only a running animation on the document's timeline:
+ * - a paused one is waiting for something, like a reveal that starts when its section scrolls into
+ *   view, and setting a start time would start it;
+ * - a scroll-driven one has a timeline of its own, whose time is no moment on this clock.
+ *
+ * It reaches CSS animations alone. One a component starts from JavaScript when it mounts never ran on
+ * the prerendered page: it starts at boot, over whatever that page has shown by then.
+ *
+ * Nothing to carry: an empty root (`uniweb dev`, a page served without a prerender), and a page not
+ * painted yet, whose first render is the first thing a visitor sees. That can include a page painted
+ * a frame ago, which the browser has not reported yet: its animations have hardly begun.
+ *
+ * @param {Element} root - The element React is about to render into.
+ */
+export function carryAnimations(root) {
+  if (!root.firstChild || !document.getAnimations) return
+  new MutationObserver((_, watch) => {
+    watch.disconnect()
+    const painted = performance.getEntriesByName('first-contentful-paint')[0]?.startTime
+    if (painted == null) return
+    for (const animation of document.getAnimations()) {
+      if (
+        animation.animationName &&
+        animation.playState === 'running' &&
+        animation.timeline === document.timeline &&
+        root.contains(animation.effect?.target)
+      ) {
+        animation.startTime = painted
+      }
+    }
+  }).observe(root, { childList: true })
+}

package/src/index.jsx

@@ -12,6 +12,7 @@ import { initUniweb, decodeData } from './setup.js'
 import { wireTracker } from './wire-foundation.js'
 import { loadFoundation, loadExtensions } from './foundation-loader.js'
 import { initAppearance } from './appearance.js'
+import { carryAnimations } from './carry-animations.js'
 import RuntimeProvider from './RuntimeProvider.jsx'
 
 /**
@@ -146,6 +147,8 @@ async function initRuntime(foundationSource, options = {}) {
 
     const app = <RuntimeProvider basename={routerBasename} development={development} />
 
+    // Armed before the render it watches for: the one that replaces a prerendered page.
+    carryAnimations(container)
     createRoot(container).render(app)
 
     // Log success

package/src/wire-foundation.js

@@ -17,26 +17,31 @@
  * the DOM, the per-page render loop — stay in the per-environment
  * entries; these helpers cover only the environment-agnostic L2 work.
  *
- * Keeping this file React-free matters for the SPA bundle: `setup.js`
- * pulls `wire-foundation.js` directly, but it must NOT transitively
+ * What this file keeps out of the SPA bundle is `react-dom/server`, not
+ * React: `FallbackRef` below is `React.createElement` alone. `setup.js`
+ * pulls `wire-foundation.js` directly, so this file must NOT transitively
  * pull `ssr-renderer.js` (which imports `react-dom/server`). The L2
  * helpers therefore live here, while the L3-composing
  * `initPrerenderForLocale` lives in `ssr-renderer.js`.
  *
  * Adding a new framework-level capability:
- *   1. Read the foundation declaration via `foundation.default.capabilities.<name>`.
- *   2. Apply it to the uniweb singleton (set a slot, call a build hook,
+ *   1. Name it in `extractFoundationRuntime`'s lists (`@uniweb/build`'s
+ *      `src/runtime-schema.js`): the built entry carries only what they
+ *      name, so anything else never reaches this file.
+ *   2. Read the foundation declaration via `foundation.default.capabilities.<name>`.
+ *   3. Apply it to the uniweb singleton (set a slot, call a build hook,
  *      register something on `activeWebsite`).
- *   3. Provide a runtime fallback if the capability is one foundations
+ *   4. Provide a runtime fallback if the capability is one foundations
  *      may legitimately not declare (see `FallbackRef`).
  *
  * Foundation export shape contract: the runtime always loads the
  * **built** foundation artifact (`dist/entry.js`) via
  * `loadFoundation()` in `foundation-loader.js`, which does `import(url)`
  * and returns a module namespace. The build pipeline
- * (`@uniweb/build`'s `src/generate-entry.js`) wraps the foundation's
- * source default export under `default.capabilities.*`, so the runtime
- * sees a single canonical shape with no need for fallback chains. This
+ * (`@uniweb/build`'s `src/generate-entry.js`) writes what the runtime
+ * reads of the foundation's source default export into
+ * `default.capabilities.*`, so the runtime sees a single canonical shape
+ * with no need for fallback chains. This
  * differs from `@uniweb/press` / `@uniweb/unipress`,
  * which DO need to handle a second shape because they're sometimes
  * called from inside a foundation bundle (where the foundation imports