sygnal 5.4.0 → 6.0.0

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

@@ -0,0 +1,96 @@
+/**
+ * Browser sources (PLAN-5 B-3, src/extra/browserSources.ts). Dev-entry-only codes
+ * (DEV_CODE_SEVERITY), reported when the driver calls
+ * `__SYGNAL_DIAGNOSTICS__.browserSource(code, name, spec, componentName, extra)`:
+ *
+ * SYG663 — a `browser` entry the driver can't start (no known kind, no `action`, an intersection
+ *          / resize target that is neither a selector nor `true`), or a BROWSER sink command
+ *          with an unknown method. It isn't started / run.
+ * SYG664 — a kind the driver wasn't made with (`makeBrowserDriverWith(...)` without its source).
+ * SYG665 — a source or command failed (permission denied, API missing, storage blocked) and its
+ *          spec names no `error` action, so nothing else would say so.
+ * SYG668 — an intersection / resize declaration with nothing to observe: no DOM source reached
+ *          the driver for the instance (extra 'dom'), or, in renderComponent's fake with
+ *          `dom: 'real'`, its selector matches no element of the component (extra 'none').
+ *
+ * A component declaring `browser` with no browser driver is SYG643 (checks/timers.ts).
+ */
+import {bridge, devReport, once} from './shared'
+
+const KINDS = ['intersection', 'resize', 'media', 'storage', 'visibility', 'online', 'geolocation']
+const SOURCE: Record<string, string> = {
+  intersection: 'intersectionSource', resize: 'resizeSource', media: 'mediaSource', storage: 'storageSource',
+  visibility: 'visibilitySource', online: 'onlineSource', geolocation: 'geolocationSource',
+  copy: 'clipboardSource', paste: 'clipboardSource', setItem: 'storageSource', removeItem: 'storageSource',
+}
+const brief = (v: any) => { try { return JSON.stringify(v) } catch (_) { return String(v) } }
+
+/** why a declared spec can't start ('' when it can; mirrors browserDriver's checks) */
+export function browserSpecProblem(s: any): string {
+  if (!s || typeof s != 'object') return `is not an object ({ ${KINDS.join(' | ')}: …, action })`
+  const k = KINDS.find(k => k in s)
+  if (!k) return `names no source (one of ${KINDS.join(', ')})`
+  if (!s.action || typeof s.action != 'string') return 'has no action (a string)'
+  if ((k == 'intersection' || k == 'resize') && s[k] !== true && (typeof s[k] != 'string' || !s[k])) return `${k} must be a selector in the component or true (its root element), got ${brief(s[k])}`
+  return ''
+}
+
+function onBrowserSource(code: string, name: string, spec: any, component?: string, extra?: any, commands?: string[]) {
+  if (code == 'SYG663' && extra === 0) {
+    // an unknown command (extra 0; `commands`: the driver's)
+    if (!once(`SYG663:${component}:cmd:${name}`)) return
+    devReport('SYG663', {
+      component,
+      message: `BROWSER command '${name}' is unknown; it is not run`,
+      fix: `Name the method as a key of the command: ${(commands || []).map(c => `{ ${c}: … }`).join(', ') || 'this driver takes no commands'}`,
+      data: {name, command: spec},
+    })
+    return
+  }
+  if (code == 'SYG663') {
+    if (!once(`SYG663:${component}:${name}:${brief(spec)}`)) return
+    devReport('SYG663', {
+      component,
+      message: `browser entry '${name}' ${browserSpecProblem(spec) || 'is invalid'}; it is not started`,
+      fix: `Declare ${name}: { media: '(prefers-color-scheme: dark)', action: 'DARK' }, { intersection: '.card', action: 'SEEN' }, … (falsy to stop it)`,
+      data: {name, spec},
+    })
+  } else if (code == 'SYG664') {
+    if (!once(`SYG664:${component}:${name}`)) return
+    devReport('SYG664', {
+      component,
+      message: `browser entry '${name}' uses the ${extra} source, which this browser driver wasn't made with; it is not started`,
+      fix: `Add it: makeBrowserDriverWith(${SOURCE[extra]}, …), or use makeBrowserDriver() (every source)`,
+      data: {name, spec, kind: extra},
+    })
+  } else if (code == 'SYG668') {
+    if (!once(`SYG668:${component}:${name}:${extra}`)) return
+    const k = KINDS.find(k => spec && k in spec) || 'intersection', target = spec?.[k]
+    devReport('SYG668', {
+      component,
+      message: extra == 'none'
+        ? `browser entry '${name}' observes ${brief(target)}, which matches no element of the component; it reports nothing`
+        : `browser entry '${name}' (${k}) has no DOM to observe: the component's DOM source didn't reach the browser driver; it reports nothing`,
+      fix: extra == 'none'
+        ? `Use a selector the component's own view renders (or true for its root element), and declare the entry only while that element exists`
+        : `Run the app with a DOM driver (run() with a mount point) and declare intersection / resize in a component's own \`browser\` static`,
+      data: {name, spec, reason: extra},
+    })
+  } else if (code == 'SYG665') {
+    if (!once(`SYG665:${component}:${name}:${extra?.name ?? extra?.code}`)) return
+    devReport('SYG665', {
+      component,
+      message: `browser ${spec && 'action' in spec ? `entry '${name}'` : `command '${name}'`} failed (${extra?.message || extra?.name || 'error'}) and names no error action`,
+      fix: `Name one to handle it, e.g. { ..., error: 'FAILED' }, and a model entry FAILED: (state, { message }) => ...`,
+      data: {name, spec, failure: extra},
+    })
+  }
+}
+
+/** install the hook the browser driver calls (removed by the returned function) */
+export function installBrowserSourceHooks(): () => void {
+  const core = bridge()
+  if (!core) return () => {}
+  core.browserSource = onBrowserSource
+  return () => { if (core.browserSource === onBrowserSource) core.browserSource = undefined }
+}

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

@@ -20,7 +20,7 @@ import {reportSafely, once, nameOf, isPlainObject} from './shared'
 const describe = (v: any): string =>
   v === null ? 'null' : v === undefined ? 'undefined' : Array.isArray(v) ? 'an array' : typeof v === 'object' ? 'an object' : `a ${typeof v}`
 
-function checkCollection(component: any, el: any): void {
+export function checkCollection(component: any, el: any): void {
   const props = (el && el.data && el.data.props) || {}
   const from = props.from
   const of = props.of

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

@@ -0,0 +1,148 @@
+/**
+ * PLAN-4 CT-1, runtime control checks (dev entry only; the static ones are in sygnal-check).
+ *
+ * SYG124 (error): a component passed where a control or selector is expected, as in
+ *   `DOM.click(TodoItem)` or `DOM.select(TodoItem)`. Mechanism: the `sources` hook wraps the
+ *   component's DOM source in a Proxy; `select()` (also chained: `DOM.select('.x').select(C)`)
+ *   and every event shorthand check their first argument. A function that isn't a control is a
+ *   component. Reported once per component and argument; the call then goes on to the DOM
+ *   source, whose select() still throws ("expects the argument to be a string").
+ *
+ * SYG125 (error): controls are elements, not components.
+ *   - a control given `.intent`, `.model` or `.initialState` (reported when it first renders,
+ *     the statics are set after controls() returns);
+ *   - a spec object whose `vnode()` returns anything but one element vnode (text, nothing, an
+ *     array, a component). With diagnostics on, the render then throws an Error with the
+ *     SYG125 text, so the component's error boundary names the control instead of failing on
+ *     the stamp.
+ *   Mechanism: controls() (src/extra/controls.ts) calls `__SYGNAL_DIAGNOSTICS__.control(control,
+ *   vnode)` on every render; installControlHooks() publishes it on the core bridge.
+ *
+ * The same hook remembers which control rendered each vnode (controlOfVnode), so inspect() can
+ * list a component's controls with their element or kind.
+ */
+import type {DiagnosticCheck} from '../index'
+import {bridge, devReport, once, onReset, nameOf, report} from './shared'
+import {DEV_CODE_SEVERITY} from '../codes'
+
+/** the key of a control, from its selector `[data-control="<Key>"]` */
+export const controlKey = (control: any): string => String(control).slice(15, -2)
+
+/** a control selector `[data-control="<Key>"]` as its key, else undefined */
+export const keyOfSelector = (selector: string): string | undefined => {
+  const m = /^\[data-control="([^"]+)"\]$/.exec(selector)
+  return m ? m[1] : undefined
+}
+
+const isControl = (x: any): boolean => typeof x == 'function' && !!x.__sygnalControl
+
+const componentName = (fn: any): string =>
+  fn.componentName || fn.label || fn.name || 'the component'
+
+let vnodeControls = new WeakMap<object, any>()
+let staticsSeen = new WeakSet<object>()
+onReset(() => {
+  vnodeControls = new WeakMap()
+  staticsSeen = new WeakSet()
+})
+
+/** the control that rendered a vnode (only while the dev entry is installed) */
+export const controlOfVnode = (vnode: any): any =>
+  vnode && typeof vnode == 'object' ? vnodeControls.get(vnode) : undefined
+
+const STATICS = ['intent', 'model', 'initialState']
+
+const describe = (v: any): string =>
+  v === undefined || v === null ? String(v)
+  : Array.isArray(v) ? `an array of ${v.length}`
+  : typeof v != 'object' ? `a ${typeof v} (${JSON.stringify(v)})`
+  : typeof v.sel != 'string' ? (v.text !== undefined ? 'a text vnode' : 'a fragment')
+  // the pragma's component placeholder (the component function in data.c)
+  : v.data && typeof v.data.c == 'function' ? `the component <${v.sel}>`
+  : 'an element vnode'
+
+function onControl(control: any, vnode: any): void {
+  const key = controlKey(control)
+  if (vnode && typeof vnode == 'object') vnodeControls.set(vnode, control)
+
+  if (!staticsSeen.has(control)) {
+    staticsSeen.add(control)
+    const given = STATICS.filter(s => control[s] != null)
+    if (given.length) {
+      devReport('SYG125', {
+        message: `The control ${key} has ${given.map(s => '.' + s).join(', ')}, but controls are elements, not components: ${given.length > 1 ? 'these statics are' : 'it is'} never used`,
+        fix: `Put the intent and model on the component that renders <${key}>, and listen to the control in its intent: DOM.click(${key}). For something with its own state and actions, write a component instead`,
+        data: {control: key, statics: given},
+      })
+    }
+  }
+
+  const what = describe(vnode)
+  if (what == 'an element vnode') return
+  const kind = control.kind
+  // report() (not devReport): in 'error' mode its DiagnosticError is thrown into the render
+  const d = report('SYG125', {
+    severity: DEV_CODE_SEVERITY.SYG125,
+    message: `The control ${key}'s spec${kind ? ` (kind '${kind}')` : ''} vnode() returned ${what}, but it must return one element vnode`,
+    fix: `Return a single element built with the h argument: vnode(props, children, h) { return h('div', props, ...children) }`,
+    data: {control: key, kind, returned: what},
+  })
+  if (d) throw new Error(d.text)
+}
+
+/** Publish the control hook on the core bridge. Returns an uninstall function. */
+export function installControlHooks(): () => void {
+  const core = bridge()
+  if (!core) return () => {}
+  core.control = onControl
+  return () => { if (core.control === onControl) core.control = undefined }
+}
+
+const wrapped = new WeakMap<object, any>()
+
+/** a DOM source whose select() and event shorthands report SYG124 for a component argument */
+function checkedDOM(component: any, dom: any): any {
+  if (!dom || typeof dom != 'object') return dom
+  let proxy = wrapped.get(dom)
+  if (proxy) return proxy
+  proxy = new Proxy(dom, {
+    get(t: any, k: any) {
+      const v = t[k]
+      if (typeof k != 'string' || typeof v != 'function' || (k != 'select' && k in t)) return v
+      return function (this: any, arg: any, ...rest: any[]) {
+        if (typeof arg == 'function' && !isControl(arg)) {
+          const name = nameOf(component), child = componentName(arg)
+          if (once(`SYG124:${name}:${child}:${k}`)) {
+            const call = k == 'select' ? `DOM.select(${child})` : `DOM.${k}(${child})`
+            devReport('SYG124', {
+              component,
+              message: `${name}.intent passes the component ${child} to ${call}, but a component is not an element: it has no element of its own to listen on, and its elements are isolated from ${name}`,
+              fix: `Handle the event in ${child} and send it up with PARENT, then read it here with CHILD.select(${child}); or render a control ${name} owns around it: const { ${child}Box } = controls({ ${child}Box: 'div' }), <${child}Box><${child} /></${child}Box>, DOM.click(${child}Box)`,
+              data: {component: child, method: k},
+            })
+          }
+        }
+        const out = v.call(t, arg, ...rest)
+        return k == 'select' ? checkedDOM(component, out) : out
+      }
+    },
+  })
+  wrapped.set(dom, proxy)
+  return proxy
+}
+
+export const controlsCheck: DiagnosticCheck = {
+  id: 'controls',
+
+  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/dataset.ts

@@ -0,0 +1,57 @@
+/**
+ * SYG421 — invalid `data` (dataset) key in a view (error, G-143).
+ *
+ * JSX `data={{ ... }}` becomes the vnode's `data.dataset` (a `data-x-y="..."` attribute is
+ * camelCased to 'xY' by the pragma, G-152), which the DOM driver writes with
+ * `element.dataset[key] = value`. The browser throws a SyntaxError DOMException for a key with
+ * a hyphen followed by a lower-case letter (`'task-id'`), and setAttribute() throws for a name
+ * with characters an attribute can't have (spaces, quotes, `=`, ...). The patch fails, so the
+ * app stops rendering, and the console shows only a bare "DOMException {}".
+ *
+ * Mechanism: onRender (before the DOM driver patches) walks the rendered vnode tree and checks
+ * every dataset key. Reported once per key; the mock DOM of renderComponent never throws, so
+ * this is also the only signal there.
+ */
+import type {DiagnosticCheck} from '../index'
+import {devReport, once, nameOf} from './shared'
+
+const camel = (key: string): string => key.replace(/-([a-z])/g, (_, c) => c.toUpperCase())
+const BAD_CHAR = /[\s"'<>\/=`]/
+
+function problem(key: string): string | undefined {
+  if (/-[a-z]/.test(key)) return `has a hyphen followed by a lower-case letter, which a dataset name can't have`
+  if (BAD_CHAR.test(key)) return `contains a character an HTML attribute name can't have`
+  return undefined
+}
+
+function walk(vnode: any, visit: (dataset: Record<string, any>, sel: string) => void, depth = 0): void {
+  if (!vnode || typeof vnode != 'object' || depth > 500) return
+  const ds = vnode.data && vnode.data.dataset
+  if (ds && typeof ds == 'object') visit(ds, vnode.sel)
+  const children = vnode.children
+  if (Array.isArray(children)) for (const c of children) walk(c, visit, depth + 1)
+}
+
+export const datasetCheck: DiagnosticCheck = {
+  id: 'dataset',
+
+  onRender(component, rootVnode) {
+    walk(rootVnode, (dataset, sel) => {
+      for (const key of Object.keys(dataset)) {
+        const why = problem(key)
+        if (!why || !once(`SYG421:${key}`)) continue
+        const good = camel(key).replace(new RegExp(BAD_CHAR.source, 'g'), '')
+        const attr = good.replace(/[A-Z]/g, c => '-' + c.toLowerCase())
+        const name = good || 'name'
+        devReport('SYG421', {
+          component,
+          message: `The view of ${nameOf(component)} renders the data key '${key}'${sel ? ` on <${String(sel).split(/[.#]/)[0]}>` : ''} ` +
+            `(from data={{ '${key}': … }}), but '${key}' ${why}. ` +
+            `Writing it throws a DOMException, which can stop rendering`,
+          fix: `Use a camelCase key in the data prop: data={{ ${name}: … }} renders the attribute data-${attr || 'name'}; read it with .data('${name}')`,
+          data: {key, suggested: good, attribute: `data-${attr}`},
+        })
+      }
+    })
+  },
+}

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

@@ -37,6 +37,7 @@ import type {DiagnosticCheck} from '../index'
 import {ScopeChecker} from '../../../cycle/dom/ScopeChecker'
 import type {Scope} from '../../../cycle/dom/isolate'
 import {reportSafely, once, onReset, timing, nameOf} from './shared'
+import {keyOfSelector} from './controls'
 
 interface Tracked {
   name: string
@@ -83,7 +84,9 @@ function viewSource(component: any): string {
 
 /** class / id / tag tokens of a selector: '.a .b-c > #d' -> ['a', 'b-c', 'd'] */
 const tokensOf = (selector: string): string[] =>
-  (selector.replace(/\[[^\]]*\]|:[\w-]+(\([^)]*\))?/g, ' ').match(/[A-Za-z_][\w-]*/g) || [])
+  (selector.replace(/\[[^\]]*\]|:[\w-]+(\([^)]*\))?/g, ' ').match(/[A-Za-z_][\w-]*/g) || [] as string[])
+    // CT-1: a control's key (`<Add>` / `h(Add)` in the view source)
+    .concat(Array.from(selector.matchAll(/\[data-control="([^"]+)"\]/g), m => m[1]))
 
 function appearsInView(component: any, selector: string): boolean {
   const src = viewSource(component)
@@ -93,12 +96,13 @@ function appearsInView(component: any, selector: string): boolean {
   return tokens.every(t => new RegExp(`(^|[^\\w-])${t.replace(/[-]/g, '\\-')}($|[^\\w-])`).test(src))
 }
 
-function rootElementOf(t: Tracked): Element | undefined {
+// G-144: a fragment-rooted component has several root elements
+function rootElementsOf(t: Tracked): Element[] {
   try {
     const im = t.source._isolateModule
-    return im && im.getElement(scopesOf(t.source.namespace))
+    return (im && im.getElements(scopesOf(t.source.namespace))) || []
   } catch (_) {
-    return undefined
+    return []
   }
 }
 
@@ -133,8 +137,8 @@ function report103(component: any, t: Tracked, selector: string, severity: 'info
 
 function sweep(component: any, t: Tracked, escalate: boolean): void {
   if (t.disposed) return
-  const root = rootElementOf(t)
-  if (!root || typeof root.querySelectorAll !== 'function') return
+  const roots = rootElementsOf(t).filter(r => typeof r.querySelectorAll === 'function')
+  if (!roots.length) return
   const im = t.source._isolateModule
   const checker = new ScopeChecker(t.source.namespace, im)
   let unmatched = false
@@ -144,8 +148,11 @@ function sweep(component: any, t: Tracked, escalate: boolean): void {
     if (matched.has(matchKey) || t.crossed.has(selector)) continue
     let all: Element[]
     try {
-      all = Array.prototype.slice.call(root.querySelectorAll(selector))
-      if (root.matches(selector)) all.push(root)
+      all = []
+      for (const root of roots) {
+        all.push(...Array.prototype.slice.call(root.querySelectorAll(selector)))
+        if (root.matches(selector)) all.push(root)
+      }
     } catch (_) {
       continue // invalid selector: the DOM driver reports that itself
     }
@@ -156,11 +163,13 @@ function sweep(component: any, t: Tracked, escalate: boolean): void {
       t.crossed.add(selector)
       if (!once(`SYG104:${t.name}:${selector}`)) continue
       const child = childNameFor(t, all) || 'a child component'
+      // CT-1: a control is named by its identifier
+      const control = keyOfSelector(selector)
       reportSafely('SYG104', {
         component,
-        message: `DOM.select('${selector}') in ${t.name} matches elements inside ${child} (isolated), so ${t.name} never receives their events`,
-        fix: `Handle the event in ${child} and send it up with PARENT (read it here with CHILD.select(${child})), or use EVENTS`,
-        data: {selector, child},
+        message: `${control ? `The control ${control}` : `DOM.select('${selector}')`} in ${t.name} matches elements inside ${child} (isolated), so ${t.name} never receives their events`,
+        fix: `Handle the event in ${child}${control ? ` (DOM.<event>(${control}) in its intent)` : ''} and send it up with PARENT (read it here with CHILD.select(${child})), or use EVENTS`,
+        data: control ? {selector, child, control} : {selector, child},
       })
       continue
     }

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

@@ -1,6 +1,8 @@
 /**
  * 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.
@@ -12,7 +14,7 @@
  * EVENTS.select() with no type (all events) counts as selecting everything.
  */
 import type {DiagnosticCheck} from '../index'
-import {report, once, onReset, didYouMean} from './shared'
+import {report, devReport, once, onReset, didYouMean} from './shared'
 
 let selected = new Set<string>()
 let emitted = new Set<string>()
@@ -29,7 +31,20 @@ export const eventsCheck: DiagnosticCheck = {
   },
 
   onBusEmit(type, emitterName) {
-    if (typeof type !== 'string') return
+    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', {