sygnal 5.3.7 → 6.0.0

package/src/extra/diagnostics/checks/shared.ts

@@ -0,0 +1,203 @@
+/**
+ * Shared plumbing for the runtime checks (PLAN-1 workstream 1A).
+ *
+ * The checks are bundled separately from the main 'sygnal' entry
+ * ('sygnal/diagnostics'). They must talk to the SAME diagnostics core
+ * instance the components use, so they never import the core's functions
+ * directly: `import '../index'` only makes sure the core is loaded (in the
+ * dist build that import is rewritten to the external 'sygnal' package, see
+ * rollup.config.mjs), and the functions are read from the bridge object the
+ * core publishes on globalThis.__SYGNAL_DIAGNOSTICS__.
+ */
+import '../index'
+import type {DiagnosticCheck, DiagnosticDetails, Diagnostic} from '../index'
+import {CODE_TITLES, DEV_CODE_SEVERITY, registerCodes} from '../codes'
+import type {DiagnosticSeverity} from '../codes'
+
+interface CoreBridge {
+  registerCheck(check: DiagnosticCheck): () => void
+  report(code: string, details: DiagnosticDetails): Diagnostic | undefined
+  [key: string]: any
+}
+
+export const bridge = (): CoreBridge => (globalThis as any).__SYGNAL_DIAGNOSTICS__
+
+export const report = (code: string, details: DiagnosticDetails): Diagnostic | undefined =>
+  bridge().report(code, details)
+
+/**
+ * report() for code that is NOT running inside a core hook (timers, wrapped
+ * methods): never throws synchronously; an 'error'-mode DiagnosticError is
+ * rethrown asynchronously, like the core does for hooks.
+ */
+export const reportSafely = (code: string, details: DiagnosticDetails): Diagnostic | undefined => {
+  try {
+    return report(code, details)
+  } catch (err) {
+    const raise = () => { throw err }
+    typeof queueMicrotask === 'function' ? queueMicrotask(raise) : setTimeout(raise)
+    return undefined
+  }
+}
+
+registerCodes(Object.keys(DEV_CODE_SEVERITY).map(code =>
+  [code, DEV_CODE_SEVERITY[code], CODE_TITLES[code]] as [string, DiagnosticSeverity, string]))
+
+/**
+ * reportSafely() for the dev-entry-only codes (DEV_CODE_SEVERITY, G-143): the main bundle's
+ * core doesn't know their severity, so it is passed explicitly.
+ */
+export const devReport = (code: string, details: DiagnosticDetails): Diagnostic | undefined =>
+  reportSafely(code, {severity: DEV_CODE_SEVERITY[code], ...details})
+
+/** Tunables (test seam: configureChecks()). */
+export const timing = {
+  /** delay after a render before DOM checks run (lets nested renders patch) */
+  settleMs: 50,
+  /** SYG103 escalates to warn after this much render-idle time ... */
+  idleMs: 2000,
+  /** ... and only once the component has rendered at least this often */
+  minRenders: 3,
+}
+
+/**
+ * Built-in actions Sygnal dispatches itself; never "missing" or "unreachable".
+ * (HYDRATE is not one since 6.0, D66: nothing dispatches it, so it is an ordinary action.)
+ */
+export const BUILTIN_ACTIONS = new Set(['BOOTSTRAP', 'INITIALIZE', 'DISPOSE', 'READY', 'RESOURCE'])
+
+/** Sinks the core handles itself: their values never go to a reply-action driver. */
+// (PLAN-4 GS-2: ELEMENT too; `{ scrollIntoView: Row, block: 'center' }` names no action)
+const NON_REPLY_SINK = /^(STATE|EFFECT|EVENTS|PARENT|READY|DOM|CHILD|ELEMENT|PERSIST)$/
+
+// `ok: 'X'` / `"error": "X"` in function source (minified code keeps string literals and keys)
+const keyedNames = (keys: string) => new RegExp(`(?:^|[{,\\s])["']?(?:${keys})["']?\\s*:\\s*(["'\`])([\\w$.:/-]+)\\1`, 'g')
+// (PLAN-3 5-4b: and a router `{ block: 'ACTION' }`)
+const REPLY_IN_SOURCE = keyedNames('ok|error|block')
+const CONNECTION_IN_SOURCE = keyedNames('message|open|close|error')
+// G-224: a `timers` static's `action: 'TICK'` / `frame: 'FRAME'`
+const TIMER_IN_SOURCE = keyedNames('action|frame')
+// PLAN-5 B-3: a `browser` static's `action: 'SEEN'` / `error: 'GEO_FAILED'`
+const BROWSER_IN_SOURCE = keyedNames('action|error')
+
+const namesIn = (fn: any, re: RegExp, out: Set<string>) => {
+  if (typeof fn !== 'function') return
+  let src = ''
+  try { src = Function.prototype.toString.call(fn) } catch (_) { return }
+  re.lastIndex = 0
+  for (let m = re.exec(src); m; m = re.exec(src)) out.add(m[2])
+}
+
+/**
+ * Reply actions a component's requests and `connections` static can name, read from the
+ * source of its non-STATE sink functions (`HTTP: (s) => ({ url, ok: 'LOADED', error: 'FAILED' })`)
+ * and of `connections` (message/open/close/error). A heuristic for SYG102 (PLAN-3): a name
+ * built at run time is missed (SYG102 stays info, so that only costs a false hint).
+ */
+export function replyNamesOf(component: any): Set<string> {
+  const out = new Set<string>()
+  const model = component && component.model
+  if (model && typeof model === 'object') {
+    for (const key of Object.keys(model)) {
+      const value = model[key]
+      const bar = key.indexOf('|')
+      if (bar >= 0) {
+        if (!NON_REPLY_SINK.test(key.slice(bar + 1).trim())) namesIn(value, REPLY_IN_SOURCE, out)
+      } else if (value && typeof value === 'object') {
+        for (const sink of Object.keys(value)) {
+          if (!NON_REPLY_SINK.test(sink)) namesIn(value[sink], REPLY_IN_SOURCE, out)
+        }
+      }
+    }
+  }
+  namesIn(component?.view?.connections, CONNECTION_IN_SOURCE, out)
+  // G-224: makeTimerDriver() replies the actions the `timers` static names (a function of the
+  // state, or an object of them)
+  const timers = component?.view?.timers
+  if (timers && typeof timers === 'object') for (const k in timers) namesIn(timers[k], TIMER_IN_SOURCE, out)
+  else namesIn(timers, TIMER_IN_SOURCE, out)
+  // PLAN-5 B-3: the browser driver replies the actions the `browser` static names
+  const browser = component?.view?.browser
+  if (browser && typeof browser === 'object') for (const k in browser) namesIn(browser[k], BROWSER_IN_SOURCE, out)
+  else namesIn(browser, BROWSER_IN_SOURCE, out)
+  // PLAN-3 5-4b: the router replies the action a `route` static names
+  const route = component?.view?.route
+  if (typeof route === 'string') out.add(route)
+  // PLAN-4 GS-5: persist() adds RESTORE (sent after hydration and by sync)
+  if (component?.view?.persist) out.add('RESTORE')
+  return out
+}
+
+/** Reply actions a component instance's requests were seen naming (replies.ts → inspect). */
+export const replySeen = new WeakMap<object, Set<string>>()
+
+/** Synthetic/internal actions (`__TEST_ACTION__`, `__NOOP_ACTION__`, ...) and built-ins. */
+export const isInternalAction = (action: string): boolean =>
+  typeof action !== 'string' || action.startsWith('__') || BUILTIN_ACTIONS.has(action)
+
+let seen = new Set<string>()
+
+/** true the first time `key` is seen (dedupes reports, e.g. per component name). */
+export const once = (key: string): boolean => (seen.has(key) ? false : (seen.add(key), true))
+/** undo once(key): the report it guarded wasn't made (G-470: diagnostics off) */
+export const unsee = (key: string): void => void seen.delete(key)
+/** whether once(`key`) has reported already (a check can skip its work: SYG435) */
+export const onced = (key: string): boolean => seen.has(key)
+
+/**
+ * Forget only the once() dedupe set (G-051: renderComponent calls it through the core bridge
+ * when an outermost instance starts, so findings are reported again in every test). Unlike
+ * resetCheckState() it keeps the checks' registries, e.g. inspect()'s live records.
+ */
+export const resetOnce = (): void => { seen = new Set() }
+{
+  const core = bridge()
+  if (core) core.resetOnce = resetOnce
+}
+
+const resetters: Array<() => void> = []
+export const onReset = (fn: () => void): void => { resetters.push(fn) }
+
+/** Clear every check's dedupe/registry state (tests). */
+export function resetCheckState(): void {
+  seen = new Set()
+  resetters.forEach(fn => fn())
+}
+
+export const nameOf = (component: any): string => (component && component.name) || 'component'
+
+export const isPlainObject = (value: any): boolean =>
+  !!value && typeof value === 'object' && !Array.isArray(value) &&
+  (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)
+
+/** Levenshtein distance (small strings only). */
+function distance(a: string, b: string): number {
+  const row = Array.from({length: b.length + 1}, (_, i) => i)
+  for (let i = 1; i <= a.length; i++) {
+    let prev = row[0]
+    row[0] = i
+    for (let j = 1; j <= b.length; j++) {
+      const tmp = row[j]
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1))
+      prev = tmp
+    }
+  }
+  return row[b.length]
+}
+
+/** Closest candidate to `name` (case-insensitive match or edit distance <= 2), if any. */
+export function suggest(name: string, candidates: Iterable<string>): string | undefined {
+  let best: string | undefined
+  let bestScore = Infinity
+  for (const c of candidates) {
+    if (c === name) continue
+    const score = c.toLowerCase() === name.toLowerCase() ? 0 : distance(c, name)
+    if (score < bestScore) { best = c; bestScore = score }
+  }
+  return bestScore <= Math.min(2, Math.floor(name.length / 3)) ? best : undefined
+}
+
+export const didYouMean = (name: string, candidates: Iterable<string>): string => {
+  const s = suggest(name, candidates)
+  return s ? ` (did you mean '${s}'?)` : ''
+}

package/src/extra/diagnostics/checks/shorthand.ts

@@ -0,0 +1,115 @@
+/**
+ * SYG115 — unknown DOM event shorthand (warn, G-143).
+ *
+ * The core's DOM source Proxy (the DOM source wrapper) turns ANY unknown property
+ * into an event shorthand: `DOM.<name>(sel)` = `DOM.select(sel).events('<name>')`. A made-up
+ * name such as `DOM.key('.x')` or `DOM.enter('.x')` therefore listens for an event the browser
+ * never fires, and the action silently never happens.
+ *
+ * Mechanism: the `sources` hook (called before each component's intent) wraps the DOM source
+ * in a second Proxy. Calling a shorthand whose name is not a known DOM event reports SYG115
+ * (once per component name and event), then behaves exactly like the core shorthand. Only the
+ * call is reported, not the property read, so tools that inspect the source (pretty-printers)
+ * don't trigger it. `DOM.select(sel).events(name)` is never checked: it is the explicit form
+ * for custom events.
+ */
+import type {DiagnosticCheck} from '../index'
+import {devReport, once, nameOf, suggest} from './shared'
+
+// Standard DOM / UI event names (lower case). In a browser, `on<name>` on an element or the
+// window also counts, so newer events are accepted there too.
+const KNOWN = new Set((
+  'abort afterprint animationcancel animationend animationiteration animationstart auxclick ' +
+  'beforeinput beforeprint beforetoggle beforeunload blur cancel canplay canplaythrough change click close ' +
+  'compositionend compositionstart compositionupdate contextlost contextmenu contextrestored copy cuechange cut ' +
+  'dblclick drag dragend dragenter dragleave dragover dragstart drop durationchange emptied ended error ' +
+  'focus focusin focusout formdata fullscreenchange fullscreenerror gotpointercapture hashchange input invalid ' +
+  'keydown keypress keyup languagechange load loadeddata loadedmetadata loadstart lostpointercapture message ' +
+  'messageerror mousedown mouseenter mouseleave mousemove mouseout mouseover mouseup offline online pagehide ' +
+  'pageshow paste pause play playing pointercancel pointerdown pointerenter pointerleave pointermove pointerout ' +
+  'pointerover pointerrawupdate pointerup popstate progress ratechange rejectionhandled reset resize scroll ' +
+  'scrollend search securitypolicyviolation seeked seeking select selectionchange selectstart slotchange stalled ' +
+  'storage submit suspend timeupdate toggle touchcancel touchend touchmove touchstart transitioncancel ' +
+  'transitionend transitionrun transitionstart unhandledrejection unload visibilitychange volumechange waiting wheel'
+).split(' '))
+
+const isKnown = (name: string): boolean => {
+  // PLAN-5 0-S6: a hyphenated name is a custom element's event (DOM['wa-hover']('.food')): no
+  // standard DOM event has a hyphen, and a bracketed name is no typo for one
+  if (KNOWN.has(name) || name.includes('-')) return true
+  const on = 'on' + name
+  const g: any = globalThis
+  try {
+    return !!((g.HTMLElement && on in g.HTMLElement.prototype) || (g.window && on in g.window) ||
+      (g.Document && on in g.Document.prototype))
+  } catch (_) { return false }
+}
+
+// Names agents reach for that are enriched-stream methods or key names, not events
+const KEY_FIX = (sel: string, key?: string) =>
+  `Listen for the real event and read the key: DOM.keydown(${sel}).key()` +
+  (key ? `.filter(k => k === '${key}')` : '')
+const SPECIAL: Record<string, (sel: string) => string> = {
+  key: sel => KEY_FIX(sel),
+  keys: sel => KEY_FIX(sel),
+  enter: sel => KEY_FIX(sel, 'Enter'),
+  escape: sel => KEY_FIX(sel, 'Escape'),
+  esc: sel => KEY_FIX(sel, 'Escape'),
+  value: sel => `Listen for the real event and read the value: DOM.input(${sel}).value()`,
+  checked: sel => `Listen for the real event and read the box: DOM.change(${sel}).checked()`,
+  data: sel => `Listen for the real event and read the attribute: DOM.click(${sel}).data('name')`,
+  doubleclick: sel => `Use DOM.dblclick(${sel})`,
+}
+
+const fixFor = (name: string, selector: any): string => {
+  const sel = typeof selector === 'string' ? `'${selector}'` : 'sel'
+  const special = SPECIAL[name.toLowerCase()]
+  if (special) return special(sel)
+  const s = suggest(name, KNOWN)
+  return (s ? `Did you mean DOM.${s}(${sel})? ` : '') +
+    `If '${name}' is a custom event you dispatch yourself, use the explicit form DOM.select(${sel}).events('${name}')`
+}
+
+const wrapped = new WeakMap<object, any>()
+
+function checkedDOM(component: any, dom: any): any {
+  if (!dom || typeof dom != 'object') return dom
+  let proxy = wrapped.get(dom)
+  if (proxy) return proxy
+  const name = nameOf(component)
+  proxy = new Proxy(dom, {
+    get(t: any, k: any) {
+      const v = t[k]
+      if (typeof k != 'string' || k in t || typeof v != 'function' || isKnown(k)) return v
+      return function (this: any, selector: any, ...rest: any[]) {
+        if (once(`SYG115:${name}:${k}`)) {
+          devReport('SYG115', {
+            component,
+            message: `${name}.intent uses DOM.${k}(${typeof selector == 'string' ? `'${selector}'` : '…'}), but '${k}' is not a DOM event, so it never fires`,
+            fix: fixFor(k, selector),
+            data: {event: k, selector},
+          })
+        }
+        return v.call(this, selector, ...rest)
+      }
+    },
+  })
+  wrapped.set(dom, proxy)
+  return proxy
+}
+
+export const shorthandCheck: DiagnosticCheck = {
+  id: 'shorthand',
+
+  sources(component, sources) {
+    if (!sources || typeof Proxy != 'function') return
+    const domName = component?.DOMSourceName || 'DOM'
+    if (!sources[domName]) return
+    return new Proxy(sources, {
+      get(t: any, k: any) {
+        const v = t[k]
+        return k === domName ? checkedDOM(component, v) : v
+      },
+    })
+  },
+}

package/src/extra/diagnostics/checks/sortable.ts

@@ -0,0 +1,129 @@
+/**
+ * PLAN-5 B-1 (3-D): `sortable` behavior diagnostics (dev entry; src/extra/sortable.ts carries no
+ * text). The behavior calls `__SYGNAL_DIAGNOSTICS__.sortable(code, ...args)`:
+ *   145  (item element, item selector, attr) a press or key on an item whose element has no
+ *        `attr`: SYG145 (warn, once per selector); the event is ignored
+ *   146  (host root, item, handle, attr) the host's first pointerdown / keydown: SYG146 (warn,
+ *        once per selector) when elements carry `attr` under the root but none matches `item`,
+ *        or items exist but none contains `handle`. Returns true once it could decide (an empty
+ *        list can't tell: the check runs again at the next interaction)
+ *   147  (from key, host state, uses key) when the host starts: a `from` key whose value isn't
+ *        an array: SYG147 (warn, once per key)
+ *   435  (3-H G-449) (fn, uses key, from keys, idOf): the host's own items' ids as shown, per
+ *        container (fn() returns [the item elements, the root]; the behavior only asks in dev), or nothing when
+ *        every list has been reported (3-L G-478: no scan). A row's place is its `data-index`
+ *        when it has one (VirtualCollection's pinned focused row is out of DOM order). (shown
+ *        groups, host state, from keys, idField, uses key) at a keyboard pick-up or a pointer
+ *        press: SYG435 (warn, once per uses key and list) when a list's shown items (those in
+ *        the container holding most of them: an element elsewhere with a matching id is no list
+ *        item; a row's container is its nearest ancestor holding another row, 3-O G-505) aren't
+ *        one run of the array in its order (a Collection's sort, or a filter hiding entries
+ *        between shown ones)
+ */
+import {devReport, once, onced, suggest} from './shared'
+
+const all = (root: any, sel: string): any[] => {
+  try { return [...root.querySelectorAll(sel)] } catch (_) { return [] }
+}
+
+export function reportSortable(code: number, a?: any, b?: any, c?: any, d?: any, e?: any): any {
+  if (code == 145) {
+    if (once(`SYG145:${b}:${c}`)) devReport('SYG145', {
+      component: 'sortable',
+      message: `sortable: an item ('${b}') has no ${c} attribute, so it can't be moved (the behavior finds each item in the list by that id)`,
+      fix: `Render the item's id on its element: <li className="${String(b).replace(/^\./, '')}" ${c}={item.id}>, or name the attribute: sortable({ ..., attr: 'data-key' })`,
+      data: {item: b, attr: c},
+    })
+    return
+  }
+  if (code == 146) {
+    const root = a, item = b, handle = c, attr = d
+    if (!root?.querySelectorAll) return true
+    const items = all(root, item).filter(el => el !== root)
+    if (!items.length) {
+      // nothing carries the id attribute either: an empty list (decide later)
+      if (!all(root, `[${attr}]`).length) return false
+      report146('item', item, `no element under the host matches it, though elements with ${attr} are rendered`, `Use the selector of the items' elements (the element with ${attr}), e.g. item: '.task'`)
+      return true
+    }
+    if (handle && !items.some(el => all(el, handle).length)) {
+      report146('handle', handle, `no item ('${item}') contains an element that matches it`, `Use the selector of the drag handle inside each item, e.g. handle: '.grip', or leave handle out to drag the whole item`)
+    }
+    return true
+  }
+  if (code == 435) {
+    // (fn, uses key, from keys, idOf) the shown ids per container: computed only here (dev)
+    if (typeof a == 'function') {
+      if ((c || []).every((l: string) => onced(`SYG435:${b}:${l}`))) return
+      try {
+        const by = new Map<any, any[]>(), [els, root] = a(), n = new Map<any, number>()
+        // a row's place: its data-index (a VirtualCollection row below the host's root; its
+        // pinned row isn't in DOM order)
+        const rows = els.map((el: any) => {
+          const r0 = el.closest?.('[data-index]'), row = r0 && r0 !== root && root.contains?.(r0) ? r0 : el
+          return [el, row, Number(row === el && !r0 ? NaN : row.getAttribute('data-index'))]
+        })
+        // 3-O G-505: a row's container is its nearest ancestor holding another row (items each in
+        // their own wrapper, <li><div data-id>, a table cell, a Collection item's root, are still
+        // one list); `n` counts the rows below each ancestor
+        const up = (row: any, f: (p: any) => any) => { for (let p = row.parentElement; p; p = p === root ? null : p.parentElement) if (f(p)) return p }
+        for (const [, row] of rows) up(row, p => void n.set(p, (n.get(p) || 0) + 1))
+        for (const [el, row, at] of rows) {
+          const p = up(row, p => n.get(p)! > 1) || row.parentElement
+          by.has(p) || by.set(p, [])
+          by.get(p)!.push([isNaN(at) ? by.get(p)!.length : at, String(d(el))])
+        }
+        return [...by.values()].map(g => g.sort((x, y) => x[0] - y[0]).map(x => x[1]))
+      } catch (_) { return }
+    }
+    // (shown groups, host state, from keys, idField, uses key) at a keyboard pick-up or a press
+    const groups: string[][] = Array.isArray(a?.[0]) ? a : [a || []]
+    for (const l of c || []) {
+      if (onced(`SYG435:${e}:${l}`)) continue
+      const at = new Map<string, number>()
+      if (Array.isArray(b?.[l])) b[l].forEach((x: any, i: number) => at.set(String(x?.[d]), i))
+      // the list's container: the one holding most of its entries (others: stray matches)
+      let dom: number[] = []
+      for (const g of groups) {
+        const ix = g.filter(i => at.has(i)).map(i => at.get(i)!)
+        if (ix.length > dom.length) dom = ix
+      }
+      // a contiguous run in the array's order is fine (all of it, or a window of it)
+      if (!dom.some((v, j) => v !== dom[0] + j)) continue
+      if (once(`SYG435:${e}:${l}`)) devReport('SYG435', {
+        component: 'sortable',
+        message: `sortable '${e}': state.${l} is shown ${dom.length < at.size ? 'with entries hidden between the shown ones' : 'in another order'} (a Collection with ${dom.length < at.size ? 'filter' : 'sort'}?), but moves and the announced positions follow the array: a keyboard step can pass entries nobody sees, or change nothing visible`,
+        fix: `Reorder a list that is shown as it is stored: drop the Collection's sort (sort state.${l} itself), and hide the drag handles while a filter hides entries`,
+        data: {from: l, key: e},
+      })
+    }
+    return
+  }
+  if (code == 147) {
+    const st = b || {}, arrays = Object.keys(st).filter(k => Array.isArray(st[k]))
+    const near = suggest(a, arrays)
+    if (once(`SYG147:${c}:${a}`)) devReport('SYG147', {
+      component: 'sortable',
+      message: `sortable '${c}': from names '${a}', but state.${a} is ${st[a] === undefined ? 'missing' : 'not an array'} when the host starts${near ? ` (did you mean '${near}'?)` : ''}; nothing in it can be moved`,
+      fix: `Name the host state's list: sortable({ from: '${near || arrays[0] || 'items'}', ... })${arrays.length ? ` (arrays in the state: ${arrays.join(', ')})` : `, and start it as an array (initialState: { ${a}: [] })`}`,
+      data: {from: a, key: c},
+    })
+  }
+}
+
+const report146 = (option: string, selector: string, why: string, fix: string) => {
+  if (once(`SYG146:${option}:${selector}`)) devReport('SYG146', {
+    component: 'sortable',
+    message: `sortable: ${option} '${selector}' matches nothing: ${why}, so no item can be dragged`,
+    fix,
+    data: {option, selector},
+  })
+}
+
+/** Install the `sortable` hook on the core bridge (sortable.ts calls it). */
+export function installSortableHooks(): () => void {
+  const c = (globalThis as any).__SYGNAL_DIAGNOSTICS__
+  if (!c) return () => {}
+  c.sortable = reportSortable
+  return () => { if (c.sortable === reportSortable) c.sortable = undefined }
+}

package/src/extra/diagnostics/checks/state.ts

@@ -0,0 +1,148 @@
+/**
+ * SYG201 — STATE reducer dropped keys that existed in the previous state (warn)
+ * SYG202 — STATE reducer returned undefined (warn)
+ * SYG221 — set() called with a string (error, G-143): the string is spread
+ *          into the state as keys '0', '1', ... (one per character)
+ * SYG238 — G-393: a root with a model but no initialState (and no state from renderComponent's
+ *          `initialState` or an HMR swap): its state is undefined, so it renders nothing until an
+ *          action sets one (the 5.x / PLAN-4 behaviour; a root without a model renders from
+ *          `initialState || true`, G-172). onModel, at construction, once per component name.
+ * SYG222 — STATE reducer returned the object it got after mutating it in place (warn, dev;
+ *          PLAN-4 GS-4): since 6.0 the same object back means "no change", so the mutation
+ *          is ignored. Mechanism: onIntent (called before the model is read) wraps the
+ *          instance's STATE reducers; the wrapper takes a shallow snapshot (keys and top-level
+ *          values) before the reducer runs and compares it when the reducer returns the same
+ *          reference; a behavior slice (state[key] of a `uses` entry) is snapshotted the same
+ *          way (keys reported as 'key.field', G-214). Nested mutations (state.list.push) are
+ *          below the snapshot. Zero bytes
+ *          in the core: the wrapping only happens with the dev entry and diagnostics on.
+ *
+ * Mechanism: onReducer(component, action, prevState, nextState). Reported once
+ * per action per component name. Not reported for:
+ *   - synthetic actions (`__*`) and INITIALIZE (whole-state replacement; HYDRATE is an
+ *     ordinary action since 6.0, D66)
+ *   - SYG202: a Collection item (`() => undefined` is its documented self-removal, G-357)
+ *   - keys that are calculated fields (they are re-derived after the reducer)
+ *   - keys whose previous value was undefined
+ * The set()/toggle() helpers always spread the previous state, so they can't
+ * drop keys and never trigger SYG201.
+ */
+import type {DiagnosticCheck} from '../index'
+import {report, devReport, once, nameOf, isPlainObject} from './shared'
+import {ORIGINAL} from '../../../shared'
+
+const SKIP = new Set(['INITIALIZE'])
+
+// SYG222: the instance's STATE reducers, wrapped (see the header)
+const WRAPPED = Symbol('SYG222')
+
+export function watchMutation(component: any, action: string, fn: any): any {
+  if (typeof fn !== 'function' || fn[WRAPPED]) return fn
+  const wrapped: any = (state: any, ...rest: any[]) => {
+    if (!isPlainObject(state)) return fn(state, ...rest)
+    // the state's top level, and (G-214) each behavior slice's: a behavior reducer that mutates
+    // its slice gets the host state back unchanged (behaviors.ts), so state[key] looks the same
+    const snaps = [[state, ''], ...(component._uses || []).map(([k]: any) => [state[k], k + '.'])]
+      .filter(([o]) => isPlainObject(o)).map(([o, p]) => [o, p, Object.keys(o), Object.values(o)])
+    const out = fn(state, ...rest)
+    if (out === state) {
+      const changed = snaps.flatMap(([o, p, keys, values]: any) => keys.filter((k: string, i: number) => !(k in o) || o[k] !== values[i])
+        .concat(Object.keys(o).filter(k => !keys.includes(k))).map((k: string) => p + k))
+      const name = nameOf(component)
+      if (changed.length && once(`SYG222:${name}:${action}`)) {
+        const list = changed.map(k => `'${k}'`).join(', ')
+        devReport('SYG222', {
+          component,
+          message: `The STATE reducer for '${action}' changed ${list} in place and returned the same object. Returning the object a reducer got means "no change" (as ABORT), so the change is ignored and nothing re-renders`,
+          fix: `Return a new object: ${changed[0].includes('.') ? `(slice, data) => ({ ...slice, ${changed[0].split('.')[1]}: … })` : `(state, data) => ({ ...state, ${changed[0]}: … })`}. To write updates as mutations, wrap the reducer in immer's produce()`,
+          data: {action, keys: changed},
+        })
+      }
+    }
+    return out
+  }
+  wrapped[WRAPPED] = true
+  // checks that read reducer source (reply actions) see the original; so do the action log
+  // and t.explain() (ORIGINAL)
+  wrapped.toString = () => fn.toString()
+  wrapped[ORIGINAL] = fn
+  return wrapped
+}
+
+export const stateCheck: DiagnosticCheck = {
+  id: 'state',
+
+  // SYG222: checks/next.ts wraps the STATE reducers (watchMutation) through wrapHandler
+
+  onModel(component) {
+    // SYG238 (G-393): the initial state is set at construction (D165), before onModel
+    const n = component?.__next
+    if (!n?.isRoot || !n.def?.model || n.state !== undefined) return
+    const name = nameOf(component)
+    if (!once(`SYG238:${name}`)) return
+    devReport('SYG238', {
+      component,
+      message: `${name} is a root with a model but no initialState: its state is undefined, so it renders nothing until an action sets one`,
+      fix: `Add ${name}.initialState = { … } (the root's start state; a child gets its state from its parent instead)`,
+      data: {},
+    })
+  },
+
+  onReducer(component, action, prevState, nextState) {
+    if (typeof action !== 'string' || action.startsWith('__') || SKIP.has(action)) return
+    const name = nameOf(component)
+
+    if (nextState === undefined) {
+      // G-357: returning undefined from a Collection item's reducer is the documented way to
+      // remove the item: not reported. In another sub-component it is info, in the root (where
+      // it wipes the whole app state) a warning.
+      if (component?.__next?.kind === 'item' || !once(`SYG202:${name}:${action}`)) return
+      const sub = !!component?.isSubComponent
+      report('SYG202', {
+        component,
+        severity: sub ? 'info' : 'warn',
+        message: `The STATE reducer for '${action}' returned undefined` +
+          (sub ? ' (only a Collection item removes itself this way)' : ''),
+        fix: `Return the new state, e.g. (state, data) => ({ ...state, ... }), or return ABORT to leave the state unchanged`,
+        data: {action},
+      })
+      return
+    }
+
+    if (!isPlainObject(prevState) || !isPlainObject(nextState)) return
+
+    // SYG221 (G-143): set('city') spreads the string into the state: { ...state, 0: 'c', 1: 'i', ... }
+    const chars: string[] = []
+    while (typeof nextState[chars.length] === 'string' && nextState[chars.length].length === 1 && !(chars.length in prevState)) {
+      chars.push(nextState[chars.length])
+    }
+    if (chars.length > 0 && !(chars.length in nextState)) {
+      if (!once(`SYG221:${name}:${action}`)) return
+      const field = chars.join('')
+      const update = /^[A-Za-z_$][\w$]*$/.test(field)
+        ? `set((state, ${field}) => ({ ${field} }))`
+        : `set((state, value) => ({ ['${field}']: value }))`
+      devReport('SYG221', {
+        component,
+        message: `The STATE reducer for '${action}' added the keys ${chars.map((_, i) => `'${i}'`).slice(0, 4).join(', ')}${chars.length > 4 ? ', …' : ''} ` +
+          `(one per character of '${field}'): set() was called with a string, set('${field}'). set() takes an object or a function`,
+        fix: `To store the action data in '${field}', pass a function: ${update}. For a fixed value pass an object: set({ ${field}: … })`,
+        data: {action, field},
+      })
+      return
+    }
+
+    const calculated: Set<string> | null = component?._calculatedFieldNames || null
+    const dropped = Object.keys(prevState).filter(key =>
+      !(key in nextState) && prevState[key] !== undefined && !(calculated && calculated.has(key)))
+    if (dropped.length === 0 || !once(`SYG201:${name}:${action}`)) return
+
+    const list = dropped.map(k => `'${k}'`).join(', ')
+    report('SYG201', {
+      component,
+      message: `The STATE reducer for '${action}' returned a state without ${list}, which ${dropped.length === 1 ? 'was' : 'were'} in the previous state (likely a missing ...state spread)`,
+      fix: `Spread the previous state: (state, data) => ({ ...state, ... }). If removing ${dropped.length === 1 ? 'the key' : 'these keys'} is intended, ignore this`,
+      data: {action, droppedKeys: dropped},
+    })
+  },
+}

package/src/extra/diagnostics/checks/statics.ts

@@ -0,0 +1,48 @@
+/**
+ * PLAN-4.5 D152: shared statics are frozen in dev (dev entry only; the core never freezes).
+ *
+ * Since P45-B a component's `initialState`, `model`, `context` and `calculated` statics are
+ * shared by all its instances (no per-instance deep copy). Mutating one in place (a reducer's
+ * `state.items.push(x)` on the initial state, a view that writes into state) would change every
+ * instance, and every later one. With diagnostics on, `initialState` is deep-frozen (its plain
+ * objects and arrays; class instances such as Map or Date are left as they are) and the other
+ * statics are frozen at the top level, so such a mutation throws a TypeError where it happens
+ * (in a reducer: reported as SYG216 with the error attached; in a view: SYG406).
+ *
+ * Frozen: the component function's own statics, and the options given to component() (G-280:
+ * `component({ view, model, initialState })`; the instance's `_o`, the values before behaviors or
+ * persist() made per-instance copies). Not frozen: the instance's values (G-268), and an
+ * initial state a wrapper built from its caller's objects (G-275: marked with `owned()` by
+ * sygnal/element (host props), Vike (pageContext.data, hydrated state) and renderComponent's
+ * `initialState` option; the caller may still change those). Mechanism: onIntent, which runs
+ * during construction, before the model is wired.
+ */
+import type {DiagnosticCheck} from '../index'
+import {OWNED} from '../../owned'
+
+const plain = (v: any): boolean => {
+  if (!v || typeof v != 'object') return false
+  const p = Object.getPrototypeOf(v)
+  return Array.isArray(v) || p === Object.prototype || p === null
+}
+
+const deepFreeze = (v: any): void => {
+  if (!plain(v) || Object.isFrozen(v) || v[OWNED]) return
+  Object.freeze(v)
+  for (const k of Object.keys(v)) deepFreeze(v[k])
+}
+
+const freeze = (o: any): void => {
+  if (!o || (typeof o != 'object' && typeof o != 'function')) return
+  deepFreeze(o.initialState)
+  for (const k of ['model', 'context', 'calculated']) if (plain(o[k])) Object.freeze(o[k])
+}
+
+export const staticsCheck: DiagnosticCheck = {
+  id: 'statics',
+
+  onIntent(component) {
+    if (typeof component?.view == 'function') freeze(component.view)
+    freeze(component?._o)
+  },
+}