sygnal 5.3.7 → 6.0.0

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

@@ -0,0 +1,175 @@
+/**
+ * PLAN-4 GS-2: element command diagnostics (dev entry; the core carries no text).
+ *
+ * The core (src/extra/elementCommands.ts) calls `__SYGNAL_DIAGNOSTICS__.elementCommand(component,
+ * command, element?)` when a command can't run:
+ *   - no element (`element` falsy): SYG640 (warn): nothing in the sending instance's DOM scope
+ *     matched the target within about 1 s;
+ *   - an element, but neither the control's spec command nor a method of the element: SYG641
+ *     (error). It names the control's declared commands. When the element is a widget's host
+ *     (PLAN-5 W-1, `__sw`): SYG142 (error), naming the widget's declared commands.
+ * installElementCommandHooks() publishes it on the core bridge.
+ *
+ * When a command is sent (checkSentCommand, from the elementCommands check's onModel, which wraps
+ * the instance's ELEMENT stream before the core subscribes it): SYG641 for a value that is not a
+ * command object, and for a method that changes the DOM Sygnal renders (remove, append,
+ * setAttribute...): the core runs any method the element has, and those break the next patch.
+ *
+ * renderComponent uses these functions too (mock DOM, and the real DOM without the dev entry), so
+ * this module has no side effects and doesn't import ./shared (which registers codes when loaded).
+ */
+import type {DiagnosticCheck} from '../index'
+import {DEV_CODE_SEVERITY} from '../codes'
+
+/** The element commands Sygnal documents and types (the core runs any method of the element) */
+export const NATIVE_COMMAND_NAMES = ['focus', 'blur', 'select', 'click', 'scrollIntoView', 'showModal', 'show', 'close', 'showPopover', 'hidePopover', 'togglePopover']
+
+const core = (): any => (globalThis as any).__SYGNAL_DIAGNOSTICS__
+
+const send = (code: string, details: any): void => {
+  try {
+    core()?.report(code, {severity: DEV_CODE_SEVERITY[code], ...details})
+  } catch (err) {
+    // 'error' mode: rethrown asynchronously (never into the caller)
+    setTimeout(() => { throw err })
+  }
+}
+
+const isControl = (x: any): boolean => typeof x == 'function' && !!x.__sygnalControl
+const keyOf = (control: any): string => String(control).slice(15, -2)
+
+/** a command as written: `{ focus: Email, preventScroll: true }` */
+export const describeCommand = (cmd: any): string => {
+  if (!cmd || typeof cmd != 'object') return JSON.stringify(cmd) ?? String(cmd)
+  const parts = Object.keys(cmd).map(k => {
+    const v = cmd[k]
+    let text: string
+    if (isControl(v)) text = keyOf(v)
+    else try { text = JSON.stringify(v) ?? String(v) } catch (_) { text = String(v) }
+    return `${k}: ${text}`
+  })
+  return `{ ${parts.join(', ')} }`
+}
+
+const 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 cur = row[j]
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] == b[j - 1] ? 0 : 1))
+      prev = cur
+    }
+  }
+  return row[b.length]
+}
+
+const closest = (name: string, names: string[]): string | undefined => {
+  let best: string | undefined, d = 3
+  for (const n of names) {
+    const x = n.toLowerCase() == name.toLowerCase() ? 0 : distance(name, n)
+    if (x < d) { d = x; best = n }
+  }
+  return best
+}
+
+const tagOf = (el: any): string => el && typeof el.tagName == 'string' ? `<${el.tagName.toLowerCase()}>` : 'element'
+
+const notACommand = (component: any, name: string, cmd: any) => send('SYG641', {
+  component,
+  message: `${name} sent ${describeCommand(cmd)} to the ELEMENT sink, which is not a command`,
+  fix: `Send { <method>: control or selector, ...options }, e.g. { focus: Email }, or an array of them`,
+  data: {command: cmd},
+})
+
+/** SYG640 (no `el`) or SYG641 (an element, but no command of that name) for `cmd` sent by `component` */
+export function reportElementCommand(component: any, cmd: any, el?: any): void {
+  // a disposed instance's pending commands are dropped silently
+  if (component && component._disposed) return
+  const name = (component && component.name) || 'component'
+  const method = cmd && typeof cmd == 'object' ? Object.keys(cmd)[0] : undefined
+  if (method === undefined) return notACommand(component, name, cmd)
+  const target = cmd[method]
+  const what = `ELEMENT ${describeCommand(cmd)}`
+  const control = isControl(target) ? keyOf(target) : undefined
+  const data: any = {method, command: cmd, ...(control ? {control} : {selector: target == null ? target : String(target)})}
+  if (!el) {
+    const missing = target == null || target === ''
+    return send('SYG640', {
+      component,
+      message: missing
+        ? `${what} in ${name} has no target (${String(target)}), so the command was dropped`
+        : `${what} in ${name} matched no element: nothing in ${name}'s own view matches ${control ? `the control ${control}` : `'${String(target)}'`} (waited 1 s), so the command was dropped`,
+      fix: missing
+        ? `Give the method a control or a selector: { ${method}: Email }`
+        : `Render the element in ${name}'s view, or send the command from the component that renders it: a child component's elements are isolated from its parent, and a command reaches only its sender's own elements (in a Collection, each item sends its own)`,
+      data,
+    })
+  }
+  // PLAN-5 W-1: the matched element is a widget's host (selector or control target): SYG142 names
+  // the widget's declared commands
+  const widget = el.__sw?.w
+  if (widget) {
+    const declared = Object.keys(widget.commands)
+    const hint = closest(method, [...declared, ...NATIVE_COMMAND_NAMES])
+    return send('SYG142', {
+      component,
+      message: `${what} in ${name}: the matched ${tagOf(el)} is a widget's host, and the widget declares no '${method}' command` +
+        (hint ? ` (did you mean '${hint}'?)` : '') + (declared.length ? `; it declares: ${declared.join(', ')}` : '; it declares none'),
+      fix: `Add '${method}' to the widget's commands (defineWidget({ commands: { ${method}: (instance, options) => … } })), or send one it declares`,
+      data: {...data, element: tagOf(el), commands: declared},
+    })
+  }
+  const commands = control && target.spec && typeof target.spec == 'object' && target.spec.commands
+    ? Object.keys(target.spec.commands) : []
+  data.element = tagOf(el)
+  if (commands.length) data.commands = commands
+  let message: string, fix: string
+  if (NATIVE_COMMAND_NAMES.includes(method)) {
+    message = `${what} in ${name}: the matched ${tagOf(el)} has no ${method}() method${commands.length ? `, and the control ${control}'s spec declares no '${method}' command (it declares: ${commands.join(', ')})` : ''}`
+    fix = /^(show|showModal|close)$/.test(method)
+      ? `${method}() works on a <dialog> element: render the target as a <dialog>`
+      : /Popover$/.test(method)
+        ? `The popover methods need an element with the popover attribute (attrs: { popover: 'auto' }) in a browser with the Popover API`
+        : `Target an element that has ${method}()`
+  } else {
+    const hint = closest(method, [...commands, ...NATIVE_COMMAND_NAMES])
+    message = `${what} in ${name}: '${method}' is not an element command` + (hint ? ` (did you mean '${hint}'?)` : '') +
+      (el.tagName ? `: the matched ${tagOf(el)} has no such method` : '') +
+      (commands.length ? `, and the control ${control}'s spec declares only: ${commands.join(', ')}` : '')
+    fix = `Use ${commands.length ? `one of its commands (${commands.join(', ')}) or ` : ''}one of: ${NATIVE_COMMAND_NAMES.join(', ')} (or another method of the element, like play). The first key of a command is the method, the others are its options: { scrollIntoView: Row, block: 'nearest' }`
+  }
+  send('SYG641', {component, message, fix, data})
+}
+
+// methods that change the DOM snabbdom owns (the next patch undoes them or trips over them)
+const DOM_MUTATORS = /^(remove|append|prepend|before|after|replaceWith|replaceChildren|appendChild|removeChild|insertBefore|replaceChild|insertAdjacent(Element|HTML|Text)|(set|remove|toggle)Attribute(NS|Node)?|attachShadow|setHTML(Unsafe)?|normalize)$/
+
+/** SYG641 when it is sent: not a command object, or a method that changes the DOM Sygnal renders */
+export function checkSentCommand(component: any, cmd: any): void {
+  if (cmd == null) return
+  const name = (component && component.name) || 'component'
+  if (typeof cmd != 'object' || Array.isArray(cmd) || !Object.keys(cmd).length) return notACommand(component, name, cmd)
+  const method = Object.keys(cmd)[0], target = cmd[method]
+  if (!DOM_MUTATORS.test(method) || (isControl(target) && target.spec?.commands?.[method])) return
+  send('SYG641', {
+    component,
+    message: `ELEMENT ${describeCommand(cmd)} in ${name}: ${method}() changes the DOM that ${name}'s view renders, so the next render undoes it or fails`,
+    fix: `Change the state and render the result instead; element commands are for what a view can't express (focus, scrolling, dialogs, popovers, media)`,
+    data: {method, command: cmd},
+  })
+}
+
+/** The dev entry check: checkSentCommand runs on every ELEMENT value through the core's onElementCommand hook (checks/next.ts) */
+export const elementCommandsCheck: DiagnosticCheck = {
+  id: 'elementCommands',
+}
+
+/** Publish the element command hook on the core bridge. Returns an uninstall function. */
+export function installElementCommandHooks(): () => void {
+  const c = core()
+  if (!c) return () => {}
+  c.elementCommand = reportElementCommand
+  return () => { if (c.elementCommand === reportElementCommand) c.elementCommand = undefined }
+}

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

@@ -0,0 +1,83 @@
+/**
+ * SYG105 — EVENTS type emitted but never selected, or selected but never
+ * emitted (info).
+ * SYG116 — a value with no string `type` (typically a function) reached the
+ * EVENTS bus (error, G-143).
+ *
+ * Mechanism: the EVENTS driver (src/extra/eventDriver.ts) calls onBusSelect
+ * for every EVENTS.select(type) and onBusEmit for every bus event.
+ *   - emitted, nothing selects it: reported when the event is emitted. The bus
+ *     is a broadcast, so an event nobody has subscribed to by then is dropped.
+ *   - selected, never emitted: only knowable at the end of a session, so it is
+ *     reported on demand by checkEventBus() (inspect / test helpers), never
+ *     automatically.
+ * EVENTS.select() with no type (all events) counts as selecting everything.
+ */
+import type {DiagnosticCheck} from '../index'
+import {report, devReport, once, onReset, didYouMean} from './shared'
+
+let selected = new Set<string>()
+let emitted = new Set<string>()
+let selectsAll = false
+
+onReset(() => { selected = new Set(); emitted = new Set(); selectsAll = false })
+
+export const eventsCheck: DiagnosticCheck = {
+  id: 'events',
+
+  onBusSelect(type) {
+    if (type === undefined || type === null || type === '') { selectsAll = true; return }
+    for (const t of ([] as any[]).concat(type)) if (typeof t === 'string') selected.add(t)
+  },
+
+  onBusEmit(type, emitterName) {
+    if (typeof type !== 'string') {
+      // SYG116 (G-143): no EVENTS.select() can ever receive it. The core copies each emitted
+      // value into a new object (devtools stamp), so a function arrives here as {}.
+      if (once(`SYG116:${emitterName}`)) {
+        devReport('SYG116', {
+          component: emitterName,
+          message: `${emitterName ? emitterName + "'s model" : 'A model'} sent a value with no string 'type' to the EVENTS sink, so nothing receives it. ` +
+            `The value was probably a function (a model entry that returns event(...) instead of being event(...)), or undefined/null`,
+          fix: `Make event() the sink entry itself: ACTION: { EVENTS: event('TYPE', (state, data) => payload) }; return ABORT to send nothing`,
+          data: {type, emitter: emitterName},
+        })
+      }
+      return
+    }
+    emitted.add(type)
+    if (selectsAll || selected.has(type) || !once(`SYG105:emit:${type}`)) return
+    report('SYG105', {
+      component: emitterName,
+      message: `EVENTS event '${type}' was emitted, but nothing selects it, so it was dropped${didYouMean(type, selected)}`,
+      fix: `Subscribe with EVENTS.select('${type}') in the component that should react, or check the event name`,
+      data: {type, direction: 'emitted-not-selected', emitter: emitterName},
+    })
+  },
+}
+
+export interface EventBusSummary {
+  selected: string[]
+  emitted: string[]
+  selectedNeverEmitted: string[]
+  emittedNeverSelected: string[]
+}
+
+/**
+ * Report SYG105 (info) for every EVENTS type that has been selected but never
+ * emitted so far, and return the bus registry. Intended for inspect tooling and
+ * tests, at a point where the session is "done".
+ */
+export function checkEventBus(): EventBusSummary {
+  const selectedNeverEmitted = [...selected].filter(t => !emitted.has(t))
+  const emittedNeverSelected = selectsAll ? [] : [...emitted].filter(t => !selected.has(t))
+  for (const type of selectedNeverEmitted) {
+    if (!once(`SYG105:select:${type}`)) continue
+    report('SYG105', {
+      message: `EVENTS.select('${type}') is used, but no component has emitted '${type}'${didYouMean(type, emitted)}`,
+      fix: `Emit it from a model entry, e.g. { EVENTS: event('${type}', ...) }, or check the event name`,
+      data: {type, direction: 'selected-not-emitted'},
+    })
+  }
+  return {selected: [...selected], emitted: [...emitted], selectedNeverEmitted, emittedNeverSelected}
+}

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

@@ -0,0 +1,135 @@
+/**
+ * makeFetchDriver requests (PLAN-3 5-3: the query cache, D79/D80; G-175). Dev-entry codes
+ * (DEV_CODE_SEVERITY):
+ *
+ * SYG630 — a cached request that is not idempotent: `cache: true` or `staleTime` on a
+ *          POST/PUT/PATCH/DELETE (a request with a body defaults to POST) (warn)
+ * SYG631 — `validate` is not a Standard Schema (no `~standard.validate`): the request
+ *          fails (error)
+ * SYG632 — `{ invalidate }` matched no cache entry and no mounted resource (info)
+ * SYG633 — `{ abort: 'X' }` cancels the lane 'X', but this instance sends its `ok: 'X'`
+ *          requests under another `key`, so nothing is cancelled (warn)
+ * SYG635 — `cache: true` / `staleTime` / `{ prefetch }` sent to a driver without a
+ *          `queryCache()` (D88): nothing is cached (warn). The source's `__inspect().cache`
+ *          is undefined without one
+ *
+ * Mechanism: onModel wraps the component's own model stream for every sink whose source
+ * takes the `resources` static (makeFetchDriver and renderComponent's HTTP fake) and checks
+ * each value as it is sent: requests, and each entry of a `{ resources }` declaration.
+ * SYG632 asks the source how many entries/resources the value matches (`__matches`).
+ * Each is reported once per component name and request URL / name.
+ */
+import type {DiagnosticCheck} from '../index'
+import {devReport, once, nameOf} from './shared'
+import {isStandardSchema} from '../../standardSchema'
+
+const IDEMPOTENT = /^(GET|HEAD)$/i
+
+/** instance → reply key lanes it has sent, and ok name → the other key it was sent under */
+const lanes = new WeakMap<object, {used: Set<string>; keyed: Map<string, string>}>()
+
+const fetchSink = (component: any, name: string) => component?.sources?.[name]?.__sygnalStatic === 'resources'
+/** 5-5: the sink's driver has no queryCache() */
+const noCache = (component: any, sink: string) => {
+  const i = component?.sources?.[sink]?.__inspect?.()
+  return !!i && i.cache === undefined
+}
+const reportNoCache = (component: any, sink: string, what: string, url: string) => {
+  if (!noCache(component, sink) || !once(`SYG635:${nameOf(component)}:${what}:${url}`)) return
+  devReport('SYG635', {
+    component,
+    message: `${sink} ${url ? url + ' ' : ''}uses ${what}, but the ${sink} driver has no queryCache(), so nothing is cached`,
+    fix: `Give the driver a cache: makeFetchDriver({ cache: queryCache({ staleTime: 30000 }) }) (import { queryCache } from 'sygnal'); in tests renderComponent(C, { http: { cache: queryCache() } }). Or remove ${what}`,
+    data: {sink, url, what},
+  })
+}
+
+function checkOne(component: any, sink: string, req: any, where: string) {
+  if (!req || typeof req !== 'object') return
+  const name = nameOf(component)
+  const url = typeof req.url === 'string' ? req.url : ''
+  const method = String(req.method || (req.json !== undefined || req.body !== undefined ? 'POST' : 'GET')).toUpperCase()
+  if ((req.cache === true || req.staleTime != null) && !IDEMPOTENT.test(method) && once(`SYG630:${name}:${method}:${url}`)) {
+    devReport('SYG630', {
+      component,
+      message: `${where} ${method} ${url} sets ${req.cache === true ? 'cache: true' : 'staleTime'}, so a cached reply answers it instead of sending it again`,
+      fix: `Cache reads only: remove ${req.cache === true ? 'cache' : 'staleTime'} from the ${method}, and refresh the cached reads after it succeeds with invalidates: ['tag']`,
+      data: {sink, method, url},
+    })
+  }
+  if (req.cache === true || req.staleTime != null) reportNoCache(component, sink, req.cache === true ? 'cache: true' : 'staleTime', url)
+  if ('validate' in req && !isStandardSchema(req.validate) && once(`SYG631:${name}:${url}`)) {
+    devReport('SYG631', {
+      component,
+      message: `${where} ${url} has validate: ${typeof req.validate}, which is not a Standard Schema, so the request fails`,
+      fix: "Pass a Standard Schema object (zod, valibot, arktype, ...: anything with a '~standard'.validate function), e.g. validate: QuoteSchema",
+      data: {sink, url},
+    })
+  }
+}
+
+export function check(component: any, sink: string, req: any) {
+  if (!req || typeof req !== 'object') return
+  const name = nameOf(component)
+  const res = req.resources
+  if (res && typeof res === 'object') {
+    for (const k of Object.keys(res)) checkOne(component, sink, typeof res[k] === 'string' ? {url: res[k]} : res[k], `${name}.resources.${k}:`)
+    return
+  }
+  if (req.prefetch) {
+    const p = req.prefetch
+    reportNoCache(component, sink, '{ prefetch }', typeof p === 'string' ? p : String(p?.url ?? ''))
+    return
+  }
+  if ('invalidate' in req) {
+    const count = component.sources[sink]?.__matches?.(req.invalidate)
+    const what = typeof req.invalidate === 'function' ? 'the predicate' : JSON.stringify(req.invalidate)
+    if (count === 0 && once(`SYG632:${name}:${what}`)) {
+      devReport('SYG632', {
+        component,
+        message: `${sink} { invalidate: ${what} } matched no cache entry and no mounted resource`,
+        fix: "Give the resources (or cached requests) to refresh tags: ['quotes'] and invalidate that tag, or a URL prefix starting with '/' ('/api/quotes')",
+        data: {sink, invalidate: what},
+      })
+    }
+    return
+  }
+  let l = lanes.get(component)
+  if (!l) lanes.set(component, (l = {used: new Set(), keyed: new Map()}))
+  const {ok, error, key, abort} = req
+  if (typeof abort === 'string' && key === undefined) {
+    const other = l.keyed.get(abort)
+    if (other !== undefined && !l.used.has(abort) && once(`SYG633:${name}:${abort}`)) {
+      devReport('SYG633', {
+        component,
+        message: `${sink} { abort: '${abort}' } cancels the requests with key '${abort}', but ${name} sends its ok: '${abort}' requests with key: '${other}', so nothing is cancelled`,
+        fix: `Cancel by that key: { abort: true, key: '${other}' } (or drop the key, so the lane is the ok action)`,
+        data: {sink, abort, key: other},
+      })
+    }
+    return
+  }
+  if (typeof ok === 'string' || typeof error === 'string') {
+    const lane = key ?? ok ?? error
+    l.used.add(lane)
+    if (typeof ok === 'string' && key !== undefined && key !== ok) l.keyed.set(ok, String(key))
+  }
+  checkOne(component, sink, req, `A ${sink} request`)
+}
+
+export const fetchCheck: DiagnosticCheck = {
+  id: 'fetch',
+
+  onModel(component) {
+    const model$ = component?.model$
+    if (!model$ || typeof model$ !== 'object') return
+    for (const sink of Object.keys(model$)) {
+      const s$ = model$[sink]
+      if (!fetchSink(component, sink) || !s$ || typeof s$.map !== 'function') continue
+      model$[sink] = s$.map((req: any) => {
+        try { check(component, sink, req) } catch (_) {}
+        return req
+      })
+    }
+  },
+}

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

@@ -0,0 +1,163 @@
+/**
+ * PLAN-5 F-1: `form` behavior diagnostics (dev entry; src/extra/form.ts carries no text).
+ *
+ * The form module calls `__SYGNAL_DIAGNOSTICS__.form(code, ...args)`:
+ *   231  form(schema) with a schema that isn't a Standard Schema: throws the SYG231 Error (in
+ *        production the first validation throws a plain TypeError)
+ *   230  (name, values) an input / focusout from a named field whose name isn't in `values`:
+ *        SYG230 (warn, once per name); the event is ignored
+ *   232  (slice) a submit while submitting or while a queued submit waits for a check: SYG232
+ *        (info, every time); the submit is dropped
+ *   233  (values, output) a valid submit: each top-level `values` key missing from the schema's
+ *        output, SYG233 (warn, once per key): the schema strips it (zod's z.object does). G-377:
+ *        only when every output key is a values key (an output with other keys reshapes: a rename)
+ *   235  (field, request) a check's request with `ok` / `error` / `latest` keys, which the form
+ *        overwrites: SYG235 (warn, once per field)
+ *   234  (submit, key) G-577: a valid submit whose `submit` names one of the form's own actions,
+ *        so it dispatched '<key>.<submit>' instead of the host's action: SYG234 (warn, once per
+ *        key and name), at the submit (the form's own action then often throws: SYG214 / SYG216)
+ * Host checks (onModel, once per component name), for each `uses` entry made by form():
+ *   SYG234 (warn) `submit` missing, not a host model entry, or one of the form's own action names
+ *          (G-577: every action in that form's model, CHECKED_<field> included)
+ *   SYG235 (warn) a `check` key that isn't a field of `values`
+ *   SYG236 (warn) an array of objects in `values` with a row without an `id`
+ *   SYG237 (warn) two form uses of one host with the same form selector (G-374)
+ */
+import type {DiagnosticCheck} from '../index'
+import {devReport, once, nameOf} from './shared'
+import {docsUrlFor} from '../codes'
+import {hasField} from '../../formHelpers'
+
+// the form's own action names (G-577: read from the form's model, so CHECKED_<field> counts)
+const ownActions = (b: any): string[] => Object.keys(b?.model || {})
+const SUBMIT_FIX = (key: string, a: string, own: string[]) =>
+  `Name the submit after a host action the form doesn't define (not ${own.join(', ')}): submit: 'SAVE', and rename the model entry '${a}' to SAVE: { HTTP: (state, values) => ({ url, json: values, ok: '${key}.DONE', error: '${key}.ERRORS' }) }`
+const RESERVED = ['ok', 'error', 'latest']
+
+const what = (v: any): string =>
+  v === null || v === undefined ? String(v)
+  : typeof v == 'function' ? 'a function'
+  : Array.isArray(v) ? 'an array'
+  : typeof v == 'object' ? `an object without ~standard.validate${typeof v.parse == 'function' ? ' (a validator from before Standard Schema?)' : ''}`
+  : `a ${typeof v}`
+
+export function reportForm(code: number, a?: any, b?: any, c?: any): any {
+  if (code == 231) {
+    const err: any = new TypeError(`[Sygnal SYG231] form(schema, options): the schema is ${what(a)}, not a Standard Schema. ` +
+      `Pass a Standard Schema object: a zod, valibot or arktype schema, or an object with '~standard': { version: 1, vendor, validate }. ${docsUrlFor('SYG231')}`)
+    err.code = 'SYG231'
+    throw err
+  }
+  if (code == 230) {
+    if (!once(`SYG230:${a}`)) return
+    devReport('SYG230', {
+      component: 'form',
+      message: `form: a field named '${a}' changed, but '${a}' isn't a field of the form's values (${Object.keys(b || {}).join(', ') || 'none'}); the change is ignored`,
+      fix: `Name the input after a path in values (name="email", name="addresses.<row id>.city"), add '${a}' to values, or move the input out of the form element`,
+      data: {name: a},
+    })
+  } else if (code == 232) {
+    devReport('SYG232', {
+      component: 'form',
+      message: `form: a submit was dropped: ${a?.submitting ? 'the previous submit is still being sent (no form.DONE / form.ERRORS yet)' : 'a submit is already queued, waiting for an async check or an async schema'}`,
+      fix: `Disable the submit button while state.form.submitting (or queued) is true; answer the submit with ok: 'form.DONE', error: 'form.ERRORS'`,
+    })
+  } else if (code == 233) {
+    if (!b || typeof b != 'object' || Object.keys(b).some(k => !(k in (a || {})))) return
+    for (const k of Object.keys(a || {})) {
+      if (!(k in b) && once(`SYG233:${k}`)) devReport('SYG233', {
+        component: 'form',
+        message: `form: values.${k} is not in the schema's output (stripped or renamed), so the submit action doesn't get it under that name (a schema strips keys it doesn't declare)`,
+        fix: `Declare '${k}' in the schema (or make the schema keep unknown keys), or remove it from values; if the schema renames it on purpose, ignore this`,
+        data: {key: k},
+      })
+    }
+  } else if (code == 234) {
+    if (!once(`SYG234:run:${b}:${a}`)) return
+    devReport('SYG234', {
+      component: 'form',
+      message: `form '${b}': a valid submit dispatched '${b}.${a}' (the form's own ${a} action), not the host's '${a}': submit: '${a}' names one of the form's own actions, which next() prefers`,
+      fix: SUBMIT_FIX(b, a, ownActions(c)),
+      data: {key: b, submit: a},
+    })
+  } else if (code == 235) {
+    const set = RESERVED.filter(k => b && k in b)
+    if (set.length && once(`SYG235:req:${a}`)) devReport('SYG235', {
+      component: 'form',
+      message: `form: the check for '${a}' returns a request with ${set.map(k => `'${k}'`).join(', ')}; the form sets them itself (its reply action and latest: true), so they are replaced`,
+      fix: `Return only the request: check: { ${a}: { request: (v) => ({ url, query }), error: (body) => message } }`,
+      data: {field: a, keys: set},
+    })
+  }
+}
+
+/** row ids missing in `values`: the names of the arrays of objects that have a row without an id */
+const missingIds = (v: any, at = '', out: string[] = []): string[] => {
+  if (v && typeof v == 'object') {
+    if (Array.isArray(v) && v.some(r => r && typeof r == 'object' && !Array.isArray(r) && r.id == null)) out.push(at)
+    for (const k in v) missingIds(v[k], at ? `${at}.${k}` : k, out)
+  }
+  return out
+}
+
+export const formsCheck: DiagnosticCheck = {
+  id: 'forms',
+
+  onModel(component) {
+    const view = component?.view, uses = view?.uses
+    if (!uses || typeof uses != 'object') return
+    const name = nameOf(component), sels: Record<string, string> = {}
+    for (const key of Object.keys(uses)) {
+      const b = uses[key]
+      if (!b?.form) continue
+      // G-374: each form listens on its selector inside the host, so two with one selector hear
+      // each other's fields and submits
+      const sel = b.options?.form || 'form'
+      if (sel in sels) {
+        if (once(`SYG237:${name}:${sel}`)) devReport('SYG237', {
+          component,
+          message: `${name}'s forms '${sels[sel]}' and '${key}' both listen on '${sel}', so each hears the other's fields and submits`,
+          fix: `Give each form element its own class and pass it: ${sels[sel]}: form(schema, { ..., form: '.${sels[sel]}' }), ${key}: form(schema, { ..., form: '.${key}' })`,
+          data: {keys: [sels[sel], key], form: sel},
+        })
+      } else sels[sel] = key
+      if (!once(`SYG23x:${name}:${key}`)) continue
+      const o = b.options || {}, values = o.values || {}
+      const model = Object.keys(view.model || {}).map(a => a.split('|')[0].trim()), own = ownActions(b)
+      const clash = own.includes(o.submit)
+      if (typeof o.submit != 'string' || !model.includes(o.submit) || clash) {
+        devReport('SYG234', {
+          component,
+          message: typeof o.submit != 'string' ? `${name}'s form '${key}' has no submit action, so a valid submit dispatches nothing`
+            : clash ? `${name}'s form '${key}' names submit: '${o.submit}', one of the form's own actions; a valid submit dispatches the form's '${key}.${o.submit}'${model.includes(o.submit) ? `, never ${name}'s '${o.submit}' entry` : ''}`
+            : `${name}'s form '${key}' dispatches '${o.submit}' on a valid submit, but ${name} has no model entry '${o.submit}'`,
+          fix: clash ? SUBMIT_FIX(key, o.submit, own)
+            : `Name a host action and add it to the model: submit: 'SIGN_UP', model: { SIGN_UP: { HTTP: (state, values) => ({ url, json: values, ok: '${key}.DONE', error: '${key}.ERRORS' }) } }`,
+          data: {key, submit: o.submit},
+        })
+      }
+      for (const f of Object.keys(o.check || {})) {
+        if (!hasField(values, f)) devReport('SYG235', {
+          component,
+          message: `${name}'s form '${key}' has a check for '${f}', which isn't a field of its values; it never runs`,
+          fix: `Use a field name from values (${Object.keys(values).join(', ')})`,
+          data: {key, field: f},
+        })
+      }
+      for (const at of missingIds(values)) devReport('SYG236', {
+        component,
+        message: `${name}'s form '${key}': values.${at} has rows without an id, so its fields are named by index and errors, touched state and focus don't follow a row when another is removed`,
+        fix: `Give each row a unique id: ${at}: [{ id: 1, ... }] (form.ADD numbers new rows itself)`,
+        data: {key, field: at},
+      })
+    }
+  },
+}
+
+/** Install the `form` hook on the core bridge (form.ts calls it). */
+export function installFormHooks(): () => void {
+  const c = (globalThis as any).__SYGNAL_DIAGNOSTICS__
+  if (!c) return () => {}
+  c.form = reportForm
+  return () => { if (c.form === reportForm) c.form = undefined }
+}