sygnal 5.4.0 → 6.0.0

package/src/extra/diagnostics/checks/public.d.ts

@@ -34,9 +34,8 @@ export interface DiagnosticCheck {
  * Strict mode (canonical forms, SYG5xx): turn the runtime strict checks on
  * (true), off (false), or back to the default (undefined → on only when
  * globalThis.__SYGNAL_STRICT__ === true). Off by default. Diagnostics must
- * also be on. Runtime rules: SYG501 (positional view args), SYG502 (reducer
- * returned the unchanged state instead of ABORT), SYG504 ('ACTION | SINK'
- * keys); `sygnal-check --strict` checks all of SYG501-507 statically.
+ * also be on. Runtime rules: SYG501 (positional view args), SYG504 ('ACTION | SINK'
+ * keys); `sygnal-check --strict` checks SYG501-508 statically (SYG502 is retired in 6.0).
  * In tests: renderComponent(C, { strict: true }).
  */
 export function configureStrict(on?: boolean): void
@@ -96,15 +95,18 @@ export function getCodeInfo(code: string): DiagnosticCodeInfo | undefined
 // ---------------------------------------------------------------------------
 
 /** How an action is dispatched. */
-export type InspectActionTrigger = 'intent' | 'next' | 'builtin' | 'unknown'
+export type InspectActionTrigger = 'intent' | 'next' | 'reply' | 'builtin' | 'unknown'
 
 export interface InspectAction {
   name: string
   /**
    * 'intent': returned by the component's intent. 'builtin': BOOTSTRAP,
-   * INITIALIZE, HYDRATE, DISPOSE or READY. 'next': dispatched with next()
-   * (statically: a next('NAME') literal; at runtime: a model-only action whose
-   * STATE reducer was seen running). 'unknown': none of these is known.
+   * INITIALIZE, DISPOSE or READY. 'reply': named as a reply action by a request
+   * (`ok: 'NAME'` / `error: 'NAME'`) or a `connections` entry (statically: a
+   * string literal; at runtime: a request the instance was seen sending).
+   * 'next': dispatched with next() (statically: a next('NAME') literal; at
+   * runtime: a model-only action whose STATE reducer was seen running).
+   * 'unknown': none of these is known.
    */
   trigger: InspectActionTrigger
   /** sinks of the model entry (STATE, EVENTS, EFFECT, PARENT, custom drivers); [] without a model entry */
@@ -134,6 +136,20 @@ export interface InspectSelector {
   matched: boolean | null
   /** the child component whose (isolated) elements it matches instead, if any */
   isolationHit: string | null
+  /** PLAN-4 CT-1: the control this selector is (its key), when it is `[data-control="<Key>"]` */
+  control?: string
+}
+
+/** PLAN-4 CT-1: a control (controls()) a component renders */
+export interface InspectControl {
+  /** the control's key (rendered as data-control="<name>") */
+  name: string
+  /** the intrinsic tag of a tag spec; null for a spec object */
+  element: string | null
+  /** a spec object's kind (e.g. 'widget') */
+  kind?: string
+  /** whether the component's intent listens to it; null when unknown */
+  listened: boolean | null
 }
 
 export interface InspectDiagnostic {
@@ -178,7 +194,60 @@ export interface InspectComponent {
   eventsSelected: string[]
   children: InspectChild[]
   selectors: InspectSelector[]
+  /** PLAN-4 CT-1: the controls it renders (runtime: seen in its renders); omitted when none */
+  controls?: InspectControl[]
+  /** static only, PLAN-4 GS-2 (G-224): the element commands (ELEMENT sink) its model sends; omitted when none */
+  commands?: InspectCommand[]
+  /** static only, PLAN-4 GS-7 (G-224): the literal timer specs of its `timers` static; omitted when none */
+  timers?: InspectTimer[]
   diagnostics: InspectDiagnostic[]
+  /** runtime, PLAN-3 5-3: the instance's `resources` and their state */
+  resources?: InspectResource[]
+}
+
+/** PLAN-4 GS-2: an element command a model entry sends (static inspect, sygnal-check --graph) */
+export interface InspectCommand {
+  /** the model entry that sends it */
+  action: string
+  /** the command's method (its first key) */
+  method: string
+  /** the control's key or the selector; null when not static */
+  target: string | null
+  /** the control it targets (its key) */
+  control?: string
+  /** intent actions listening on the target for a native event the command causes (close, toggle...) */
+  triggers?: string[]
+}
+
+/** PLAN-4 GS-7: a literal timer spec of a `timers` static (static inspect, sygnal-check --graph) */
+export interface InspectTimer {
+  name: string
+  every?: number | null
+  after?: number | null
+  /** the action a frame timer dispatches */
+  frame?: string | null
+  action?: string | null
+  background?: true
+}
+
+/** PLAN-3 5-3: a resource of a component instance (runtime inspect()) */
+export interface InspectResource {
+  name: string
+  status: 'idle' | 'loading' | 'success' | 'error'
+  refreshing: boolean
+  /** `data` is set (a success, or kept through a refetch) */
+  hasData: boolean
+  /** the error message while 'error' */
+  error?: string
+}
+
+/** PLAN-3 5-3: a makeFetchDriver cache entry (runtime inspect(), t.cache) */
+export interface InspectCacheEntry {
+  key: string
+  age?: number
+  stale: boolean
+  subscribers: number
+  data: any
 }
 
 export interface InspectGraph {
@@ -190,6 +259,26 @@ export interface InspectGraph {
   events: Record<string, { emitters: string[]; selectors: string[] }>
   /** diagnostics not tied to a listed component */
   diagnostics: InspectDiagnostic[]
+  /** runtime, PLAN-3 5-3: makeFetchDriver cache entries, by sink name (empty when no cache) */
+  cache?: Record<string, InspectCacheEntry[]>
+  /** runtime, PLAN-4 2-C (GS-10): with `inspect({ actions })`, the most recent actions, oldest first */
+  recentActions?: InspectRecentAction[]
+}
+
+/** PLAN-4 2-C (GS-10): one recent action (inspect({ actions })) */
+export interface InspectRecentAction {
+  type: string
+  /** the action's data, when it is JSON-safe and small (a DOM event is left out) */
+  data?: any
+  /** the component's name */
+  component: string
+  /** the instance's id (InspectComponent.id) */
+  instance: string
+  /** the sinks that produced a value for it (not ABORT) */
+  sinks: string[]
+  cause: 'intent' | 'next' | 'reply' | 'built-in' | 'simulateAction' | 'behavior'
+  /** ms since the dev entry started recording (or the last resetChecks()) */
+  at: number
 }
 
 export interface InspectOptions {
@@ -199,6 +288,8 @@ export interface InspectOptions {
   selectors?: Record<string, InspectSelector[]>
   /** diagnostics to attach (default: the devtools' collected diagnostics, when available) */
   diagnostics?: Array<{ code: string; severity: DiagnosticSeverity; component?: string; message: string; [key: string]: any }>
+  /** PLAN-4 2-C: add `recentActions`: true for every kept one (the last 200), a number for the last n */
+  actions?: boolean | number
 }
 
 /**

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

@@ -0,0 +1,128 @@
+/**
+ * Reply actions (PLAN-3 §1.1, workstream 1-D).
+ *
+ * SYG112 — a request names a reply action the sending component has no
+ *          model entry for (error: the reply is dropped). Dev-entry code
+ *          (DEV_CODE_SEVERITY).
+ * SYG508 — strict: the component reads the replies to its own request with
+ *          X.select('cat') / X.errors('cat') where reply actions would do.
+ *
+ * Mechanism:
+ *   onSink   (checks/next.ts: checkRequest) every value an instance sends to a
+ *            reply-capable sink (`__sygnalReplies === true`: makeFetchDriver,
+ *            driverFromAsync, the socket driver) is checked as it is sent.
+ *            The names it sees feed inspect()'s 'reply' trigger.
+ *   sources  (strict only) wraps those sources for the intent, recording the
+ *            select()/errors() categories the instance reads.
+ * A request's `category` is compared for SYG508 (driverFromAsync's custom
+ * `selector` property is not known at run time; sygnal-check covers it).
+ * Reported once per component name and action / category.
+ *
+ * `{ connections }` values (the `connections` static, which the core sends to
+ * the same sink, or one a model entry sends) are checked the same way:
+ * each connection's message / open / close / error and its SSE `events` names.
+ */
+import type {DiagnosticCheck} from '../index'
+import {STRICT_CODE_SEVERITY} from '../codes'
+import {devReport, reportSafely, once, nameOf, suggest, replySeen} from './shared'
+import {isStrictEnabled} from './strict'
+
+const REPLY_KEYS = ['ok', 'error']
+// PLAN-3 5-4b: on the router's sink, `{ route }` (the route static) and `{ block }` name reply actions
+const ROUTER_KEYS = ['route', 'block']
+const CONNECTION_KEYS = ['message', 'open', 'close', 'error']
+
+/** [action, key, connection name?] for every reply action name a sink value names */
+function replyNames(req: any, router?: boolean): Array<[string, string, string?]> {
+  const out: Array<[string, string, string?]> = []
+  for (const key of router ? REPLY_KEYS.concat(ROUTER_KEYS) : REPLY_KEYS) if (typeof req[key] === 'string') out.push([req[key], key])
+  const conns = req.connections
+  if (conns && typeof conns === 'object') {
+    for (const name of Object.keys(conns)) {
+      const spec = conns[name]
+      if (!spec || typeof spec !== 'object') continue
+      for (const key of CONNECTION_KEYS) if (typeof spec[key] === 'string') out.push([spec[key], key, name])
+      const events = spec.events
+      if (events && typeof events === 'object') {
+        for (const ev of Object.keys(events)) if (typeof events[ev] === 'string') out.push([events[ev], `events.${ev}`, name])
+      }
+    }
+  }
+  return out
+}
+
+/** instance → 'SINK\0category' → the select/errors call that read it */
+const selected = new WeakMap<object, Map<string, string>>()
+
+
+function readingSource(component: any, sink: string, source: any) {
+  const wrapped = Object.create(source)
+  for (const method of ['select', 'errors']) {
+    if (typeof source[method] !== 'function') continue
+    wrapped[method] = (category?: any, ...rest: any[]) => {
+      if (typeof category === 'string') {
+        let reads = selected.get(component)
+        if (!reads) selected.set(component, reads = new Map())
+        reads.set(`${sink}\0${category}`, `${sink}.${method}('${category}')`)
+      }
+      return source[method](category, ...rest)
+    }
+  }
+  return wrapped
+}
+
+export function checkRequest(component: any, sink: string, req: any, modelActions: string[]) {
+  if (!req || typeof req !== 'object') return
+  const name = nameOf(component)
+  let replies = false
+  for (const [action, key, connection] of replyNames(req, !!component?.sources?.[sink]?.__sygnalRouter)) {
+    replies = true
+    let seen = replySeen.get(component)
+    if (!seen) replySeen.set(component, seen = new Set())
+    seen.add(action)
+    if (modelActions.includes(action) || !once(`SYG112:${name}:${action}`)) continue
+    const near = suggest(action, modelActions.filter(a => !a.startsWith('__')))
+    devReport('SYG112', {
+      component,
+      message: (connection
+        ? `${sink} connection '${connection}' names '${action}' as its ${key} reply action, but ${name} has no model entry '${action}', so those events are dropped`
+        : `A ${sink} request names '${action}' as its ${key} reply action, but ${name} has no model entry '${action}', so the reply is dropped`) +
+        (near ? ` (did you mean '${near}'?)` : ''),
+      fix: near
+        ? `Use the existing entry: ${key.startsWith('events.') ? `events: { '${key.slice(7)}': '${near}' }` : `${key}: '${near}'`}`
+        : `Add '${action}' to ${name}.model, e.g. ${action}: (state, data) => ({ ...state, ... }), or fix the name`,
+      data: {action, key, sink, ...(connection ? {connection} : {}), ...(near ? {suggestion: near} : {}), modelActions},
+    })
+  }
+
+  // SYG508 (strict): a request without reply actions whose replies this instance reads back with select()/errors()
+  if (replies || 'abort' in req || typeof req.category !== 'string' || !isStrictEnabled()) return
+  const read = selected.get(component)?.get(`${sink}\0${req.category}`)
+  if (!read || !once(`SYG508:${name}:${sink}:${req.category}`)) return
+  // (inside a sink stream: reportSafely, so 'error' mode can't break the stream)
+  reportSafely('SYG508', {
+    severity: STRICT_CODE_SEVERITY.SYG508,
+    component,
+    message: `${name} sends a ${sink} request with category: '${req.category}' and reads the reply back with ${read}`,
+    fix: `Use reply actions instead: name them in the request, ${sink}: (state) => ({ url, ok: 'LOADED', error: 'FAILED' }), ` +
+      `handle LOADED (the parsed body) and FAILED ({ error, status, body, request }) in the model, and remove ${read} from the intent`,
+    data: {sink, category: req.category, read},
+  })
+}
+
+export const repliesCheck: DiagnosticCheck = {
+  id: 'replies',
+
+  sources(component, sources) {
+    if (!isStrictEnabled() || typeof Proxy != 'function') return
+    const cache = new Map<string, any>()
+    return new Proxy(sources, {
+      get(t: any, k: any) {
+        const v = t[k]
+        if (typeof k != 'string' || !v || v.__sygnalReplies !== true) return v
+        if (!cache.has(k)) cache.set(k, readingSource(component, k, v))
+        return cache.get(k)
+      },
+    })
+  },
+}

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

@@ -0,0 +1,100 @@
+/**
+ * Router and declaration statics (PLAN-3 5-4b). Dev-entry-only codes (DEV_CODE_SEVERITY):
+ *
+ * SYG130 — href() names no route, or leaves out a param its pattern needs (the link is broken).
+ *          (A `{ to }` command with the same problem is SYG620, reported by the router itself
+ *          in production too, and not navigated.)
+ * SYG131 — href() or a `{ to, params }` command passes params the route's pattern doesn't use.
+ * SYG132 — G-167: a component declares a static the core sends to a driver (`route`,
+ *          `resources`, `connections`, `head`) but never sends it: it has no model (the core
+ *          wires statics in its model setup), or it is a root without initialState (a static is
+ *          computed from the state stream, which a root without state never emits).
+ * SYG133 — the SPA router (makeRouter().driver without `navigate`) runs inside a Vike app,
+ *          where Vike owns links and history.
+ *
+ * Mechanism: the router's href() calls `__SYGNAL_DIAGNOSTICS__.routerHref(routes, name, params)`
+ * when it exists (installRouterHooks() sets it); onModel looks at the component's sources for
+ * `__sygnalStatic` / `__sygnalRouter` markers.
+ */
+import type {DiagnosticCheck} from '../index'
+import {bridge, devReport, once, nameOf, suggest} from './shared'
+
+const PARAM = /:(\w+)/g
+const paramsOf = (pat: string) => (pat.match(PARAM) || []).map(p => p.slice(1))
+
+function checkHref(routes: Record<string, string>, name: string, params: any) {
+  const names = Object.keys(routes).filter(k => routes[k] != '*')
+  const pat = routes[name]
+  if (pat == null || pat == '*') {
+    if (!once(`SYG130:${name}`)) return
+    const near = suggest(String(name), names)
+    devReport('SYG130', {
+      message: `href('${name}') names no route, so the link points to '/'` + (near ? ` (did you mean '${near}'?)` : ''),
+      fix: `Use one of the route names: ${names.join(', ')}`,
+      data: {name, routes: names, ...(near ? {suggestion: near} : {})},
+    })
+    return
+  }
+  const wanted = paramsOf(pat)
+  const given = params && typeof params == 'object' ? params : {}
+  const missing = wanted.filter(k => given[k] == null)
+  const extra = Object.keys(given).filter(k => !wanted.includes(k))
+  if (missing.length && once(`SYG130:${name}:${missing}`)) {
+    devReport('SYG130', {
+      message: `href('${name}') leaves out ${missing.map(k => `'${k}'`).join(', ')} (${pat}), so that segment is empty`,
+      fix: `href('${name}', { ${wanted.join(', ')} })`,
+      data: {name, pattern: pat, missing},
+    })
+  }
+  if (extra.length && once(`SYG131:${name}:${extra}`)) {
+    devReport('SYG131', {
+      message: `Route '${name}' (${pat}) has no param ${extra.map(k => `'${k}'`).join(', ')}; it is ignored`,
+      fix: wanted.length ? `Pass only ${wanted.join(', ')}; put other values in the query: href('${name}', params, { ${extra[0]} })` : `Put it in the query: href('${name}', {}, { ${extra[0]} })`,
+      data: {name, pattern: pat, extra},
+    })
+  }
+}
+
+/** install the hook the router's href() calls (removed by the returned function) */
+export function installRouterHooks(): () => void {
+  const core = bridge()
+  if (!core) return () => {}
+  core.routerHref = checkHref
+  return () => { if (core.routerHref === checkHref) core.routerHref = undefined }
+}
+
+export const routerCheck: DiagnosticCheck = {
+  id: 'router',
+
+  onModel(component) {
+    const sources = component?.sources
+    if (!sources || typeof sources != 'object') return
+    const name = nameOf(component)
+    for (const n of component.sourceNames || Object.keys(sources)) {
+      const src = sources[n]
+      const k = src?.__sygnalStatic
+      if (typeof k == 'string' && component.view?.[k] != null) {
+        // statics are computed from state (G-167: with or without a model): a root whose state
+        // never emits (a model but no initialState) never sends one
+        if (!component.isSubComponent && component.initialState === undefined && once(`SYG132:${name}:${k}`)) {
+          devReport('SYG132', {
+            component,
+            message: `${name} declares ${name}.${k}, but a root without initialState has no state, so ${k} is never sent to ${n}`,
+            fix: `Add ${name}.initialState (e.g. { }${k == 'route' ? ', or { route: router.current() }' : ''})`,
+            data: {static: k, source: n, reason: 'state'},
+          })
+        }
+      }
+      const opts = src?.__sygnalRouter
+      const g: any = globalThis
+      if (opts && typeof opts == 'object' && !opts.navigate && g.document?.getElementById?.('vike_pageContext') && once('SYG133')) {
+        devReport('SYG133', {
+          component,
+          message: `The SPA router (${n}) runs inside a Vike app: Vike owns links and history, so both would handle a click`,
+          fix: "Pass Vike's navigate: makeRouter({ routes, navigate }) with import { navigate } from 'vike/client/router', or use Vike's routing",
+          data: {source: n},
+        })
+      }
+    }
+  },
+}

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

@@ -9,7 +9,7 @@
  * xstream equivalent and the SYG301 docs link. The error is also reported
  * (collected / printed per the diagnostics mode; in 'error' mode report()
  * throws the DiagnosticError itself). It works anywhere a stream is used
- * (intent, peers, drivers), with no hook in component.ts.
+ * (intent, peers, drivers), with no hook in the core.
  *
  * Caveat: `typeof stream.pipe === 'function'` is true while this entry is
  * loaded (dev only).

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

@@ -11,6 +11,8 @@
  */
 import '../index'
 import type {DiagnosticCheck, DiagnosticDetails, Diagnostic} from '../index'
+import {CODE_TITLES, DEV_CODE_SEVERITY, registerCodes} from '../codes'
+import type {DiagnosticSeverity} from '../codes'
 
 interface CoreBridge {
   registerCheck(check: DiagnosticCheck): () => void
@@ -38,6 +40,16 @@ export const reportSafely = (code: string, details: DiagnosticDetails): Diagnost
   }
 }
 
+registerCodes(Object.keys(DEV_CODE_SEVERITY).map(code =>
+  [code, DEV_CODE_SEVERITY[code], CODE_TITLES[code]] as [string, DiagnosticSeverity, string]))
+
+/**
+ * reportSafely() for the dev-entry-only codes (DEV_CODE_SEVERITY, G-143): the main bundle's
+ * core doesn't know their severity, so it is passed explicitly.
+ */
+export const devReport = (code: string, details: DiagnosticDetails): Diagnostic | undefined =>
+  reportSafely(code, {severity: DEV_CODE_SEVERITY[code], ...details})
+
 /** Tunables (test seam: configureChecks()). */
 export const timing = {
   /** delay after a render before DOM checks run (lets nested renders patch) */
@@ -48,8 +60,76 @@ export const timing = {
   minRenders: 3,
 }
 
-/** Built-in actions Sygnal dispatches itself; never "missing" or "unreachable". */
-export const BUILTIN_ACTIONS = new Set(['BOOTSTRAP', 'INITIALIZE', 'HYDRATE', 'DISPOSE', 'READY'])
+/**
+ * Built-in actions Sygnal dispatches itself; never "missing" or "unreachable".
+ * (HYDRATE is not one since 6.0, D66: nothing dispatches it, so it is an ordinary action.)
+ */
+export const BUILTIN_ACTIONS = new Set(['BOOTSTRAP', 'INITIALIZE', 'DISPOSE', 'READY', 'RESOURCE'])
+
+/** Sinks the core handles itself: their values never go to a reply-action driver. */
+// (PLAN-4 GS-2: ELEMENT too; `{ scrollIntoView: Row, block: 'center' }` names no action)
+const NON_REPLY_SINK = /^(STATE|EFFECT|EVENTS|PARENT|READY|DOM|CHILD|ELEMENT|PERSIST)$/
+
+// `ok: 'X'` / `"error": "X"` in function source (minified code keeps string literals and keys)
+const keyedNames = (keys: string) => new RegExp(`(?:^|[{,\\s])["']?(?:${keys})["']?\\s*:\\s*(["'\`])([\\w$.:/-]+)\\1`, 'g')
+// (PLAN-3 5-4b: and a router `{ block: 'ACTION' }`)
+const REPLY_IN_SOURCE = keyedNames('ok|error|block')
+const CONNECTION_IN_SOURCE = keyedNames('message|open|close|error')
+// G-224: a `timers` static's `action: 'TICK'` / `frame: 'FRAME'`
+const TIMER_IN_SOURCE = keyedNames('action|frame')
+// PLAN-5 B-3: a `browser` static's `action: 'SEEN'` / `error: 'GEO_FAILED'`
+const BROWSER_IN_SOURCE = keyedNames('action|error')
+
+const namesIn = (fn: any, re: RegExp, out: Set<string>) => {
+  if (typeof fn !== 'function') return
+  let src = ''
+  try { src = Function.prototype.toString.call(fn) } catch (_) { return }
+  re.lastIndex = 0
+  for (let m = re.exec(src); m; m = re.exec(src)) out.add(m[2])
+}
+
+/**
+ * Reply actions a component's requests and `connections` static can name, read from the
+ * source of its non-STATE sink functions (`HTTP: (s) => ({ url, ok: 'LOADED', error: 'FAILED' })`)
+ * and of `connections` (message/open/close/error). A heuristic for SYG102 (PLAN-3): a name
+ * built at run time is missed (SYG102 stays info, so that only costs a false hint).
+ */
+export function replyNamesOf(component: any): Set<string> {
+  const out = new Set<string>()
+  const model = component && component.model
+  if (model && typeof model === 'object') {
+    for (const key of Object.keys(model)) {
+      const value = model[key]
+      const bar = key.indexOf('|')
+      if (bar >= 0) {
+        if (!NON_REPLY_SINK.test(key.slice(bar + 1).trim())) namesIn(value, REPLY_IN_SOURCE, out)
+      } else if (value && typeof value === 'object') {
+        for (const sink of Object.keys(value)) {
+          if (!NON_REPLY_SINK.test(sink)) namesIn(value[sink], REPLY_IN_SOURCE, out)
+        }
+      }
+    }
+  }
+  namesIn(component?.view?.connections, CONNECTION_IN_SOURCE, out)
+  // G-224: makeTimerDriver() replies the actions the `timers` static names (a function of the
+  // state, or an object of them)
+  const timers = component?.view?.timers
+  if (timers && typeof timers === 'object') for (const k in timers) namesIn(timers[k], TIMER_IN_SOURCE, out)
+  else namesIn(timers, TIMER_IN_SOURCE, out)
+  // PLAN-5 B-3: the browser driver replies the actions the `browser` static names
+  const browser = component?.view?.browser
+  if (browser && typeof browser === 'object') for (const k in browser) namesIn(browser[k], BROWSER_IN_SOURCE, out)
+  else namesIn(browser, BROWSER_IN_SOURCE, out)
+  // PLAN-3 5-4b: the router replies the action a `route` static names
+  const route = component?.view?.route
+  if (typeof route === 'string') out.add(route)
+  // PLAN-4 GS-5: persist() adds RESTORE (sent after hydration and by sync)
+  if (component?.view?.persist) out.add('RESTORE')
+  return out
+}
+
+/** Reply actions a component instance's requests were seen naming (replies.ts → inspect). */
+export const replySeen = new WeakMap<object, Set<string>>()
 
 /** Synthetic/internal actions (`__TEST_ACTION__`, `__NOOP_ACTION__`, ...) and built-ins. */
 export const isInternalAction = (action: string): boolean =>
@@ -59,6 +139,10 @@ let seen = new Set<string>()
 
 /** true the first time `key` is seen (dedupes reports, e.g. per component name). */
 export const once = (key: string): boolean => (seen.has(key) ? false : (seen.add(key), true))
+/** undo once(key): the report it guarded wasn't made (G-470: diagnostics off) */
+export const unsee = (key: string): void => void seen.delete(key)
+/** whether once(`key`) has reported already (a check can skip its work: SYG435) */
+export const onced = (key: string): boolean => seen.has(key)
 
 /**
  * Forget only the once() dedupe set (G-051: renderComponent calls it through the core bridge

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

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