sygnal 5.3.7 → 6.0.0

package/src/extra/form.ts

@@ -0,0 +1,268 @@
+/*
+ * PLAN-5 F-1 (D193): the `form` behavior, the canonical form recipe.
+ *
+ *   Signup.uses = { form: form(signupSchema, {
+ *     values: { email: '', password: '', addresses: [{ id: 1, street: '', city: '' }] },
+ *     submit: 'SIGN_UP',             // the host action a valid submit dispatches (data: the schema's output)
+ *     check: { email: { request: (email) => ({ url: '/api/email-free', query: { email } }), error: (body) => !body.free && 'Taken' } },
+ *   }) }
+ *
+ * Fields are addressed by their `name=` attribute (the path in `values`; rows of an array by
+ * id: `addresses.7.street`), heard on the form element (option `form`, default 'form'): input
+ * and focusout bubble to it, also from fields rendered by Collection items. Nothing is wired per
+ * field.
+ *
+ * Options: `values` (the start values; D239: or a function of the host's state, called when the
+ * form starts), `submit` (host action), `check` (async per-field checks through a driver: a
+ * request with a reply action, `latest`), `show` ('blur' default: a schema error shows once its
+ * field was blurred; 'input'; 'submit'), `form` (selector), `http` (the driver sink of the
+ * checks, 'HTTP'), `resetOnShow` (D239).
+ *
+ * D239 (G-578): `resetOnShow: true` starts the form over (the start values, as a new form: touched,
+ * errors, server errors, checks and the submit state cleared) each time it is shown: when its
+ * host starts (VALIDATE: a component mounted again, a Switchable page made again for another
+ * `instance`, a slice kept in the parent's state) and each time the form element appears again
+ * in the host's DOM after being absent (a Switchable page shown again: hidden pages stay alive;
+ * a form rendered conditionally). Re-renders while it is shown keep what the user typed. Off by
+ * default: a wizard step keeps its values when the user comes back. Without a real DOM (the mock
+ * DOM, SSR) only the host start counts. A `values` function is called with the host's state at
+ * each start over (without resetOnShow: once, when the host starts with the slice untouched);
+ * before that (a child's first render) the fields come from calling it with a blank state.
+ *
+ * Slice (state.form): values, initial, errors (all current schema errors by name), touched,
+ * server (server errors), remote (async check results: '' passed), pending (name -> value being
+ * checked), submitting, submitted, submitCount, queued (a submit waits for a check or an async
+ * schema), validating (an async schema runs), validated (the schema has answered since the start
+ * or the last reset); calculated: fields (per name: { name, value, error, invalid, touched,
+ * dirty, pending }; `error` is what to show), valid (G-382: the last answer's, kept while an async
+ * schema re-validates), dirty, error (form-level message).
+ *
+ * Actions: form.CHANGE ({ name, value, item? }: G-376: a checkbox gives `checked`, and `item`, its
+ * value, which toggles membership when the field is an array; <select multiple> an array of the
+ * selected values; type=file is ignored), form.BLUR (name), form.SUBMIT, form.ADD ({ field,
+ * value }), form.REMOVE ({ field, id }), form.ERRORS (an error reply or a map: server errors),
+ * form.DONE (saved), form.RESET (values?); internal: form.RESULT (an async schema's result),
+ * form.CHECKED_<name> (a check's reply; a failed check passes: the server checks on submit),
+ * form.VALIDATE (the first validation, when the host starts: G-375; `valid` is false until the
+ * schema answered; with resetOnShow also each time the form element appears, D239).
+ *
+ * G-575 (D236): a valid submit is `submitting` (until form.DONE / form.ERRORS, a second submit
+ * dropped) only when the host's submit entry has the `http` sink; any other submit (STATE, PARENT,
+ * EVENTS, EFFECT, ...) sends no request and is done at once (submitted, as form.DONE would). A
+ * slice kept in parent state from a host that unmounted mid-submit starts unstuck: VALIDATE (each
+ * host start) clears submitting, queued and pending.
+ *
+ * Each action is one step function, `(slice, data, key) => outcome | null` (null: no change),
+ * the outcome `{ s: new slice, focus: ELEMENT command, req: a check request, send: 1 (dispatch
+ * submit), wait: { values, submit? } (an async schema to await) }`. Its sinks (STATE, EFFECT,
+ * ELEMENT, and the checks' driver) read that outcome, computed once per (slice, data). D197:
+ * the handlers get the `uses` key, which names the reply actions.
+ *
+ * Dev diagnostics (checks/forms.ts, through the core bridge's `form` hook; nothing in
+ * production): SYG230 a field name not in values, SYG231 not a Standard Schema (throws), SYG232
+ * a submit dropped, SYG233 a values key missing from the schema's output, SYG234 a submit that
+ * dispatched one of the form's own actions (G-577), SYG235 a check request that sets reply
+ * fields. The host checks (SYG234 submit, SYG235 check names, SYG236 row ids)
+ * run when the host is created.
+ */
+import xs from './xstreamCompat'
+import {defineBehavior} from './behaviors'
+import {ABORT} from '../shared'
+import {isStandardSchema} from './standardSchema'
+import {checkForm, fieldNames, getField, hasField, setField, replyErrors, focusInvalid} from './formHelpers'
+
+const dev = (...a: any[]): any => (globalThis as any).__SYGNAL_DIAGNOSTICS__?.form?.(...a)
+const keys = (o: any) => Object.keys(o).filter(k => o[k])
+const drop = (o: any, p: string) => {
+  const r: any = {}
+  for (const k in o) if (k != p && !k.startsWith(p + '.')) r[k] = o[k]
+  return r
+}
+
+export const form = (schema: any, o: any = {}): any => {
+  isStandardSchema(schema) || dev(231, schema)
+  const {values: vo = {}, submit, check: checks = {}, show = 'blur', http = 'HTTP', form: sel = 'form', resetOnShow: again} = o
+  // D239: `values` can be a function of the host's state, called when the form starts (and each
+  // show, resetOnShow). Before that (the host's first render, before its first action) the
+  // fields come from calling it with a blank state: every read gives '' in the result
+  const fn = typeof vo == 'function', B: any = new Proxy(() => B, {get: (_, k) => k == Symbol.toPrimitive ? () => '' : B})
+  const clean = (x: any): any => x === B ? '' : Array.isArray(x) ? x.map(clean) : x && typeof x == 'object' ? Object.fromEntries(Object.entries(x).map(([k, y]) => [k, clean(y)])) : x
+  let values: any = vo
+  if (fn) try { values = clean(vo(B)) } catch (_) { values = {} }
+  const cache = new WeakMap(), checked = Object.keys(checks)
+  // G-575: a submit is pending (until form.DONE / form.ERRORS) only when the host's submit entry
+  // sends a request on the `http` sink; any other submit is done once its entry has run. Set when
+  // the form merges into its host
+  let req = true
+  // the schema's result, once per values object; an async one replaces its Promise when it settles
+  const v = (vals: any): any => {
+    let r = cache.get(vals)
+    if (!r) {
+      cache.set(vals, r = checkForm(schema, vals))
+      r.then?.((x: any) => cache.set(vals, x))
+    }
+    return r
+  }
+  // G-379: a field is a path of values (an undefined value too); `quiet`: no SYG230 (a focusout
+  // from a named button)
+  const known = (s: any, n: any, quiet?: any) => {
+    const k = n && hasField(s.values, n)
+    n && !k && !quiet && dev(230, n, s.values)
+    return k
+  }
+  // new values: errors now (sync schema), or after the schema's Promise (RESULT)
+  const edit = (s: any, vals: any, x?: any) => {
+    const r = v(vals), a = !!r.then
+    return {s: {...s, ...x, values: vals, validating: a, ...(!a && {errors: r.errors, validated: true})}, wait: a && {values: vals}}
+  }
+  // the first check due: no schema error, a value, and not checked or running for it
+  const due = (s: any, only?: string) => checked.find(f => {
+    const x = getField(s.values, f)
+    return (!only || f == only) && !s.errors[f] && x !== '' && x != null && !(f in s.pending) && !(f in s.remote)
+  })
+  const ask = (s: any, f: string, k: string, queued: boolean) => {
+    const x = getField(s.values, f), q = checks[f].request(x), ok = `${k}.CHECKED_${f}`
+    dev(235, f, q)
+    return {s: {...s, queued, pending: {...s.pending, [f]: x}}, req: {...q, ok, error: ok, latest: true}}
+  }
+  // a submit with s's errors: blocked (focus the first), a check to run or to wait for, or sent
+  const attempt = (s: any, k: string) => {
+    const bad = [...keys(s.errors), ...keys(s.remote)], f = due(s)
+    return bad.length ? {s: {...s, queued: false}, focus: focusInvalid(bad, sel)}
+      : f ? ask(s, f, k, true)
+      : Object.keys(s.pending).length ? {s: {...s, queued: true}}
+      : {s: req ? {...s, queued: false, submitting: true} : done({...s, queued: false}), send: 1}
+  }
+  const base = (vals: any) => ({initial: vals, values: vals, touched: {}, server: {}, remote: {}, pending: {},
+    submitting: false, submitted: false, submitCount: 0, queued: false, errors: {}, validated: false})
+  const fresh = (vals: any) => edit(base(vals), vals)
+  const done = (s: any) => ({...s, submitting: false, submitted: true, initial: s.values, server: {}, touched: {}})
+  const group = (cur: any, d: any) => {
+    if (!Array.isArray(cur) || !('item' in d)) return d.value
+    const r = cur.filter(x => x !== d.item)
+    return d.value ? [...r, d.item] : r
+  }
+
+  const steps: Record<string, (s: any, d: any, k: string, h?: any) => any> = {
+    // G-376: a checkbox (`item`: its value) on an array field is one of a group: checked adds
+    // its value, unchecked removes it
+    CHANGE: (s, d) => known(s, d?.name) ? edit(s, setField(s.values, d.name, group(getField(s.values, d.name), d)), {
+      server: drop(drop(s.server, d.name), ''), remote: drop(s.remote, d.name), pending: drop(s.pending, d.name), queued: false,
+      touched: show == 'input' ? {...s.touched, [d.name]: true} : s.touched,
+    }) : null,
+    BLUR: (s, n, k) => {
+      if (!known(s, n, 1)) return null
+      const t = show == 'submit' || s.touched[n] ? s.touched : {...s.touched, [n]: true}, x = {...s, touched: t}
+      return due(s, n) ? ask(x, n, k, s.queued) : t != s.touched ? {s: x} : null
+    },
+    SUBMIT: (s, _, k) => {
+      if (s.submitting || s.queued) return void dev(232, s)
+      const n = {...s, submitCount: s.submitCount + 1}, r = v(s.values)
+      // G-371: a submit waiting for an async schema is queued (a second one is dropped)
+      return r.then ? {s: {...n, validating: true, queued: true}, wait: {values: s.values, submit: 1}} : attempt({...n, errors: r.errors}, k)
+    },
+    RESULT: (s, d, k) => {
+      if (d.values !== s.values) return
+      const n = {...s, errors: v(d.values).errors, validating: false, validated: true}
+      // the submit it was queued for (G-575: a done local submit isn't `submitting`, so not that)
+      return d.submit && s.queued ? attempt(n, k) : {s: n}
+    },
+    ADD: (s, {field, value}) => {
+      const rows = getField(s.values, field) || []
+      return edit(s, setField(s.values, field, [...rows, {id: rows.reduce((m: number, r: any) => Math.max(m, +r.id || 0), 0) + 1, ...value}]))
+    },
+    REMOVE: (s, {field, id}) => {
+      const p = field + '.' + id
+      return edit(s, setField(s.values, field, getField(s.values, field).filter((r: any) => r.id + '' != id)),
+        {touched: drop(s.touched, p), server: drop(s.server, p)})
+    },
+    ERRORS: (s, d) => {
+      const e = replyErrors(d, s.values)
+      return {s: {...s, server: e, submitting: false, queued: false}, focus: focusInvalid(e, sel)}
+    },
+    DONE: (s) => ({s: done(s)}),
+    RESET: (s, d) => fresh(d && typeof d == 'object' ? d : s.initial),
+    // G-375: the first validation, when the host starts (form() doesn't validate at module load).
+    // G-575: a slice kept in parent state from a host that unmounted mid-submit starts unstuck.
+    // D239: with resetOnShow (also each time the form element appears again), or a `values`
+    // function not called yet, the slice starts over from the start values (h: the host state)
+    VALIDATE: (s, _, _k, h) => again || fn && s.values === values ? fresh(fn ? vo(h) : vo)
+      : edit({...s, submitting: false, queued: false, pending: {}}, s.values),
+  }
+  // a check's reply (ok and error: an error reply carries an Error and passes)
+  for (const f of checked) steps['CHECKED_' + f] = (s, d, k) => {
+    if (!(f in s.pending)) return
+    const n = {...s, pending: drop(s.pending, f), remote: {...s.remote, [f]: d?.error instanceof Error ? '' : checks[f].error?.(d) || ''}}
+    return s.queued ? attempt(n, k) : {s: n}
+  }
+
+  const model: any = {}
+  for (const a in steps) {
+    let last: any[] = []
+    // (HOST, with the host state h, always computes: one slice object starts every app's host)
+    const out = (s: any, d: any, k: string, h?: any) => !h && last[0] === s && last[1] === d ? last[2] : (last = [s, d, steps[a](s, d, k, h)])[2]
+    model[a] = {
+      // VALIDATE: on the host's state (HOST), for a `values` function; the slice's own steps on it
+      ...a == 'VALIDATE' ? {HOST: (h: any, d: any, _n: any, _p: any, _o: any, k: string) => { const x = out(h[k], d, k, h); return x ? {...h, [k]: x.s} : h }}
+        : {STATE: (s: any, d: any, _n: any, _p: any, _o: any, k: string) => out(s, d, k)?.s || ABORT},
+      EFFECT: (s: any, d: any, next: any, _p: any, _o: any, k: string) => {
+        const x = out(s, d, k), w = x?.wait
+        if (x?.send) {
+          const r = v(x.s.values).value
+          dev(233, s.values, r)
+          // G-577: a submit named after one of the form's own actions goes to that one
+          submit in steps && dev(234, submit, k, b)
+          next(submit, r, 0)
+        }
+        w && Promise.resolve(v(w.values)).then(() => next('RESULT', w, 0))
+      },
+      ELEMENT: (s: any, d: any, _n: any, _p: any, _o: any, k: string) => out(s, d, k)?.focus || ABORT,
+      ...(checked.length && {[http]: (s: any, d: any, _n: any, _p: any, _o: any, k: string) => out(s, d, k)?.req || ABORT}),
+    }
+  }
+
+  const b = defineBehavior({
+    form: schema,
+    // validating until VALIDATE (sync) or its RESULT (async): not valid yet (G-375, not validated)
+    initialState: {...base(values), validating: true},
+    intent: ({DOM}: any) => {
+      const f = DOM.select(sel)
+      let on = 0
+      return {
+        // D239: resetOnShow also starts over each time the form element appears again (a
+        // Switchable page shown again: hidden pages stay alive; a form rendered again)
+        VALIDATE: again ? xs.merge(xs.of(0), f.elements().filter((e: any) => { const r = e.length && !on; on = e.length; return r })) : xs.of(0),
+        // G-376: a checkbox (native, or a hyphenated tag with a boolean `checked`: a
+        // form-associated custom checkbox / switch) gives `checked` and its value as `item`; a
+        // <select multiple> the selected values; type=file is left alone; others give `value`
+        CHANGE: f.events('input').filter(({target: t}: any) => t.type != 'file').map(({target: t}: any) =>
+          t.type == 'checkbox' || /-/.test(t.tagName) && typeof t.checked == 'boolean' ? {name: t.name, value: t.checked, item: t.value}
+          : {name: t.name, value: t.type == 'select-multiple' ? [...t.selectedOptions].map((o: any) => o.value) : t.value}),
+        BLUR: f.events('focusout').map((e: any) => e.target.name),
+        SUBMIT: f.events('submit', {preventDefault: true}),
+      }
+    },
+    model,
+    calculated: {
+      fields: (s: any) => {
+        const out: any = {}
+        for (const n of fieldNames(s.values)) {
+          const value = getField(s.values, n)
+          const error = s.server[n] || s.remote[n] || ((s.submitCount || show != 'submit' && s.touched[n]) && s.errors[n]) || ''
+          out[n] = {name: n, value, error, invalid: !!error, touched: !!s.touched[n], dirty: value !== getField(s.initial, n), pending: n in s.pending}
+        }
+        return out
+      },
+      // G-382: an async schema re-validating keeps the last answer's validity (no flicker)
+      valid: (s: any) => s.validated && !keys(s.errors).length && !keys(s.remote).length,
+      dirty: (s: any) => JSON.stringify(s.values) != JSON.stringify(s.initial),
+      error: (s: any) => s.server[''] || (s.submitCount && s.errors['']) || '',
+    },
+  })({...o, values}), merge = b.merge
+  b.merge = (c: any, k: string) => {
+    const e = c.model?.[submit]
+    req = !!e && typeof e == 'object' && http in e
+    merge(c, k)
+  }
+  return b
+}

package/src/extra/formHelpers.ts

@@ -0,0 +1,139 @@
+/*
+ * PLAN-5 F-1: form helpers. The `form` behavior (./form.ts) is built on them, and they are
+ * exported as the escape hatch for a form written with plain model actions (D193, shape B).
+ * Pure functions over a plain `values` object, for model reducers; 0 B core.
+ *
+ * Field names: a field's `name=` attribute is its path in `values`, dot-separated. A segment
+ * inside an array of objects is the row's `id` (not its index), so touched/errors follow a row
+ * when another row is removed: `addresses.7.street` is `values.addresses.find(r => r.id == 7).street`.
+ * An array of non-objects (or rows without an id) uses the index; a row with an id is named by
+ * its id only (G-380: `addresses.0.city` is no field when the rows have ids).
+ *
+ * Validation: any Standard Schema (`schema['~standard'].validate`: zod, valibot, arktype, a
+ * hand-written object), no dependency. A sync schema validates inside reducers; an async one
+ * (validate returns a Promise) returns a Promise here, for an EFFECT.
+ */
+import type {SchemaIssue} from './standardSchema'
+import {focusWithin} from './focusWithin'
+import {ABORT} from '../shared'
+
+export type FieldErrors = Record<string, string>
+export type FormCheck = {errors: FieldErrors; value: any}
+
+const isRow = (r: any) => r?.id != null
+// the key of segment `s` in `v`: an array's row with that id, else the index unless the element
+// there is a row (G-380: a row is named by its id only; -1, no element), an object's key
+const key = (v: any, s: string): any => {
+  if (!Array.isArray(v)) return s
+  const i = v.findIndex(r => isRow(r) && r.id + '' == s)
+  return i < 0 && !isRow(v[+s]) ? +s : i
+}
+
+/** the field name (id-based path) of a schema issue path (index-based) */
+export const fieldName = (values: any, path: ReadonlyArray<any> = []): string => {
+  let v = values
+  return path.map(p => {
+    p = p?.key ?? p
+    const r = Array.isArray(v) && isRow(v[p]) ? v[p].id : p
+    v = v?.[p]
+    return r
+  }).join('.')
+}
+
+/** the value at a field name (undefined when there is none) */
+export const getField = (values: any, name: string): any =>
+  name.split('.').reduce((v, s) => v?.[key(v, s)], values)
+
+/** whether `name` is a field of `values`: its path exists (G-379: also when the value is undefined) */
+export const hasField = (values: any, name: string): boolean => {
+  let v = values
+  for (const s of name.split('.')) {
+    const k = v && typeof v == 'object' ? key(v, s) : -1
+    if (!(k in Object(v))) return false
+    v = v[k]
+  }
+  return true
+}
+
+/** `values` with the field at `name` set to `value` (immutable; an unknown row is left alone) */
+export const setField = (values: any, name: string, value: any): any => {
+  const [s, ...rest] = name.split('.'), k = key(values, s), a = Array.isArray(values)
+  const x = rest.length ? setField(values?.[k] ?? {}, rest.join('.'), value) : value
+  if (x === values?.[k] || a && !(k in values)) return values
+  const c = a ? values.slice() : {...values}
+  c[k] = x
+  return c
+}
+
+/**
+ * every field name of `values`, in object order: each leaf, and each array itself (for an
+ * array-level error such as "at least one address"); a row's `id` is not a field
+ */
+export const fieldNames = (v: any, at = '', row?: boolean): string[] => {
+  if (!v || typeof v != 'object') return at ? [at] : []
+  const a = Array.isArray(v), out = a ? [at] : []
+  for (const k in v) {
+    const x = (v as any)[k]
+    if (!row || k != 'id') out.push(...fieldNames(x, (at && at + '.') + (a && isRow(x) ? x.id : k), a))
+  }
+  return out
+}
+
+const errorsOf = (values: any, issues: ReadonlyArray<SchemaIssue> = []): FieldErrors => {
+  const e: FieldErrors = {}
+  for (const i of issues) {
+    const n = fieldName(values, i.path)
+    n in e || (e[n] = i.message)
+  }
+  return e
+}
+
+/**
+ * Validates `values` with a Standard Schema: `{ errors, value }` (errors by field name, '' for
+ * a form-level issue, the first message per field; `value` is the schema's output, transformed,
+ * when there are none). A Promise of it when the schema is async. `schema` must be a Standard
+ * Schema object (the `form` behavior reports SYG231 in dev).
+ */
+export const checkForm = (schema: any, values: any): FormCheck | Promise<FormCheck> => {
+  const r = schema['~standard'].validate(values)
+  const done = (r: any): FormCheck => ({errors: errorsOf(values, r.issues), value: r.issues ? undefined : r.value})
+  return r.then ? r.then(done) : done(r)
+}
+
+/** the errors only, by field name ({} when valid); a Promise of them for an async schema */
+export const formErrors = (schema: any, values: any): any => {
+  const r: any = checkForm(schema, values)
+  return r.then ? r.then((x: FormCheck) => x.errors) : r.errors
+}
+
+/**
+ * Server errors as field errors: an error reply (a driver's `{ error, status?, body?, request }`
+ * or `{ status, body }`; the body `{ errors }` or the map itself), a map `{ name: message |
+ * messages }`, or a list of Standard-Schema-like issues `[{ path, message }]` (index paths
+ * become field names with `values`). With `values`, a message for a name that isn't one of its
+ * fields (`message`, `error`) is the form-level message (''); a reply without any becomes
+ * 'Request failed (status)' under ''.
+ */
+export const replyErrors = (reply: any, values?: any): FieldErrors => {
+  let e = reply && ('request' in reply || 'body' in reply && 'status' in reply) ? reply.body : reply
+  e = e?.errors ?? e
+  const out: FieldErrors = Array.isArray(e) ? errorsOf(values, e) : {}
+  if (e && typeof e == 'object' && !Array.isArray(e)) for (const k in e) {
+    const m = [].concat(e[k])[0] + ''
+    k && values && !hasField(values, k) ? out[''] ||= m : out[k] = m
+  }
+  return Object.keys(out).length ? out : {'': 'Request failed' + (reply?.status ? ` (${reply.status})` : '')}
+}
+
+/**
+ * An ELEMENT command that focuses the first field, in DOM order, whose `name` is one of `names`
+ * (a list, or an errors map: its names with a message; '' is skipped), anywhere in the sender's view, fields
+ * of child components and Collection items included (`focusWithin`, D194). With `within` (a
+ * selector: the form element's), only fields inside a matching element (G-373: a second form,
+ * or a child component's field of the same name outside the form, isn't focused). ABORT when
+ * there is nothing to focus: `ELEMENT: (state) => focusInvalid(state.errors, '.signup')`.
+ */
+export const focusInvalid = (names: string[] | FieldErrors, within?: string): any => {
+  const list = (Array.isArray(names) ? names : Object.keys(names).filter(n => names[n])).filter(n => n)
+  return list.length ? {focus: focusWithin(list.map(n => `${within ? within + ' ' : ''}[name=${JSON.stringify(n)}]`).join())} : ABORT
+}

package/src/extra/head.ts

@@ -0,0 +1,106 @@
+import {Stream} from 'xstream';
+import {senderOf, makeReplies} from './replies';
+
+/*
+ * makeHeadDriver({ titleTemplate?, document? }) (PLAN-3 §1.7, X-1). Docs: src/index.d.ts and
+ * docs guide/head.md. Summary:
+ *
+ * - Values `{ title?, meta?: { [name | property]: content | null }, link?: [{ rel, href, key?, ... }] }`
+ *   come from a component's `head` static (`App.head = state => ({ title })`, sent as
+ *   `{ head }`, `__sygnalStatic: 'head'`) or from a model entry (`HEAD: (s, d) => ({ title })`).
+ *   Each component instance has one entry, replaced by its next value; a falsy value or the
+ *   instance's dispose removes it.
+ * - Merge, in mount order (first declaration; a removed entry that comes back goes last): a
+ *   later `title` wins, `meta` keys merge (null removes a key), `link`s merge by `key`, else by
+ *   `rel` for canonical, else by `rel` + `href`. Meta keys with an `og:`/`article:`/... prefix
+ *   use `property`, the others `name`.
+ * - DOM: `document.title` (the page's original title when no entry sets one); meta and link
+ *   tags it creates carry `data-sygnal-head="<key>"`. An existing unmarked `<meta>` with the same
+ *   name is updated and restored when no entry sets it. Marked tags from SSR (`renderHead()`)
+ *   are adopted, or removed once no entry sets them.
+ * - SSR: `renderToString(App, { head: list })` pushes each rendered component's `head` static
+ *   into `list`; `renderHead(list, { titleTemplate })` gives the tags. No document: no-op.
+ */
+
+const PROPERTY = /^(og|fb|article|book|profile|music|video|al):/;
+const esc = (s: any) => String(s).replace(/[&<>"]/g, c => `&#${c.charCodeAt(0)};`);
+const attrOf = (k: string) => PROPERTY.test(k) ? 'property' : 'name';
+
+/** merged `{ title, meta: [[key, content]], link: [[key, attrs]] }` of head values, in order */
+export function mergeHead(list: any[], titleTemplate?: string) {
+  let title: any;
+  const meta: Record<string, any> = {}, link: Record<string, any> = {};
+  for (const h of list) {
+    if (!h || typeof h != 'object') continue;
+    if (h.title != null) title = h.title;
+    Object.assign(meta, h.meta);
+    for (const l of h.link || []) if (l) link['l:' + (l.key ?? (l.rel == 'canonical' ? l.rel : l.rel + ' ' + l.href))] = l;
+  }
+  return {
+    title: title != null && titleTemplate ? titleTemplate.replace('%s', title) : title,
+    meta: Object.keys(meta).filter(k => meta[k] != null).map(k => ['m:' + k, k, meta[k]]),
+    link: Object.entries(link),
+  };
+}
+
+/** the `<title>`, `<meta>` and `<link>` tags of head values (SSR) */
+export function renderHead(list: any[], options: {titleTemplate?: string} = {}): string {
+  const m = mergeHead(list, options.titleTemplate);
+  const attrs = (o: any) => Object.keys(o).filter(k => k != 'key' && o[k] != null && o[k] !== false).map(k => ` ${k}="${esc(o[k])}"`).join('');
+  return (m.title != null ? `<title>${esc(m.title)}</title>` : '') +
+    m.meta.map(([key, k, c]) => `<meta${attrs({[attrOf(k)]: k, content: c})} data-sygnal-head="${esc(key)}">`).join('') +
+    m.link.map(([key, l]) => `<link${attrs(l)} data-sygnal-head="${esc(key)}">`).join('');
+}
+
+export function makeHeadDriver(options: {titleTemplate?: string, document?: any} = {}) {
+  return (sink$: Stream<any>) => {
+    const d: any = options.document || (typeof document != 'undefined' ? document : null);
+    const entries = new Map<any, any>();
+    // key → element this driver manages; adopted: element → its original content
+    const made = new Map<string, any>(), adopted = new Map<any, any>();
+    const title0 = d?.title;
+    d?.querySelectorAll('[data-sygnal-head]').forEach((el: any) => made.set(el.getAttribute('data-sygnal-head'), el));
+
+    const set = (el: any, o: any) => { for (const k in o) if (k != 'key') o[k] == null || o[k] === false ? el.removeAttribute(k) : el.setAttribute(k, o[k]); };
+    const apply = () => {
+      if (!d) return;
+      const m = mergeHead([...entries.values()], options.titleTemplate), want = new Set<string>();
+      d.title = m.title ?? title0;
+      const put = (key: string, tag: string, o: any, find?: string) => {
+        want.add(key);
+        let el = made.get(key);
+        if (!el) {
+          el = find && d.head.querySelector(find);
+          if (el) adopted.set(el, el.getAttribute('content'));
+          else (el = d.createElement(tag)).setAttribute('data-sygnal-head', key), d.head.appendChild(el);
+          made.set(key, el);
+        }
+        set(el, o);
+      };
+      for (const [key, k, c] of m.meta) put(key, 'meta', {[attrOf(k)]: k, content: c}, `meta[${attrOf(k)}="${k}"]`);
+      for (const [key, l] of m.link) put(key, 'link', l);
+      made.forEach((el, key) => {
+        if (want.has(key)) return;
+        made.delete(key);
+        if (adopted.has(el)) set(el, {content: adopted.get(el)}), adopted.delete(el);
+        else el.remove();
+      });
+    };
+
+    const {replies} = makeReplies(s => { if (entries.delete(s)) apply(); });
+
+    sink$.addListener({
+      next: (v: any) => {
+        if (!v || typeof v != 'object') return;
+        const s = senderOf(v), h = 'head' in v ? v.head : v;
+        if (h && typeof h == 'object') entries.set(s, h);
+        else entries.delete(s);
+        apply();
+      },
+      error: (e: any) => console.error('[Sygnal] head', e),
+    });
+
+    const dispose = () => { entries.clear(); apply(); };
+    return {...replies, __sygnalStatic: 'head', dispose};
+  };
+}

package/src/extra/hmr.ts

@@ -10,7 +10,6 @@ interface HotModule {
 interface SygnalApp {
   hmr: (next: any, state?: any) => void;
   dispose?: () => void;
-  sources?: {STATE?: {stream?: {_v?: any}}};
 }
 
 function normalizeModule(maybeModule: any): ModuleWithDefault | null {
@@ -44,8 +43,8 @@ export default function enableHMR(
         next = normalizeModule(loaded);
       }
       if (next) {
-        const explicitState = app?.sources?.STATE?.stream?._v;
-        app.hmr(next, explicitState);
+        // (hmr() keeps the app's current state, read through the runtime API)
+        app.hmr(next);
       }
     } finally {
       applying = false;

package/src/extra/owned.ts

@@ -0,0 +1,24 @@
+/**
+ * PLAN-4.5 G-275: marks an initial state that a wrapper built from its caller's values (an
+ * element's host props, Vike's pageContext.data or hydrated state, renderComponent's
+ * initialState option). The dev statics freeze (D152, checks/statics.ts) leaves a marked object
+ * and everything in it alone: the caller may still change those values. A non-enumerable symbol
+ * key: spreads, JSON and Object.keys don't see it.
+ */
+export const OWNED = Symbol.for('sygnal.owned')
+
+export const owned = <T>(v: T): T => {
+  // G-289: an object that refuses the key (a Proxy) is returned as is
+  try { if (v && typeof v == 'object' && Object.isExtensible(v)) Object.defineProperty(v, OWNED, {value: 1}) } catch {}
+  return v
+}
+
+/**
+ * G-289: owned() of a shallow copy of a plain object or array (the caller's own object stays
+ * unmarked: it may be a component's static, which the freeze must still cover, or sealed, which
+ * can't be marked); anything else as owned()
+ */
+export const ownedCopy = <T>(v: T): T => {
+  const p = v && typeof v == 'object' ? Object.getPrototypeOf(v) : 0
+  return owned(Array.isArray(v) ? [...v] as any : p == Object.prototype || p === null ? {...v} : v)
+}

package/src/extra/pager.ts

@@ -0,0 +1,50 @@
+/*
+ * PLAN-4 GS-1: the first-party `pager` behavior.
+ *
+ *   const { Older, Newer } = controls({ Older: 'button', Newer: 'button' })
+ *   List.uses = { pager: pager({ pageSize: 10, next: Newer, prev: Older }) }
+ *
+ * Slice: { page, pageSize, total } plus the calculated offset, pages, hasPrev, hasNext.
+ * Actions: pager.NEXT, pager.PREV (ABORT at the bounds), pager.GOTO (page number, clamped),
+ * pager.SET_TOTAL (item count; keeps the page in range). `total` is optional: without it NEXT
+ * has no upper bound and `pages` is null. A host reducer may also write `state.pager.total`;
+ * the calculated fields follow.
+ */
+import { defineBehavior } from './behaviors'
+import { ABORT } from '../shared'
+
+const pagesOf = (p: any) => p.total == null ? null : Math.max(1, Math.ceil(p.total / p.pageSize))
+const to = (p: any, page: number) => {
+  const n = pagesOf(p)
+  page = Math.max(0, Math.min(page | 0, n == null ? page : n - 1))
+  return page === p.page ? ABORT : {...p, page}
+}
+
+/**
+ * A page cursor over a list (GS-1 behavior). Options: `pageSize` (20), `page` (0), `total`
+ * (null: unknown), and the controls `next` / `prev` whose clicks move the page. Use it as
+ * `uses = { pager: pager({ pageSize: 10, next: Newer, prev: Older }) }`, then render
+ * `items.slice(state.pager.offset, state.pager.offset + state.pager.pageSize)`.
+ */
+export const pager = /*#__PURE__*/ defineBehavior({
+  initialState: {page: 0, pageSize: 20, total: null},
+  intent: ({DOM}: any, {next, prev}: any) => ({
+    ...(next && {NEXT: DOM.click(next)}),
+    ...(prev && {PREV: DOM.click(prev)}),
+  }),
+  model: {
+    NEXT: (p: any) => to(p, p.page + 1),
+    PREV: (p: any) => to(p, p.page - 1),
+    GOTO: (p: any, page: number) => to(p, page),
+    SET_TOTAL: (p: any, total: number) => {
+      const q = {...p, total}, r = to(q, p.page)
+      return r === ABORT ? q : r
+    },
+  },
+  calculated: {
+    offset: (p: any) => p.page * p.pageSize,
+    pages: pagesOf,
+    hasPrev: (p: any) => p.page > 0,
+    hasNext: (p: any) => p.total == null || p.page + 1 < pagesOf(p)!,
+  },
+})