sygnal 5.4.0 → 6.0.0

package/src/cycle/dom/makeDOMDriver.ts

@@ -1,10 +1,9 @@
 import {Driver} from '../run/types';
-import {init, Module, Options as SnabbdomOptions, VNode, toVNode} from './snabbdom';
+import {init, Module, Options as SnabbdomOptions, VNode} from './snabbdom';
 import xs, {Stream, Listener} from 'xstream';
-import {concat, sampleCombine} from '../../extra/xstreamExtras';
 import {MainDOMSource} from './MainDOMSource';
 import {VNodeWrapper} from './VNodeWrapper';
-import {getValidNode, checkValidContainer} from './utils';
+import {getValidNode, checkValidContainer, POKE, flat} from './utils';
 import defaultModules from './modules';
 import {IsolateModule} from './IsolateModule';
 import {EventDelegator} from './EventDelegator';
@@ -36,17 +35,11 @@ export interface DOMDriverOptions {
   snabbdomOptions?: SnabbdomOptions;
 }
 
-function dropCompletion<T>(input: Stream<T>): Stream<T> {
-  return xs.merge(input, xs.never());
-}
-
 function unwrapElementFromVNode(vnode: VNode): Element {
   return vnode.elm as Element;
 }
 
-function defaultReportSnabbdomError(err: any): void {
-  (console.error || console.log)(err);
-}
+const ERR = 'data-sygnal-error';
 
 function makeDOMReady$(): Stream<null> {
   return xs.create<null>({
@@ -68,11 +61,64 @@ function makeDOMReady$(): Stream<null> {
   });
 }
 
-function addRootScope(vnode: VNode): VNode {
-  vnode.data = vnode.data || {};
-  (vnode.data as any).isolate = [];
-  return vnode;
-}
+// G-456 (D217): the app's first patch adopts markup already in the mount point (server HTML, an
+// Astro island, a Vike page). Its old vnode is built from the DOM with the client's vnode as the
+// template, by position (no toVNode): an element with the client's tag takes the client's
+// selector and key (so component roots and Collection items match), and its data is what the
+// modules need to reach the client's from what the server wrote: the dataset (stale keys go:
+// data-sygnal-ssr), the class as the className prop (the className module drops stale classes),
+// and each attribute the client sets as an attribute or a prop, with the server's value (nothing
+// is written again: an iframe's src isn't reloaded). Any other attribute is removed now; so is a
+// style (G-483: the style module writes the client's declarations, so none of the server's
+// stays). A single text child keeps its text node. Whitespace and comments where the client has
+// no text go; any other node that doesn't match stays as a placeholder that snabbdom replaces
+// with the client's node, in place (the lists stay aligned, so the nodes after it are still
+// adopted). Made again that way, as a fresh render makes them: an element whose selector has a
+// class or id (G-486: `h('p.card')`, the Portal placeholder; patching never corrects them), and
+// one whose hook expects a new element (G-485): a create or init hook (a thunk), an insert hook
+// without a postpatch (a Transition's enter, a measured row, the toaster region, a lazy()
+// placeholder), and any insert hook of the user's own (G-521: with a postpatch too; `u` when a
+// ref, autoFocus or widget chained theirs after it; `s` marks a function chainHooks made)
+const adopt = (e: any, v: any): any => {
+  // (a hole, `{cond && <X/>}`, has no node: snabbdom skips it. G-481: no fragment either, they
+  // are flat by now: their nodes pair with their children in their parent's run)
+  const c = (v.children || []).filter((z: any) => z), out: any[] = [];
+  for (let j = 0, x = e.firstChild, y: any; x; x = y) {
+    const w = c[j], t = x.nodeType, d = w?.data || {}, k = d.hook;
+    // a node that doesn't match stays in its place under a selector no vnode has: snabbdom makes
+    // the client's node before it and removes it (the lists stay aligned: no other node is paired)
+    let n: any = {sel: '', data: {}, elm: x};
+    // G-520: client text vnodes next to each other (`Hello, {name}!`) are one server text node:
+    // it is split by the client's text when that is its start, so the nodes after stay paired
+    t == 3 && c[j + 1]?.text != null && !c[j + 1].sel && w?.text && x.data.startsWith(w.text) && x.splitText(w.text.length);
+    y = x.nextSibling;
+    if (t == 3 && w && !w.sel && w.text != null) n = {text: x.data, elm: x};
+    else if (t == 1 && x.localName == w?.sel && !(k && (k.create || k.init || k.u || k.insert && !(k.postpatch && k.insert.s)))) {
+      const p = d.props || {}, a = d.attrs || {}, o: any = {}, at: any = {}, pr: any = {}, f = x.firstChild;
+      o.class = 'className';
+      for (const m in p) o[m == 'htmlFor' ? 'for' : m.toLowerCase()] = m;
+      // G-482: a data-* attribute the client sets as an attribute isn't in the dataset (the
+      // dataset module would remove it): it goes, and the attributes module writes it again.
+      // G-487: `open` (a <details> the user opened) stays when the client doesn't render it
+      for (const {name: m, value: y} of [...x.attributes])
+        /^data-/.test(m) ? m in a && x.removeAttribute(m)
+        : m in a ? at[m] = y
+        : m == 'open' ? 0
+        : m in o && !d.ns ? pr[o[m]] = y
+        : x.removeAttribute(m);
+      // G-484: a textarea's value no longer follows its text, which goes
+      x.localName == 'textarea' && (x.value = x.value);
+      const s = w.text != null && f?.nodeType == 3 && !f.nextSibling;
+      n = {sel: w.sel, key: w.key, data: {dataset: {...x.dataset}, attrs: at, props: pr}, children: s ? undefined : adopt(x, w), text: s ? f.data : undefined, elm: x};
+    } else if (t != 1 && (t != 3 || !/\S/.test(x.data))) {
+      x.remove();
+      continue;
+    }
+    out.push(n);
+    j++;
+  }
+  return out;
+};
 
 function makeDOMDriver(
   container: string | Element | DocumentFragment,
@@ -86,66 +132,79 @@ function makeDOMDriver(
   const patch = init([isolateModule.createModule() as Partial<Module>].concat(modules), undefined, snabbdomOptions);
   const domReady$ = makeDOMReady$();
   let vnodeWrapper: VNodeWrapper;
-  let mutationObserver: MutationObserver;
-  const mutationConfirmed$ = xs.create<null>({
-    start(listener) {
-      mutationObserver = new MutationObserver(() => listener.next(null));
-    },
-    stop() {
-      mutationObserver.disconnect();
-    },
-  });
 
   function DOMDriver(vnode$: Stream<VNode>, name = 'DOM'): MainDOMSource {
     domDriverInputGuard(vnode$);
     const sanitation$ = xs.create<null>();
 
+    let r: any;
     const firstRoot$ = domReady$.map(() => {
       const firstRoot = getValidNode(container) || document.body;
       vnodeWrapper = new VNodeWrapper(firstRoot);
+      r = {sel: '', data: {isolate: []}, elm: firstRoot};
       return firstRoot;
     });
 
     const rememberedVNode$ = vnode$.remember();
     rememberedVNode$.addListener({});
 
-    mutationConfirmed$.addListener({});
-
-    const elementAfterPatch$ = firstRoot$
+    // P45-C (rec 9, D146): the root element, when the DOM is ready and then after each patch
+    // (it was a MutationObserver on the root's subtree: DOM changes made outside a patch no
+    // longer emit)
+    // G-261: and when Sygnal changes the DOM outside a patch (a Transition's leave, a Portal
+    // mounted late): an event that bubbles up to the root. G-276: on the current root (a patch
+    // can replace the first one). G-277: the innermost app's root takes it (a nested app or
+    // custom element doesn't re-emit the outer app's DOM source)
+    let pl: any, cur: any;
+    const poke = (e: Event) => pl && (e.stopPropagation(), pl.next(cur));
+    const off = () => cur?.removeEventListener(POKE, poke);
+    // G-545: run() gives any DOM driver its reporter (onError, phase 'patch') on the isolate
+    // module; an explicit reportSnabbdomError comes first
+    const rep = (e: any) => (options.reportSnabbdomError || (isolateModule as any).rep || console.error)(e);
+    let dead = 0, end = 0;
+    const rootElement$ = firstRoot$
       .map(
-        firstRoot =>
-          xs
-            .merge(rememberedVNode$.endWhen(sanitation$), sanitation$)
-            .map(vnode => vnodeWrapper.call(vnode))
-            .startWith(addRootScope(toVNode(firstRoot)))
-            .fold(patch, toVNode(firstRoot))
-            .drop(1)
-            .map(unwrapElementFromVNode)
-            .startWith(firstRoot as any)
-            .map(el => {
-              mutationObserver.observe(el, {
-                childList: true,
-                attributes: true,
-                characterData: true,
-                subtree: true,
-                attributeOldValue: true,
-                characterDataOldValue: true,
-              });
-              return el;
-            })
-            .compose(dropCompletion)
+        (firstRoot, P = (o: any, v: any) => (v = flat(v), patch(o == r ? (cur.removeAttribute?.(ERR), {...r, sel: v.sel, key: v.key, children: adopt(firstRoot, v)}) : o, v))) =>
+          xs.merge(
+            xs
+              .merge(rememberedVNode$.endWhen(sanitation$), sanitation$.map(() => (end = 1, null)))
+              .map(vnode => vnodeWrapper.call(vnode))
+              // the first step gives the root its scope; the second, the app's first patch,
+              // adopts the markup in it (G-456). The root keeps its own attributes (G-466)
+              .startWith(r)
+              // G-540: a patch that throws (a hook, a module) is reported once, and the app's DOM
+              // stops updating: snabbdom stopped half way (some elements patched, created or
+              // removed, the rest not; insert hooks not run), and no vnode tree matches that DOM
+              // (patching on from either tree, or adopting the DOM again, left wrong or duplicated
+              // DOM). The stream doesn't end (its events, the root element), and a patch to no
+              // children (dispose) still runs, so what the last good tree mounted (a Portal's
+              // content) is removed; its errors aren't reported again. G-549: only dispose (`end`:
+              // the sanitation signal), not a live render that has no children. G-543 (D224): the
+              // root element is marked data-sygnal-error="patch" while its DOM is stopped (CSS can
+              // show it; dispose removes it). G-550: marked before the error is reported (onError
+              // can read it); the first patch clears a mark a failed, undisposed app left in the
+              // container, and dispose removes it only when this app set it; a throw while
+              // flattening the tree (a key JSON.stringify can't take) is a patch error too (P
+              // flattens). A DocumentFragment mount point has no attributes: no mark
+              .fold((o: any, v: any) => {
+                if (!dead || end) try { o = P(o, v) } catch (e) { dead++ || (cur.setAttribute?.(ERR, 'patch'), rep(e)) }
+                end && dead && cur.removeAttribute?.(ERR)
+                return o
+              }, {...r, data: {}})
+              .drop(1)
+              .map(unwrapElementFromVNode)
+              .startWith(firstRoot as any)
+              .map((el: any) => (off(), el.addEventListener(POKE, poke), cur = el)),
+            // never completes (nor does the root element). G-285: the listener moves with the
+            // root and goes when the app stops (a disposed app's driver isn't kept by its root)
+            xs.create<any>({start: l => pl = l, stop: () => (pl = 0, off())})
+          )
       )
-      .flatten();
-
-    const rootElement$ = concat(domReady$, mutationConfirmed$)
+      .flatten()
       .endWhen(sanitation$)
-      .compose(sampleCombine(elementAfterPatch$))
-      .map(arr => arr[1])
       .remember();
 
-    rootElement$.addListener({
-      error: options.reportSnabbdomError || defaultReportSnabbdomError,
-    });
+    rootElement$.addListener({error: rep});
 
     const delegator = new EventDelegator(rootElement$, isolateModule);
 

package/src/cycle/dom/mockDOMSource.ts

@@ -95,7 +95,15 @@ export class MockedDOMSource {
     return out;
   }
 
-  public select(selector: string): MockedDOMSource {
+  public select(selector: any): MockedDOMSource {
+    // CT-1: a control selects by its marker; a component (any other function) is rejected
+    // like the real DOM source does (SYG124 in the dev entry names the fixes)
+    if (typeof selector == 'function') {
+      if (!selector.__sygnalControl) {
+        throw new Error(`DOM driver's select() expects the argument to be a string as a CSS selector`);
+      }
+      selector = '' + selector;
+    }
     const mockConfigForSelector = this._mockConfig[selector] || {};
 
     return new MockedDOMSource(
@@ -113,6 +121,18 @@ export class MockedDOMSource {
     return source.select('.' + SCOPE_PREFIX + scope);
   }
 
+  /**
+   * PLAN-4.6: isolateSink for one vnode (a copy, with the scope class). 4-I G-558: a fragment (a
+   * Collection's, `<>…</>`) has no element: each of its top-level elements gets the class (as the
+   * real driver's scoped()); a text vnode is left as it is
+   */
+  public isolateValue(vnode: any, scope: string): any {
+    // G-305: the scope's class token exactly (scope s1 is not s14)
+    return !vnode || typeof vnode != 'object' ? vnode
+      : !vnode.sel ? (vnode.children ? {...vnode, children: vnode.children.map((c: any) => this.isolateValue(c, scope))} : vnode)
+      : vnode.sel.split('.').indexOf(SCOPE_PREFIX + scope) > 0 ? vnode : {...vnode, sel: vnode.sel + `.${SCOPE_PREFIX}${scope}`};
+  }
+
   public isolateSink(sink: any, scope: string): any {
     return adapt(
       xs.fromObservable<any>(sink).map((vnode: VNode) => {

package/src/cycle/dom/modules.ts

@@ -1,19 +1,32 @@
-import {Module, classModule, propsModule, attributesModule, datasetModule} from './snabbdom';
+import {Module, classModule, attributesModule, datasetModule} from './snabbdom';
 import {styleModule} from './styleModule';
 import {selectModule} from './selectModule';
 import {controlledInputModule} from './controlledInputModule';
 import {classNameModule} from './classNameModule';
+import {propsModule} from './propsModule';
+import {isField} from './controlledInputModule';
+import {sameData} from './utils';
 
-const modules: Array<Module> = [
+const list: Array<Module> = [
   styleModule,
   classModule,
-  propsModule,
+  propsModule, // Sygnal's: also clears removed and nullish props (B-015, G-109)
   classNameModule, // after propsModule (B-012)
   attributesModule,
   datasetModule,
   selectModule,
   controlledInputModule,
 ];
+// P46-P: one update hook for these modules, in their order. A vnode whose data is the same as
+// last time (each bucket shallow-equal) needs none of them, unless it is a form field (the
+// controlled-input and select modules re-sync it every patch)
+const ups = list.map(m => m.update!);
+const modules: Array<Module> = list.map(({update, ...m}) => m as Module).concat({
+  update(o: any, v: any) {
+    if (!isField(v) && sameData(o.data, v.data)) return;
+    for (let i = 0; i < ups.length; i++) ups[i](o, v);
+  },
+} as Module);
 
 export {styleModule, classModule, propsModule, attributesModule, datasetModule, selectModule, controlledInputModule, classNameModule};
 

package/src/cycle/dom/propsModule.ts

@@ -0,0 +1,65 @@
+/**
+ * Sygnal's props module: snabbdom's propsModule, plus clearing removed and
+ * nullish props (B-015, G-109).
+ *
+ * Problem: snabbdom's propsModule writes new and changed props but never
+ * unsets a prop that disappears, so a reused element keeps `title`, `disabled`,
+ * `href`, ... from the previous render. A nullish prop is written as the
+ * string "undefined"/"null" (`title={cond ? 'x' : undefined}`, `src={null}`).
+ *
+ * Fix: write new and changed props except nullish ones (G-109: nothing is ever
+ * written as "null"). For each prop that is gone (or became nullish), remove
+ * the reflected attribute, which resets the property (numbers such as
+ * maxLength fall back to their default too). Without such an attribute, reset
+ * the property by its current type (boolean -> false, string -> '', other
+ * non-number -> undefined/null) if it differs (G-095). `className` is left
+ * to classNameModule (B-012). On form fields a nullish `value`/`checked` clears
+ * the field ('' / false, D49); a removed one is left alone (the controlled-input
+ * module owns them; removing them hands control back to the user, as in React).
+ */
+
+import type {VNode} from 'snabbdom/build/vnode.js';
+
+function clearProp(elm: any, key: string, nullish?: boolean): void {
+  if (key === 'className') return;
+  if (/^(value|checked)$/.test(key) && /^(INPUT|TEXTAREA|SELECT)$/.test(elm.tagName)) {
+    const empty = key === 'value' ? '' : false;
+    if (nullish && elm[key] !== empty) elm[key] = empty;
+    return;
+  }
+  const attr = key === 'htmlFor' ? 'for' : key.replace(/^aria(?=[A-Z])/, 'aria-').toLowerCase();
+  // G-095: a reflected attribute is just removed, which resets the property. Writing it first
+  // (src = '') would queue an img/video error event or navigate an iframe to about:blank.
+  if (elm.hasAttribute?.(attr)) return elm.removeAttribute(attr);
+  const cur = elm[key];
+  const t = typeof cur;
+  const reset = t === 'boolean' ? false : t === 'string' ? '' : cur === null || t === 'function' ? null : undefined;
+  try {
+    // numbers (maxLength, ...) are left to their default; unchanged values aren't rewritten
+    if (t !== 'number' && cur !== reset) elm[key] = reset;
+  } catch (_) {
+    // e.g. contentEditable rejects ''
+  }
+}
+
+function updateProps(oldVnode: VNode, vnode: VNode): void {
+  const elm: any = vnode.elm;
+  const props: any = vnode.data?.props || {};
+  const oldProps: any = oldVnode.data?.props || {};
+  if (!elm || oldProps === props) return;
+  for (const key in oldProps) {
+    if (!(key in props)) clearProp(elm, key);
+  }
+  for (const key in props) {
+    const cur = props[key];
+    if (cur === oldProps[key]) continue;
+    // a nullish className is left to classNameModule, which rebuilds the attribute (B-012)
+    if (cur == null) clearProp(elm, key, true);
+    // G-553: on create (no old sel) `value` is always written: the create hooks run before the
+    // children are appended, so an <option>'s value reads '' (no text yet) and value="" would be
+    // skipped, leaving no attribute (the option then submits its label)
+    else if (key !== 'value' || elm[key] !== cur || !oldVnode.sel) elm[key] = cur;
+  }
+}
+
+export const propsModule = {create: updateProps, update: updateProps};

package/src/cycle/dom/selectModule.ts

@@ -1,33 +1,38 @@
 /**
- * Snabbdom module that fixes <select> value assignment.
+ * Snabbdom module that applies a <select>'s `value` after its <option>s exist.
  *
- * Problem: snabbdom's createElm() fires the propsModule create hook
- * (which sets elm.value) BEFORE appending child <option> elements.
- * The browser silently ignores the value assignment because no matching
- * option exists yet, so <select> always shows the first option.
+ * Problem: snabbdom runs the module create/update hooks (propsModule sets
+ * elm.value) BEFORE it creates or patches the element's children. When the
+ * matching <option> is new in this patch, the browser ignores the value and
+ * the <select> shows the first option. On create that is every <select>; on
+ * update it is a value change together with an options change (B-017).
  *
- * Fix: collect <select> elements that have a value prop during create,
- * then re-apply the value in the post hook (after all elements and
- * children have been inserted).
+ * Fix: collect <select> elements with a value prop during create and update,
+ * then re-apply the value in the post hook, after all children are patched.
  */
 
 import type {VNode} from 'snabbdom/build/vnode.js';
+import {isField} from './controlledInputModule';
 
 let pendingSelects: Array<{elm: HTMLSelectElement; value: any}> = [];
 
-function createSelect(_oldVnode: VNode, vnode: VNode): void {
-  const elm = vnode.elm as Element;
-  if (elm && elm.tagName === 'SELECT' && vnode.data?.props?.value !== undefined) {
-    pendingSelects.push({elm: elm as HTMLSelectElement, value: vnode.data.props.value});
+function queueSelect(_oldVnode: VNode, vnode: VNode): void {
+  // P45-A: a form field by the vnode's tag first; most vnodes aren't
+  if (!isField(vnode)) return;
+  const elm = vnode.elm as HTMLSelectElement;
+  const value = vnode.data?.props?.value;
+  if (elm && elm.tagName === 'SELECT' && value != null) {
+    pendingSelects.push({elm, value});
   }
 }
 
 function postPatch(): void {
-  for (let i = 0; i < pendingSelects.length; i++) {
-    const {elm, value} = pendingSelects[i];
-    elm.value = value;
-  }
+  const list = pendingSelects;
   pendingSelects = [];
+  for (let i = 0; i < list.length; i++) {
+    const {elm, value} = list[i];
+    if (elm.value !== String(value)) elm.value = value;
+  }
 }
 
-export const selectModule = {create: createSelect, post: postPatch};
+export const selectModule = {create: queueSelect, update: queueSelect, post: postPatch};

package/src/cycle/dom/snabbdom.ts

@@ -13,14 +13,9 @@
 export {h, fragment as HFragment} from 'snabbdom/build/h.js';
 export {init} from 'snabbdom/build/init.js';
 export type {Options} from 'snabbdom/build/init.js';
-export {toVNode} from 'snabbdom/build/tovnode.js';
 export {vnode} from 'snabbdom/build/vnode.js';
 export type {VNode, VNodeData} from 'snabbdom/build/vnode.js';
-import {Fragment as _Fragment} from 'snabbdom/build/jsx.js';
-
-// Tag Fragment so we can identify it even after minification mangles Function.name
-(_Fragment as any).__sygnalFragment = true;
-export const Fragment = _Fragment;
+export {Fragment} from './fragment';
 
 // Module type
 export type {Module} from 'snabbdom/build/modules/module.js';

package/src/cycle/dom/thunk.ts

@@ -1,4 +1,5 @@
 import {h, VNode, VNodeData} from './snabbdom';
+import {flat} from './utils';
 
 export interface ThunkData extends VNodeData {
   fn(): VNode;
@@ -10,6 +11,8 @@ export interface Thunk extends VNode {
 }
 
 function copyToThunk(vnode: VNode, thunkVNode: Thunk): void {
+  // (rendered during the patch: its fragments are flattened here, as the DOM driver does)
+  vnode = flat(vnode);
   thunkVNode.elm = vnode.elm;
   (vnode.data as ThunkData).fn = thunkVNode.data.fn;
   (vnode.data as ThunkData).args = thunkVNode.data.args;

package/src/cycle/dom/utils.ts

@@ -86,3 +86,101 @@ export function makeInsert(
     }
   };
 }
+
+// G-261: a DOM change Sygnal makes outside a patch (a Transition's leave, a Portal mounted late)
+// re-emits the DOM source of the app whose root contains `el` (makeDOMDriver listens on its root)
+export const POKE = 'sygnal-dom';
+export const pokeDOM = (el: any): any => el?.dispatchEvent(new Event(POKE, {bubbles: true}));
+
+const obj = (o: any) => o !== null && typeof o == 'object' && !Array.isArray(o);
+/**
+ * P46-P: two vnodes' data are the same for the DOM modules: the same keys, each value identical
+ * or a shallow-equal object (a module bucket: props, attrs, class, dataset, style, ...)
+ */
+export function sameData(a: any, b: any): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  let n = 0;
+  for (const k in a) {
+    n++;
+    const x = a[k], y = b[k];
+    if (x !== y) {
+      if (!obj(x) || !obj(y)) return false;
+      let m = 0;
+      for (const j in x) { m++; if (x[j] !== y[j]) return false; }
+      for (const _ in y) m--;
+      if (m) return false;
+    }
+  }
+  for (const _ in b) n--;
+  return !n;
+}
+
+// G-517 / G-518 / G-522: snabbdom never sees a fragment. Before each patch, a fragment's children
+// (through nested ones) are spliced into its parent's children, so they are diffed, moved and
+// adopted at hydration as the parent's own (snabbdom's fragment bounds went stale: an insert into
+// one landed at the parent's end, a keyed one never moved, a later patch threw NotFoundError).
+// The children of a keyed fragment (a Collection item, a component's root) take its key and their
+// own key, else their tag and its count among them: they move with it and stay apart from another
+// item's. G-541: no two paths give the same key (a '/' separator did: fragment "src" + "a/b.ts" and
+// fragment "src/a" + "b.ts"). 3-W G-544: each segment is a JSON string (the key as a string) or
+// array ([tag, count], always last), which ends where it ends, appended to the prefix
+// (`"src""a/b.ts"`): a key grows linearly with the nesting (JSON in JSON doubled at each level),
+// and any key String() takes is fine (G-548: a BigInt; two Symbols with the same description share
+// a key; a number key and its string are one key, as in snabbdom). A vnode with no fragment below is kept by identity, as is one already
+// flattened (a cached subtree), so snabbdom still skips unchanged subtrees; so are a keyed
+// fragment's copies while the fragment and its prefix are the same (G-539; a hit compares the
+// parent's prefix, the fragment's own is made on a miss). A hoisted keyed fragment rendered in two
+// places shares its copies, as any hoisted vnode shares its object (render it once). A copy (a
+// parent with new children, a child with a new key) has its vnode's fields and writes its
+// element there too, so the app's vnodes get their `elm` as before (testing and diagnostics read
+// it); it keeps its own (a vnode object reused under another key: the old copy removes its own).
+const flatOf = new WeakMap<any, any>();
+const cpOf = new WeakMap<any, any>();
+// 4-I G-561: a copy is an instance of one class (the vnode's own fields, `elm` an accessor on its
+// prototype), not Object.create(y) with an own accessor: snabbdom's patch loop read each field
+// through the prototype chain and called a per-object accessor, ~3x slower over a 1k Collection.
+// (y: set again after the fields, as a copy's own y is its vnode's vnode; m starts as the vnode's
+// elm, which snabbdom replaces before reading it)
+class Copy {
+  y: any; m: any
+  constructor(y: any, o: any) { this.y = y; Object.assign(this, y, o).y = y }
+  get elm() { return this.m }
+  set elm(e: any) { this.y.elm = this.m = e }
+}
+const seg = (k: any, s: any) => (k || '') + JSON.stringify(typeof s == 'object' ? s : String(s));
+export const flat = (v: any): any => {
+  if (!v || v.$p || !v.children) return v;
+  let r = flatOf.get(v);
+  if (!r) {
+    const o: any[] = [];
+    let d = 0;
+    // (m, s: locals of each call)
+    const put = (c: any[], k?: string, n: any = {}, m?: any, s?: any) => {
+      for (const x of c) {
+        // G-539: a keyed fragment's copies are kept per (fragment, prefix), in flatOf (flat() never
+        // takes a fragment): an unchanged one (a Collection item that didn't render again) gives
+        // snabbdom the same vnodes
+        if (x && !x.sel && x.children) d = 1, x.key == null ? put(x.children, k, n)
+          : (m = flatOf.get(x)) && m[0] === k ? o.push(...m[1])
+          : (s = o.length, put(x.children, seg(k, x.key)), flatOf.set(x, [k, o.slice(s)]));
+        else {
+          let y = flat(x);
+          y !== x && (d = 1);
+          if (k && y) {
+            // 4-H: the copy of an unchanged child under the same key is kept (the fragment is new
+            // when one of its children is: a Collection's), so snabbdom skips the others. 4-I
+            // G-561: a hit compares the prefix and the child's own part (its key, else its count),
+            // so the key is only built on a miss
+            const s = y.key ?? (n[y.sel] = -~n[y.sel]), c = cpOf.get(y);
+            y = c && c[0] === k && c[1] === s ? c[2] : (cpOf.set(y, [k, s, y = new Copy(y, {key: seg(k, y.key ?? [y.sel, s])})]), y);
+          }
+          o.push(y);
+        }
+      }
+    };
+    put(v.children);
+    flatOf.set(v, r = d ? new Copy(v, {children: o}) : v);
+  }
+  return r;
+};

package/src/cycle/dom/viewTransition.ts

@@ -0,0 +1,43 @@
+import xs, {Stream} from 'xstream';
+import type {VNode} from './snabbdom';
+
+/**
+ * PLAN-4 GS-12 (D129): the patch that something asked for runs inside
+ * `document.startViewTransition()`. The ask is `flags().vt`, set by the core when a component's
+ * `viewTransitions` action changes state (on the app's IsolateModule, so it is per app).
+ *
+ * - No API, or `prefers-reduced-motion: reduce`, or the first render: patched at once.
+ * - P45-C: one action is one patch (the app's render scheduler flushes every component, a
+ *   Collection move included, into one), so the update callback patches with the latest vnode
+ *   that arrived before the browser called back, and is done once that patch is (no quiet
+ *   window: it was 20 ms, capped at 200 ms, for the several patches of a move).
+ * - A new transition while one animates: the browser skips the running one (it jumps to its end).
+ * - G-489: a skipped transition's `ready` rejection is handled (no uncaught InvalidStateError).
+ */
+export function viewTransition$(vnode$: Stream<VNode>, flags: () => any): Stream<VNode> {
+  const g: any = globalThis, out$ = xs.create<VNode>();
+  let held: VNode[] | 0 = 0, first = 1;
+  return xs.merge(vnode$.filter(v => {
+    const f = flags() || {}, d = g.document, want = f.vt && !first;
+    // the first render has no old view to transition from (a ROUTE reply at start asks too)
+    f.vt = first = 0;
+    if (held) return held[0] = v, false;
+    if (!want || !d?.startViewTransition || g.matchMedia?.('(prefers-reduced-motion: reduce)').matches) return true;
+    held = [v];
+    const update = () => {
+      const h = held as VNode[];
+      held = 0;
+      out$.shamefullySendNext(h[0]);
+    };
+    try {
+      // G-489: a transition the browser skips (duplicate names, a newer one) rejects `ready`:
+      // handled (the update still runs; `finished` / `updateCallbackDone` reject only when it throws).
+      // (a stand-in without `ready` must not throw here: the update would run twice)
+      d.startViewTransition(update)?.ready?.catch(Object);
+    } catch (_) {
+      // the browser refused (e.g. an invalid state): patch now
+      update();
+    }
+    return false;
+  }), out$);
+}

package/src/cycle/state/StateSource.ts

@@ -3,6 +3,7 @@ import {dropRepeats} from '../../extra/xstreamExtras';
 import {DevToolEnabledSource} from '../run/types';
 import {adapt} from '../run/adapt';
 import {Getter, Setter, Scope, Reducer} from './types';
+import {objIsEqual} from './objIsEqual';
 
 function updateArrayEntry<T>(
   array: Array<T>,
@@ -87,9 +88,13 @@ export class StateSource<S> {
   public stream: MemoryStream<S>;
   private _stream: MemoryStream<S>;
   private _name: string;
+  private _end?: Stream<any>;
 
-  constructor(stream: Stream<S>, name: string) {
-    this._stream = stream
+  // raw (P45-D): `stream` is another StateSource's stream mapped, already without undefined and
+  // repeats (a component's own source), so one stream instead of four
+  constructor(stream: Stream<S>, name: string, end?: Stream<any>, raw?: any) {
+    this._end = end;
+    this._stream = raw ? stream.remember() : stream
       .filter(s => typeof s !== 'undefined')
       .compose(dropRepeats())
       .remember();
@@ -105,7 +110,18 @@ export class StateSource<S> {
    */
   public select<R>(scope: Scope<S, R>): StateSource<R> {
     const get = makeGetter(scope);
-    return new StateSource<R>(this._stream.map(get) as Stream<R>, this._name);
+    // G-214: keeps the end stream, so a selected source's watch() also ends on dispose
+    return new StateSource<R>(this._stream.map(get) as Stream<R>, this._name, this._end);
+  }
+
+  /**
+   * PLAN-4 GS-6: selector(state) whenever it changes structurally (objIsEqual). The current
+   * value is the baseline, not a change, unless { immediate: true }. Ends with the state stream
+   * or, for a component's own STATE source, when the component is disposed
+   */
+  public watch<R>(selector: (state: S) => R, {immediate}: {immediate?: boolean} = {}): Stream<R> {
+    const s$ = this._stream.map(selector).compose(dropRepeats(objIsEqual)).endWhen(this._end || xs.never());
+    return immediate ? s$ : s$.drop(1);
   }
 
   public isolateSource = isolateSource;