sygnal 5.3.7 → 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

@@ -0,0 +1,67 @@
+/**
+ * SYG401 — <Collection> has no `from` and the whole state is not an array (warn).
+ * A defined `from` is checked by the core (D22).
+ *
+ * Reported through diagnostics in addition to the existing console output.
+ *
+ * Mechanism: the core has no hook at Collection instantiation, and the
+ * Collection marker vnode is gone by the time onRender sees the tree. So, at
+ * onModel (construction time, before the first render), this check wraps the
+ * component INSTANCE's instantiateCollection method (an own property that
+ * shadows the prototype method; Component calls `this.instantiateCollection`
+ * for every new Collection). The wrapper inspects the marker's props and the
+ * component's current state, then always calls the original. This only
+ * happens when the dev-only 'sygnal/diagnostics' entry is loaded and
+ * diagnostics are on. Reported once per component name and `from` value.
+ */
+import type {DiagnosticCheck} from '../index'
+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}`
+
+export function checkCollection(component: any, el: any): void {
+  const props = (el && el.data && el.data.props) || {}
+  const from = props.from
+  const of = props.of
+  const ofName = typeof of === 'function' ? (of.componentName || of.label || of.name || 'component') : String(of)
+  const name = nameOf(component)
+
+  let state = component.currentState
+  try { if (typeof component.addCalculated === 'function') state = component.addCalculated(state) } catch (_) {}
+
+  let problem: string | undefined
+  let fix = `Pass the name of an array field in ${name}'s state, e.g. <Collection of={${ofName}} from="items" />, and initialize that field to [] in initialState`
+  // Every defined `from` (string field, lens object, or an invalid value) is reported by
+  // the core itself (SYG401/SYG412, retrofitted in 1E) in every diagnostics mode (D22), so
+  // this check only covers a missing `from`.
+  if (from !== undefined) return
+  if (!Array.isArray(state) && !(state && Array.isArray(state.value))) {
+    problem = `has no 'from' prop, so it uses ${name}'s whole state, which is ${describe(state)}, not an array`
+  }
+
+  if (!problem || !once(`SYG401:${name}:undefined`)) return
+  reportSafely('SYG401', {
+    component,
+    message: `<Collection of={${ofName}}> ${problem}, so it renders no items`,
+    fix,
+    data: {from: 'undefined', of: ofName},
+  })
+}
+
+const WRAPPED = '__sygnalDiagWrapped'
+
+export const collectionsCheck: DiagnosticCheck = {
+  id: 'collections',
+
+  onModel(component) {
+    const original = component && component.instantiateCollection
+    if (typeof original !== 'function' || original[WRAPPED]) return
+    const wrapped = function (this: any, el: any, ...rest: any[]) {
+      try { checkCollection(this, el) } catch (_) {}
+      return original.call(this, el, ...rest)
+    }
+    ;(wrapped as any)[WRAPPED] = true
+    component.instantiateCollection = wrapped
+  },
+}

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

@@ -0,0 +1,250 @@
+/**
+ * SYG104 — isolation boundary: an intent selector matches nothing in the
+ *          component's own scope, but matches elements inside a child
+ *          component / Collection item (warn).
+ * SYG103 — an intent selector has never matched a rendered element (info,
+ *          escalated to warn after >= 3 renders AND 2 s of render-idle time
+ *          without a match).
+ *
+ * Mechanism:
+ *   1. MainDOMSource.select() calls the onSelector hook with the source it was
+ *      called on. Its namespace = the component's isolation scopes + any
+ *      earlier select() selectors. Selectors are queued as "pending".
+ *   2. onIntent (right after the intent function ran, still inside the
+ *      component's constructor) claims the pending selectors whose isolation
+ *      scopes equal the component's DOM source scopes, and records
+ *      scopes -> component name (used to name the child for SYG104).
+ *   3. onRender schedules a sweep after `settleMs` (onRender sees the vnode
+ *      before the DOM patch; nested components patch a few ms later). The
+ *      sweep finds the component's root element through the DOM driver's
+ *      IsolateModule and runs each selector with querySelectorAll, splitting
+ *      the matches with the DOM driver's own ScopeChecker (the same test the
+ *      EventDelegator uses to deliver events) into "in scope" and "inside a
+ *      total-isolation boundary" (child component).
+ *   4. "Ever matched" is tracked per component NAME + selector, so a selector
+ *      that matches in one Collection item is fine for all of them.
+ *
+ * SYG103 noise control (conditional rendering is normal): a selector whose
+ * class/id/tag tokens all appear in the component's view source is assumed
+ * to be conditionally rendered and is not reported. A selector that does not
+ * appear in the view (typo, or an element rendered elsewhere) is reported as
+ * info on the first sweep, and escalated per the rule above.
+ *
+ * Only real DOM sources (with an IsolateModule) are checked; renderComponent's
+ * mock DOM never calls onSelector.
+ */
+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
+  source: any
+  selectors: string[]
+  renders: number
+  settleTimer?: any
+  idleTimer?: any
+  /** selectors already explained by SYG104 */
+  crossed: Set<string>
+  disposed?: boolean
+}
+
+const scopesOf = (ns: Scope[]): Scope[] => ns.filter(s => s.type !== 'selector')
+const keyOf = (scopes: Scope[]): string => scopes.map(s => `${s.type[0]}:${s.scope}`).join('/')
+
+let pending: Array<{key: string; selector: string}> = []
+let tracked = new WeakMap<object, Tracked>()
+/** isolation-scope key -> the component instance that owns it (latest wins) */
+let owners = new Map<string, any>()
+const ownerKeys = new WeakMap<object, string>()
+let matched = new Set<string>()
+let viewTokens = new WeakMap<object, string>()
+
+onReset(() => {
+  pending = []
+  tracked = new WeakMap()
+  owners = new Map()
+  matched = new Set()
+})
+
+const unref = (t: any) => { if (t && typeof t.unref === 'function') t.unref(); return t }
+
+function viewSource(component: any): string {
+  const view = component && component.view
+  if (typeof view !== 'function') return ''
+  let src = viewTokens.get(view)
+  if (src === undefined) {
+    try { src = Function.prototype.toString.call(view) } catch (_) { src = '' }
+    viewTokens.set(view, src as string)
+  }
+  return src as 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) || [] 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)
+  if (!src) return false
+  const tokens = tokensOf(selector)
+  if (!tokens.length) return false
+  return tokens.every(t => new RegExp(`(^|[^\\w-])${t.replace(/[-]/g, '\\-')}($|[^\\w-])`).test(src))
+}
+
+// G-144: a fragment-rooted component has several root elements
+function rootElementsOf(t: Tracked): Element[] {
+  try {
+    const im = t.source._isolateModule
+    return (im && im.getElements(scopesOf(t.source.namespace))) || []
+  } catch (_) {
+    return []
+  }
+}
+
+function childNameFor(t: Tracked, elements: Element[]): string | undefined {
+  const im = t.source._isolateModule
+  const depth = scopesOf(t.source.namespace).length
+  for (const el of elements) {
+    let ns: Scope[] | undefined
+    try { ns = im.getNamespace(el) } catch (_) { ns = undefined }
+    if (!ns) continue
+    for (let i = depth; i < ns.length; i++) {
+      if (ns[i].type !== 'total') continue
+      const owner = owners.get(keyOf(ns.slice(0, i + 1)))
+      if (owner) return nameOf(owner)
+      break
+    }
+  }
+  return undefined
+}
+
+function report103(component: any, t: Tracked, selector: string, severity: 'info' | 'warn'): void {
+  if (!once(`SYG103:${severity}:${t.name}:${selector}`)) return
+  reportSafely('SYG103', {
+    component,
+    severity,
+    message: `DOM.select('${selector}') in ${t.name} has not matched any element ${t.name} rendered` +
+      (severity === 'warn' ? ` (after ${t.renders} renders)` : ''),
+    fix: `Check the selector against the view's className/id. If the element is rendered by a child component, handle the event inside that child`,
+    data: {selector, renders: t.renders},
+  })
+}
+
+function sweep(component: any, t: Tracked, escalate: boolean): void {
+  if (t.disposed) 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
+
+  for (const selector of t.selectors) {
+    const matchKey = `${t.name}\u0000${selector}`
+    if (matched.has(matchKey) || t.crossed.has(selector)) continue
+    let all: Element[]
+    try {
+      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
+    }
+    const own = all.filter(el => { try { return checker.isDirectlyInScope(el) } catch (_) { return false } })
+    if (own.length) { matched.add(matchKey); continue }
+
+    if (all.length) {
+      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: `${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
+    }
+
+    if (appearsInView(component, selector)) continue
+    unmatched = true
+    if (escalate && t.renders >= timing.minRenders) report103(component, t, selector, 'warn')
+    else report103(component, t, selector, 'info')
+  }
+
+  if (unmatched && !escalate) {
+    clearTimeout(t.idleTimer)
+    t.idleTimer = unref(setTimeout(() => { t.idleTimer = undefined; sweep(component, t, true) }, timing.idleMs))
+  }
+}
+
+/**
+ * inspect (2B, read-only): a component's intent selectors on a real DOM source
+ * and whether a sweep has seen them match (true), only match inside a child
+ * (crossed), or neither yet. undefined when the component isn't tracked.
+ */
+export function selectorStatus(component: any): Array<{selector: string; matched: boolean | null; crossed: boolean}> | undefined {
+  const t = tracked.get(component)
+  return t && t.selectors.map(selector => ({
+    selector,
+    matched: matched.has(`${t.name}\u0000${selector}`) ? true : t.crossed.has(selector) ? false : null,
+    crossed: t.crossed.has(selector),
+  }))
+}
+
+export const domCheck: DiagnosticCheck = {
+  id: 'dom',
+
+  onSelector(source, selector) {
+    const ns: Scope[] | undefined = source && source.namespace
+    if (!Array.isArray(ns) || typeof selector !== 'string' || !selector) return
+    const prefix = ns.filter(s => s.type === 'selector').map(s => s.scope).join(' ')
+    pending.push({key: keyOf(scopesOf(ns)), selector: prefix ? `${prefix} ${selector}` : selector})
+    if (pending.length > 1000) pending.shift()
+  },
+
+  onIntent(component) {
+    const claimed = pending
+    pending = []
+    const source = component && component.sources && component.sources[component.DOMSourceName || 'DOM']
+    if (!source || !source._isolateModule || !Array.isArray(source.namespace)) return
+    const key = keyOf(scopesOf(source.namespace))
+    const name = nameOf(component)
+    owners.set(key, component)
+    ownerKeys.set(component, key)
+    const selectors = [...new Set(claimed.filter(p => p.key === key).map(p => p.selector))]
+    if (selectors.length) tracked.set(component, {name, source, selectors, renders: 0, crossed: new Set()})
+  },
+
+  onRender(component) {
+    const t = tracked.get(component)
+    if (!t || t.disposed) return
+    t.renders++
+    clearTimeout(t.idleTimer)
+    t.idleTimer = undefined
+    if (t.settleTimer) return
+    t.settleTimer = unref(setTimeout(() => {
+      t.settleTimer = undefined
+      sweep(component, t, false)
+    }, timing.settleMs))
+  },
+
+  onDispose(component) {
+    const key = ownerKeys.get(component)
+    if (key !== undefined && owners.get(key) === component) owners.delete(key)
+    const t = tracked.get(component)
+    if (!t) return
+    t.disposed = true
+    clearTimeout(t.settleTimer)
+    clearTimeout(t.idleTimer)
+    tracked.delete(component)
+  },
+}