sygnal 5.4.0 → 6.0.0

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

@@ -1,37 +1,108 @@
 /**
  * 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/HYDRATE (whole-state replacement)
+ *   - 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, once, nameOf, isPlainObject} from './shared'
+import {report, devReport, once, nameOf, isPlainObject} from './shared'
+import {ORIGINAL} from '../../../shared'
 
-const SKIP = new Set(['INITIALIZE', 'HYDRATE'])
+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) {
-      if (!once(`SYG202:${name}:${action}`)) return
-      // Returning undefined from a Collection item's reducer is the documented way to remove
-      // the item, so only the root (where it wipes the whole app state) is a warning.
+      // 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 ? ' (this removes the item if the component is a Collection item)' : ''),
+          (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},
       })
@@ -39,6 +110,28 @@ export const stateCheck: DiagnosticCheck = {
     }
 
     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)))

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)
+  },
+}

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

@@ -13,13 +13,14 @@
  *
  * | Code   | Rule (canonical form)                    | Runtime mechanism                       |
  * |--------|------------------------------------------|-----------------------------------------|
- * | SYG501 | C1 destructure the view's first argument | onModel: component.view.length > 1      |
- * | SYG502 | C3 return ABORT for "no change"          | onReducer: returned the previous state  |
- * |        |                                          | object (undefined stays SYG202)         |
- * | SYG504 | C5 object form, no 'ACTION | SINK' keys  | onModel: raw model keys containing '|'  |
- * | SYG503, SYG505, SYG506, SYG507: static only (sygnal-check --strict); the
- *   runtime can't tell emit() from { EVENTS }, a side effect from a pure
- *   reducer, or see CHILD.select() arguments without a core hook.
+ * | SYG508 | reply actions, not select()/errors()     | replies.ts: a request with a category   |
+ * |        | round trip (PLAN-3 §1.1)                 | the same instance select()ed on a       |
+ * |        |                                          | reply-capable source                    |
+ *
+ * SYG501 (positional views) and SYG504 ('ACTION | SINK' keys) are forms Sygnal 6.0 removed
+ * (D164): at run time they are SYG612 (checks/next.ts, strict or not); `sygnal-check --strict`
+ * still reports them under their own codes, with --fix. SYG502 is retired (PLAN-4 GS-4). SYG503,
+ * SYG505, SYG506, SYG507: static only (sygnal-check --strict).
  *
  * Every finding is reported once per component name (+ action / key).
  * The SYG5xx severities are registered here (registerCodes) and passed
@@ -28,7 +29,7 @@
 import type {DiagnosticCheck} from '../index'
 import {CODE_TITLES, STRICT_CODE_SEVERITY, registerCodes} from '../codes'
 import type {DiagnosticSeverity} from '../codes'
-import {bridge, report, once, nameOf, isInternalAction} from './shared'
+import {bridge} from './shared'
 
 registerCodes(Object.keys(STRICT_CODE_SEVERITY).map(code =>
   [code, STRICT_CODE_SEVERITY[code], CODE_TITLES[code]] as [string, DiagnosticSeverity, string]))
@@ -48,65 +49,7 @@ export function isStrictEnabled(): boolean {
   return flag === undefined ? (globalThis as any).__SYGNAL_STRICT__ === true : flag === true
 }
 
-const strictReport = (code: string, details: Parameters<typeof report>[1]) =>
-  report(code, {severity: STRICT_CODE_SEVERITY[code], ...details})
-
+/** The strict check's runtime half is SYG508 (replies.ts); this entry keeps the flag. */
 export const strictCheck: DiagnosticCheck = {
   id: 'strict',
-
-  onModel(component) {
-    if (!isStrictEnabled() || !component) return
-    const name = nameOf(component)
-
-    // SYG501 — view(props, state, context, peers): positional use of the 2nd+ args.
-    // (A default value or a rest parameter stops Function.length, so this can
-    // miss `(props, state = {})`, but it never flags a single-argument view.)
-    const view = component.view
-    if (typeof view === 'function' && view.length > 1 && !view.__sygnalLazy && once(`SYG501:${name}`)) {
-      const extra = ['state', 'context', 'peers'].slice(0, view.length - 1)
-      strictReport('SYG501', {
-        component,
-        message: `The view takes ${view.length} positional arguments (props, ${extra.join(', ')})`,
-        fix: `Destructure the first argument instead: function ${name}({ ${extra.join(', ')}, ...props })`,
-        data: {arity: view.length},
-      })
-    }
-
-    // SYG504 — 'ACTION | SINK' shorthand keys
-    const model = component.model
-    if (!model || typeof model !== 'object') return
-    for (const key of Object.keys(model)) {
-      if (!key.includes('|')) continue
-      const [action, sink] = key.split('|').map(s => s.trim())
-      if (!action || !sink || !once(`SYG504:${name}:${key}`)) continue
-      const rewrite = sink === 'EVENTS'
-        ? `${action}: { EVENTS: event('TYPE', (state, data) => payload) }`
-        : `${action}: { ${sink}: (state, data, next) => ... }`
-      strictReport('SYG504', {
-        component,
-        message: `Model key '${key}' uses the 'ACTION | SINK' shorthand`,
-        fix: `Use the object form: ${rewrite} (merge it into an existing '${action}' entry if there is one)`,
-        data: {key, action, sink},
-      })
-    }
-  },
-
-  onReducer(component, action, prevState, nextState) {
-    if (!isStrictEnabled() || isInternalAction(action)) return  // incl. INITIALIZE/HYDRATE/DISPOSE
-    // undefined is SYG202 (state check, every mode); only the identical object here.
-    if (!prevState || typeof prevState !== 'object' || nextState === undefined) return
-    let same = nextState === prevState
-    if (!same && typeof component?.addCalculated === 'function') {
-      // with calculated fields the reducer saw addCalculated(prev) (memoized: same object)
-      try { same = component.addCalculated(prevState) === nextState } catch (_) {}
-    }
-    const name = nameOf(component)
-    if (!same || !once(`SYG502:${name}:${action}`)) return
-    strictReport('SYG502', {
-      component,
-      message: `The STATE reducer for '${action}' returned the unchanged state object`,
-      fix: `Return ABORT for "no change": ${action}: (state, data) => cond ? { ...state, ... } : ABORT`,
-      data: {action},
-    })
-  },
 }

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

@@ -0,0 +1,80 @@
+/**
+ * Timers and declaration statics without a driver (PLAN-4 GS-7). Dev-entry-only codes
+ * (DEV_CODE_SEVERITY):
+ *
+ * SYG643 — a component declares a static that only a registered driver acts on (`timers`:
+ *          makeTimerDriver(), `connections`: makeSocketDriver(), `resources`: makeFetchDriver(),
+ *          `browser`: makeBrowserDriver())
+ *          and no source of the app takes it (no `__sygnalStatic` marker for it), so nothing
+ *          happens and nothing else says so. Also closes PLAN-3's "connections without a driver
+ *          report nothing" gap. (`route` and `head` are left out: renderComponent asks for the
+ *          router itself, and `head` is also collected by renderToString without a driver.)
+ * SYG422 — a timer spec makeTimerDriver() can't run (non-positive `every`, negative `after`,
+ *          `every` with `after`, no action, `frame` that isn't an action name): it isn't started.
+ *          The driver calls `__SYGNAL_DIAGNOSTICS__.timerSpec(name, spec, componentName)`, which
+ *          installTimerHooks() sets.
+ */
+import type {DiagnosticCheck} from '../index'
+import {bridge, devReport, once, nameOf} from './shared'
+
+const NEEDS: Record<string, string> = {
+  timers: 'makeTimerDriver()',
+  connections: 'makeSocketDriver()',
+  resources: 'makeFetchDriver()',
+  browser: 'makeBrowserDriver()',
+}
+const KEY: Record<string, string> = {timers: 'TIMER', connections: 'WS', resources: 'HTTP', browser: 'BROWSER'}
+
+const brief = (v: any) => { try { return JSON.stringify(v) } catch (_) { return String(v) } }
+
+/** why a timer spec can't run ('' when it can; mirrors timers.ts's valid()) */
+export function timerSpecProblem(s: any): string {
+  if (!s || typeof s != 'object') return 'is not an object ({ every, action }, { after, action } or { frame: action })'
+  if ('frame' in s && s.frame) return typeof s.frame == 'string' ? '' : 'frame must be the action name (a string)'
+  if (!s.action || typeof s.action != 'string') return 'has no action (a string)'
+  if (s.every == null && s.after == null) return 'has neither every nor after'
+  if (s.every != null && s.after != null) return 'has both every and after'
+  if (s.every != null) return s.every > 0 && s.every < 1 / 0 ? '' : `every must be a positive number of ms (got ${brief(s.every)})`
+  return s.after >= 0 && s.after < 1 / 0 ? '' : `after must be a number of ms, 0 or more (got ${brief(s.after)})`
+}
+
+function checkSpec(name: string, spec: any, component?: string) {
+  const problem = timerSpecProblem(spec) || 'is invalid'
+  if (!once(`SYG422:${component}:${name}:${brief(spec)}`)) return
+  devReport('SYG422', {
+    component,
+    message: `Timer '${name}' ${problem}; it is not started`,
+    fix: `Declare ${name}: { every: 100, action: 'TICK' }, { after: 5000, action: 'EXPIRE' } or { frame: 'FRAME' } (falsy to stop it)`,
+    data: {name, spec},
+  })
+}
+
+/** install the hook makeTimerDriver() calls for an invalid spec (removed by the returned function) */
+export function installTimerHooks(): () => void {
+  const core = bridge()
+  if (!core) return () => {}
+  core.timerSpec = checkSpec
+  return () => { if (core.timerSpec === checkSpec) core.timerSpec = undefined }
+}
+
+export const timersCheck: DiagnosticCheck = {
+  id: 'timers',
+
+  onModel(component) {
+    const sources = component?.sources, view = component?.view
+    if (!sources || typeof sources != 'object' || !view) return
+    const names = component.sourceNames || Object.keys(sources)
+    for (const k in NEEDS) {
+      if (view[k] == null) continue
+      if (names.some((n: string) => sources[n]?.__sygnalStatic === k)) continue
+      const name = nameOf(component)
+      if (!once(`SYG643:${name}:${k}`)) continue
+      devReport('SYG643', {
+        component,
+        message: `${name} declares ${name}.${k}, but no ${NEEDS[k]} driver is registered, so ${k == 'timers' ? 'its timers never run' : k == 'connections' ? 'its connections never open' : k == 'browser' ? 'its browser sources never start' : 'its resources are never fetched'}`,
+        fix: `Register the driver: run(App, { ${KEY[k]}: ${NEEDS[k]} })`,
+        data: {static: k, driver: NEEDS[k]},
+      })
+    }
+  },
+}

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

@@ -0,0 +1,47 @@
+/**
+ * View Transitions (PLAN-4 GS-12, D129). Dev-entry-only code (DEV_CODE_SEVERITY):
+ *
+ * SYG645 — a component declares `viewTransitions`, but its app's DOM driver can't run them (run()'s
+ *          default makeDOMDriver, not makeViewTransitionDOMDriver()), so its actions patch at once
+ *          and nothing else says so. The helper marks its IsolateModule (`vtDriver`). Not reported
+ *          for renderComponent's mock DOM (no IsolateModule) or its `dom: 'real'` container
+ *          (`.sygnal-test`): tests don't animate.
+ *          Also (G-228): the static is not an array (`true`, `'MOVE'`): no action is listed (the core
+ *          reads it with `includes?.()`, so a string matches substrings; anything else matches none).
+ */
+import type {DiagnosticCheck} from '../index'
+import {devReport, once, nameOf} from './shared'
+
+export const viewTransitionsCheck: DiagnosticCheck = {
+  id: 'viewTransitions',
+
+  onModel(component) {
+    const list = component?.view?.viewTransitions
+    if (list == null) return
+    if (!Array.isArray(list)) {
+      const name = nameOf(component)
+      if (!once(`SYG645:${name}`)) return
+      const actions = Object.keys(component.model || {}).filter(a => !a.includes('|'))
+      devReport('SYG645', {
+        component,
+        message: `${name}.viewTransitions is not an array (it is ${typeof list == 'string' ? `'${list}'` : typeof list}), so no action is listed for a View Transition`,
+        fix: `List the action names in an array: ${name}.viewTransitions = [${(typeof list == 'string' ? [list] : actions.slice(0, 2)).map(a => `'${a}'`).join(', ') || "'ACTION'"}] (an array of action names)`,
+        data: {value: list},
+      })
+      return
+    }
+    if (!list.length) return
+    const im = component.sources?.[component.DOMSourceName || 'DOM']?._isolateModule
+    // the core's DOM source proxy answers any unknown key with an event shorthand (a function)
+    if (typeof im != 'object' || !im || im.vtDriver) return
+    if (typeof document != 'undefined' && document.querySelector?.('.sygnal-test')) return
+    const name = nameOf(component)
+    if (!once(`SYG645:${name}`)) return
+    devReport('SYG645', {
+      component,
+      message: `${name} declares ${name}.viewTransitions (${list.map((a: any) => `'${a}'`).join(', ')}), but the app's DOM driver can't run View Transitions, so those actions patch without one`,
+      fix: `Give run() the View Transition DOM driver: run(App, { DOM: makeViewTransitionDOMDriver('#root') })`,
+      data: {actions: list},
+    })
+  },
+}

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

@@ -0,0 +1,73 @@
+/**
+ * PLAN-5 V-1: `<VirtualCollection>` diagnostics (dev entry; src/extra/virtual.ts carries no text).
+ *
+ * The VirtualCollection host calls `__SYGNAL_DIAGNOSTICS__.virtual(code, owner, extra)`:
+ *   430  the container has no bounded height: `extra.reason` 'height' (laid out 0 px tall) or
+ *        'grows' (as tall as all its rows and taller than the viewport, so it would render every
+ *        row); the window is clamped to the viewport (once per host and reason)
+ *   431  items without `id` (index keys; once per host)
+ *   432  an item renders a fragment or text, not one element (once per host)
+ *   433  scrollToIndex / scrollToId for an index or id not in the (filtered) list
+ *   434  estimateSize / overscan not a positive number (or a function, for estimateSize)
+ */
+import {devReport, nameOf} from './shared'
+
+const tag = (owner: any) => `<VirtualCollection> in ${nameOf(owner)}`
+
+export function reportVirtual(code: number, owner: any, x: any = {}): any {
+  const component = owner ? nameOf(owner) : 'VirtualCollection'
+  if (code == 430) {
+    const grows = x.reason == 'grows'
+    return devReport('SYG430', {
+      component,
+      message: grows
+        ? `${tag(owner)} grows with its rows (it is ${Math.round(x.height)} px tall, as tall as all of them), so it is not a scroll container; only the rows within the viewport's height render`
+        : `${tag(owner)} is 0 px tall, so no row is in view`,
+      fix: 'Give its className a bounded height (height or max-height, e.g. .rows { height: 400px }, or flex: 1 with min-height: 0 in a flex column); it scrolls itself (overflow-y: auto)',
+      data: x,
+    })
+  }
+  if (code == 431) {
+    return devReport('SYG431', {
+      component,
+      message: `${tag(owner)} has items without an id (${x.count} items): they are keyed by their index, so a row's instance and measured height follow its position, not its item, when items are added, removed or reordered`,
+      fix: "Give every item a unique id (e.g. rows: data.map((r, i) => ({ id: r.key ?? i, ...r })))",
+      data: x,
+    })
+  }
+  if (code == 432) {
+    return devReport('SYG432', {
+      component,
+      message: `${tag(owner)}: its item component ${x.component} renders a fragment or text, so its rows can't be measured, positioned or given aria-posinset`,
+      fix: `Make ${x.component}'s view return one element (wrap its content in a <div> or <li>)`,
+      data: x,
+    })
+  }
+  if (code == 433) {
+    const what = 'id' in x ? `id ${JSON.stringify(x.id) ?? String(x.id)}` : `index ${x.index}`
+    return devReport('SYG433', {
+      component,
+      message: `${tag(owner)}: ${'id' in x ? 'scrollToId' : 'scrollToIndex'} for ${what}, which is not in its list (${x.count} rows after filter); it didn't scroll`,
+      fix: 'id' in x
+        ? 'Send the id of an item in the array the filter keeps: { scrollToId: \'.rows\', id }'
+        : `Send an integer index from 0 to ${Math.max(0, x.count - 1)} into the shown (filtered, sorted) rows: { scrollToIndex: '.rows', index }`,
+      data: x,
+    })
+  }
+  if (code == 434) {
+    return devReport('SYG434', {
+      component,
+      message: `${tag(owner)}: ${x.prop}={${typeof x.value == 'string' ? JSON.stringify(x.value) : String(x.value)}} is not ${x.prop == 'overscan' ? 'a number ≥ 0; 5 is used' : 'a positive number or a function; 32 is used'}`,
+      fix: x.prop == 'overscan' ? 'Pass overscan={5} (rows rendered beyond each edge)' : 'Pass estimateSize={32} (about a row\'s height in px), or (item, index) => px',
+      data: x,
+    })
+  }
+}
+
+/** Publish the VirtualCollection hook on the core bridge. Returns an uninstall function. */
+export function installVirtualHooks(): () => void {
+  const c = (globalThis as any).__SYGNAL_DIAGNOSTICS__
+  if (!c) return () => {}
+  c.virtual = reportVirtual
+  return () => { if (c.virtual === reportVirtual) c.virtual = undefined }
+}