sygnal 5.3.7 → 5.4.0

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

@@ -0,0 +1,319 @@
+/**
+ * inspect() — the machine-readable app graph at runtime (PLAN-1 workstream 2B).
+ *
+ * Built only from what the diagnostics hooks already see, keyed by component
+ * instance (so diagnostics must be on while the app runs):
+ *   onIntent    registers the instance (name, parent, kind) and its intent
+ *               action names; claims the EVENTS.select() types seen since the
+ *               previous onIntent (intent runs synchronously right before it)
+ *   onModel     action -> sinks; and wraps the component's own EVENTS model
+ *               stream (component.model$.EVENTS, before initSinks merges it)
+ *               in an identity map that records the emitted types. Since
+ *               B-023 the driver-side emitter name (onBusEmit) is the
+ *               emitting component's, but it is only a name, and this
+ *               graph is per instance, so the per-instance tap stays.
+ *   onReducer   which model-only actions actually ran (=> dispatched by next())
+ *   onBusEmit   EVENTS types seen on the bus
+ *   onBusSelect EVENTS types selected (see onIntent)
+ *   onDispose   prunes the instance
+ * Selectors come from the DOM check (real DOM) or from renderComponent (mock
+ * DOM, passed in as options.selectors). The same shape is produced statically
+ * by `sygnal-check --graph`; the JSON Schema is
+ * sygnal-check/schema/inspect.schema.json, the types are in ./public.d.ts.
+ *
+ * This lives in the 'sygnal/diagnostics' dev entry only (D29: zero bytes in
+ * app bundles). installInspect() publishes inspect() on the core bridge
+ * (renderComponent's t.inspect() reads it there) and on the devtools object
+ * (window.__SYGNAL_DEVTOOLS__, which is getDevTools()) once it exists.
+ */
+import type {DiagnosticCheck} from '../index'
+import type {InspectGraph, InspectComponent, InspectOptions, InspectSelector, InspectDiagnostic, InspectChild} from './public'
+import {bridge, onReset, nameOf, isPlainObject, BUILTIN_ACTIONS} from './shared'
+import {checkEventBus} from './events'
+import {selectorStatus} from './dom'
+
+type Kind = InspectComponent['kind']
+
+interface Rec {
+  instance: any
+  id: string
+  name: string
+  parentId: string | null
+  kind: Kind
+  /** null: single-stream intent (no action names) */
+  intentActions: string[] | null
+  injected: Set<string>
+  modelMap: Record<string, string[]>
+  fired: Set<string>
+  eventsSelected: Set<string>
+  eventsEmitted: Set<string>
+}
+
+let records = new Map<any, Rec>()
+let pendingSelects: string[] = []
+/** every EVENTS type seen on the bus */
+let busTypes = new Set<string>()
+
+onReset(() => {
+  records = new Map()
+  pendingSelects = []
+  busTypes = new Set()
+})
+const uniq = <T>(list: Iterable<T>): T[] => [...new Set(list)]
+
+function kindOf(c: any): Kind {
+  const s = (c && c.sources) || {}
+  if (typeof s.__parentComponentNumber !== 'number') return 'root'
+  // Collection items get PARENT: null (src/component.ts instantiateCollection)
+  if ('PARENT' in s && s.PARENT === null) return 'collection-item'
+  // switchable() adds a lower-case `state` source next to the component's own (src/switchable.ts)
+  if (c.stateSourceName !== 'state' && 'state' in s && s.state !== s[c.stateSourceName]) return 'switchable'
+  return 'child'
+}
+
+function ensure(c: any): Rec {
+  let r = records.get(c)
+  if (!r) {
+    const parent = c && c.sources && c.sources.__parentComponentNumber
+    r = {
+      instance: c,
+      id: String(c && c._componentNumber),
+      name: nameOf(c),
+      parentId: typeof parent === 'number' ? String(parent) : null,
+      kind: kindOf(c),
+      intentActions: [],
+      injected: new Set(),
+      modelMap: {},
+      fired: new Set(),
+      eventsSelected: new Set(),
+      eventsEmitted: new Set(),
+    }
+    records.set(c, r)
+  }
+  return r
+}
+
+let devtools: any
+function attachDevtools(): void {
+  const dt = (globalThis as any).__SYGNAL_DEVTOOLS__
+  if (!dt || typeof dt !== 'object') return
+  devtools = dt
+  if (dt.inspect !== inspect) {
+    try { dt.inspect = inspect } catch (_) { /* frozen: ignore */ }
+  }
+}
+
+export const inspectCheck: DiagnosticCheck = {
+  id: 'inspect',
+
+  onBusSelect(type) {
+    if (type === undefined || type === null || type === '') pendingSelects.push('*')
+    else for (const t of ([] as any[]).concat(type)) if (typeof t === 'string') pendingSelects.push(t)
+    if (pendingSelects.length > 1000) pendingSelects.shift()
+  },
+
+  onIntent(component, actionNames) {
+    attachDevtools()
+    const r = ensure(component)
+    const intent$ = component && component.intent$
+    r.intentActions = intent$ && typeof intent$.addListener === 'function' ? null : (actionNames || [])
+    r.injected = new Set((intent$ && typeof intent$ === 'object' && intent$.__sygnalTestActions) || [])
+    for (const t of pendingSelects) r.eventsSelected.add(t)
+    pendingSelects = []
+  },
+
+  onModel(component, modelMap) {
+    const r = ensure(component)
+    r.modelMap = modelMap || {}
+    const model$ = component && component.model$
+    const events$ = model$ && model$.EVENTS
+    if (events$ && typeof events$.map === 'function' && !events$.__sygnalInspect) {
+      const tapped = events$.map((ev: any) => {
+        if (ev && typeof ev.type === 'string') r.eventsEmitted.add(ev.type)
+        return ev
+      })
+      tapped.__sygnalInspect = true
+      model$.EVENTS = tapped
+    }
+  },
+
+  onReducer(component, action) {
+    const r = records.get(component)
+    if (r && typeof action === 'string') r.fired.add(action)
+  },
+
+  onBusEmit(type) {
+    if (typeof type === 'string') busTypes.add(type)
+  },
+
+  onDispose(component) {
+    records.delete(component)
+  },
+}
+
+const slim = (d: any): InspectDiagnostic => {
+  const out: InspectDiagnostic = {code: d.code, severity: d.severity, message: d.message}
+  if (d.component) out.component = d.component
+  if (d.fix) out.fix = d.fix
+  if (d.docsUrl) out.docsUrl = d.docsUrl
+  if (d.data !== undefined) {
+    // keep it JSON-safe (data can hold errors, vnodes, ...)
+    try { out.data = JSON.parse(JSON.stringify(d.data)) } catch (_) { /* drop */ }
+  }
+  return out
+}
+
+function actionsOf(r: Rec): InspectComponent['actions'] {
+  const intent = (r.intentActions || []).filter(a => !r.injected.has(a))
+  const names = uniq([...intent, ...Object.keys(r.modelMap)]).filter(a => typeof a === 'string' && !a.startsWith('__'))
+  return names.map(name => ({
+    name,
+    trigger: BUILTIN_ACTIONS.has(name) ? 'builtin'
+      : intent.includes(name) ? 'intent'
+      : !r.injected.has(name) && r.fired.has(name) ? 'next'
+      : 'unknown',
+    sinks: [...(r.modelMap[name] || [])],
+  }))
+}
+
+function stateKeysOf(c: any, calculated: string[]): string[] {
+  const s = c && c.currentState
+  return isPlainObject(s) ? Object.keys(s).filter(k => !calculated.includes(k)) : []
+}
+
+/**
+ * renderComponent's mock DOM (src/extra/testing.ts passes its listener registry):
+ * listener paths are the select() chain with isolation scopes as '.___<scope>' entries;
+ * probe(selectors, scope) matches one against the latest vtree: own = in the component's
+ * own scope, child = the scope of the first (isolated) child component it matches inside.
+ */
+interface MockDom {
+  listeners: Map<string, string[]>
+  evTypes: Record<string, string[]>
+  owners: Map<string, string>
+  scopeIds: Map<string, number>
+  probe: (selectors: string[], scope?: string) => {own: boolean; child?: string}
+  vtree: any
+}
+
+const isScope = (s: string) => s.startsWith('.___')
+
+function mockSelectors(mock: MockDom): Record<string, InspectSelector[]> {
+  const out: Record<string, InspectSelector[]> = {}
+  mock.listeners.forEach((path, key) => {
+    const scope = path.filter(isScope).pop()
+    const id = mock.scopeIds.get(scope || '')
+    if (id === undefined) return
+    const sels = path.filter(s => !isScope(s)).join(' ').split(/[\s>]+/).filter(Boolean)
+    const page = !sels.length || /^(document|body)$/.test(sels[0])
+    const {own, child} = mock.vtree && !page ? mock.probe(sels, scope) : {own: false, child: undefined}
+    ;(out[id] = out[id] || []).push({
+      selector: sels.join(' '),
+      events: uniq(mock.evTypes[key] || []),
+      matched: mock.vtree && !page ? own : null,
+      isolationHit: !own && child ? mock.owners.get(child) || 'a child component' : null,
+    })
+  })
+  return out
+}
+
+function selectorsOf(r: Rec, options: InspectOptions, diags: any[]): InspectSelector[] {
+  const given = options.selectors && options.selectors[r.id]
+  if (given) return given.map(s => ({...s}))
+  return (selectorStatus(r.instance) || []).map(({selector, matched, crossed}) => {
+    const hit = diags.find(d => d.code === 'SYG104' && d.component === r.name && d.data && d.data.selector === selector)
+    const missed = diags.some(d => d.code === 'SYG103' && d.component === r.name && d.data && d.data.selector === selector)
+    return {
+      selector,
+      events: null,
+      matched: matched === null && missed ? false : matched,
+      isolationHit: crossed ? ((hit && hit.data.child) || 'a child component') : null,
+    }
+  })
+}
+
+function childrenOf(r: Rec, all: Rec[]): InspectChild[] {
+  const via: Record<Kind, InspectChild['via']> = {root: 'tag', child: 'tag', 'collection-item': 'collection', switchable: 'switchable'}
+  const out = new Map<string, InspectChild>()
+  for (const c of all) {
+    if (c.parentId !== r.id) continue
+    const key = `${c.name}\u0000${via[c.kind]}`
+    const entry = out.get(key)
+    if (entry) entry.count = (entry.count || 1) + 1
+    else out.set(key, {name: c.name, via: via[c.kind], count: 1})
+  }
+  return [...out.values()]
+}
+
+/** The app graph of the live component instances (see ./public.d.ts). */
+export function inspect(options: InspectOptions = {}): InspectGraph {
+  // report SYG105 (info) for EVENTS types selected but never emitted so far
+  try { checkEventBus() } catch (_) { /* 'error' mode: info never throws; be safe */ }
+
+  let diags: any[] = options.diagnostics as any[] || []
+  if (!options.diagnostics) {
+    attachDevtools()
+    try { diags = (devtools && typeof devtools.getDiagnostics === 'function' && devtools.getDiagnostics()) || [] } catch (_) { diags = [] }
+  }
+
+  const mock: MockDom | undefined = (options as any).mock
+  if (mock) options = {...options, selectors: {...mockSelectors(mock), ...options.selectors}}
+
+  const all = [...records.values()]
+  const ids = options.ids && new Set(options.ids.map(String))
+  const recs = ids ? all.filter(r => ids.has(r.id)) : all
+  const names = new Set(recs.map(r => r.name))
+
+  const components: InspectComponent[] = recs.map(r => {
+    const c = r.instance
+    const calculated = c && c.calculated && typeof c.calculated === 'object' ? Object.keys(c.calculated) : []
+    return {
+      name: r.name,
+      id: r.id,
+      parentId: r.parentId,
+      kind: r.kind,
+      actions: actionsOf(r),
+      stateKeys: stateKeysOf(c, calculated),
+      calculated,
+      contextProvides: c && isPlainObject(c.context) ? Object.keys(c.context) : [],
+      contextConsumes: null,
+      eventsEmitted: [...r.eventsEmitted],
+      eventsSelected: [...r.eventsSelected],
+      children: childrenOf(r, all),
+      selectors: selectorsOf(r, options, diags),
+      diagnostics: diags.filter(d => d && d.component === r.name).map(slim),
+    }
+  })
+
+  const events: InspectGraph['events'] = {}
+  const ev = (type: string) => events[type] || (events[type] = {emitters: [], selectors: []})
+  const add = (list: string[], name: string) => { if (!list.includes(name)) list.push(name) }
+  for (const c of components) {
+    for (const t of c.eventsEmitted) add(ev(t).emitters, c.name)
+    for (const t of c.eventsSelected) add(ev(t).selectors, c.name)
+  }
+  // emitted on the bus by something that isn't a listed component (e.g. a driver, a pruned component)
+  if (!ids) for (const t of busTypes) ev(t)
+
+  return {
+    version: 1,
+    source: 'runtime',
+    components,
+    events,
+    diagnostics: diags.filter(d => d && (!d.component || !names.has(d.component))).map(slim),
+  }
+}
+
+/** Publish inspect() on the core bridge and the devtools object. Returns an uninstall function. */
+export function installInspect(): () => void {
+  const core = bridge()
+  if (core) core.inspect = inspect
+  attachDevtools()
+  return () => {
+    if (core && core.inspect === inspect) core.inspect = undefined
+    const dt = (globalThis as any).__SYGNAL_DEVTOOLS__
+    if (dt && dt.inspect === inspect) {
+      try { delete dt.inspect } catch (_) { /* ignore */ }
+    }
+  }
+}

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

@@ -0,0 +1,51 @@
+/**
+ * SYG106 — a prop passed by the parent is silently overwritten (warn).
+ *
+ * The view is called with { ...props, state, children, slots, context, peers },
+ * so a parent prop with one of those names never reaches the child. (Tracker
+ * G-007 item 2.) `state` is special: Sygnal reads it as the child's state
+ * lens (a state field name or a { get, set } object), so it is only reported
+ * when the value can't be a lens.
+ *
+ * Mechanism: onRender reads the component's current (sanitized) props.
+ * Reported once per component name and prop.
+ */
+import type {DiagnosticCheck} from '../index'
+import {report, once, nameOf} from './shared'
+
+const RESERVED = ['children', 'slots', 'context', 'peers']
+
+export const propsCheck: DiagnosticCheck = {
+  id: 'props',
+
+  onRender(component) {
+    const props = component && component.currentProps
+    if (!props || typeof props !== 'object') return
+    const name = nameOf(component)
+
+    for (const key of RESERVED) {
+      if (!(key in props) || !once(`SYG106:${name}:${key}`)) continue
+      report('SYG106', {
+        component,
+        severity: 'warn',
+        message: `The prop '${key}' passed to ${name} is overwritten: '${key}' is a reserved view argument, so the child never sees the parent's value`,
+        fix: `Rename the prop (for example '${key}Value'), in the parent and in ${name}`,
+        data: {prop: key},
+      })
+    }
+
+    if ('state' in props) {
+      const value = props.state
+      const isLens = typeof value === 'string' || (value && typeof value === 'object' && typeof value.get === 'function')
+      if (!isLens && value !== undefined && once(`SYG106:${name}:state`)) {
+        report('SYG106', {
+          component,
+          severity: 'warn',
+          message: `The prop 'state' passed to ${name} is not data: Sygnal reads it as the child's state lens (a state field name or a { get, set } object), and the view's 'state' argument is the child's own state`,
+          fix: `To give ${name} a slice of the parent state use state="fieldName"; to pass data, use another prop name (for example 'item')`,
+          data: {prop: 'state', valueType: typeof value},
+        })
+      }
+    }
+  },
+}

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

@@ -0,0 +1,211 @@
+/**
+ * Types for the 'sygnal/diagnostics' entry (runtime consistency checks).
+ *
+ *   import 'sygnal/diagnostics'   // registers all checks (side effect)
+ *
+ * Checks only run while diagnostics are on: run(App, drivers, { diagnostics: 'warn' }),
+ * or globalThis.__SYGNAL_DEV__ (set by the Vite plugin in dev).
+ */
+
+export type DiagnosticSeverity = 'error' | 'warn' | 'info'
+
+export interface DiagnosticCodeInfo {
+  code: string
+  severity: DiagnosticSeverity
+  title: string
+  /** anchor on https://sygnal.js.org/reference/errors, e.g. 'syg101' */
+  docsSlug: string
+}
+
+/** A runtime check, as registered with the diagnostics core. */
+export interface DiagnosticCheck {
+  id: string
+  onIntent?: (component: any, actionNames: string[], selectorsUsed: string[] | undefined) => void
+  onModel?: (component: any, modelMap: Record<string, string[]>) => void
+  onRender?: (component: any, rootVnode: any) => void
+  onReducer?: (component: any, action: string, prevState: any, nextState: any, sinkName: string) => void
+  onDispose?: (component: any) => void
+  onSelector?: (domSource: any, selector: string) => void
+  onBusEmit?: (type: string, emitterName?: string) => void
+  onBusSelect?: (type: string | string[] | undefined) => void
+}
+
+/**
+ * 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.
+ * In tests: renderComponent(C, { strict: true }).
+ */
+export function configureStrict(on?: boolean): void
+
+/** Whether the runtime strict checks are on. */
+export function isStrictEnabled(): boolean
+
+/** Every runtime check in this entry. */
+export const checks: DiagnosticCheck[]
+
+/** Re-register all checks and the RxJS hints (done automatically on import). Returns an uninstall function. */
+export function installChecks(): () => void
+
+export interface ChecksOptions {
+  /** delay after a render before the DOM checks (SYG103/104) run; default 50 ms */
+  settleMs?: number
+  /** render-idle time before SYG103 escalates to warn; default 2000 ms */
+  idleMs?: number
+  /** renders required before SYG103 escalates to warn; default 3 */
+  minRenders?: number
+}
+
+/** Tune the timing of the DOM checks (mostly for tests). */
+export function configureChecks(options?: ChecksOptions): void
+
+/** Forget what the checks have seen and reported (dedupe state, registries). For tests. */
+export function resetChecks(): void
+
+export interface EventBusSummary {
+  selected: string[]
+  emitted: string[]
+  selectedNeverEmitted: string[]
+  emittedNeverSelected: string[]
+}
+
+/**
+ * Report SYG105 (info) for every EVENTS type selected but never emitted so far,
+ * and return the EVENTS bus registry.
+ */
+export function checkEventBus(): EventBusSummary
+
+/** RxJS operator name -> xstream equivalent (used by SYG301). */
+export const RXJS_HINTS: Record<string, string>
+
+/** Metadata for every registered diagnostic code. */
+export function listCodes(): DiagnosticCodeInfo[]
+
+/** Metadata for one diagnostic code, or undefined if unknown. */
+export function getCodeInfo(code: string): DiagnosticCodeInfo | undefined
+
+// ---------------------------------------------------------------------------
+// inspect (PLAN-1 workstream 2B): a machine-readable app graph. The same shape
+// is produced at runtime (inspect(), getDevTools().inspect(), renderComponent's
+// t.inspect()) and statically (`sygnal-check --graph --json`); JSON Schema:
+// sygnal-check/schema/inspect.schema.json. Fields one side cannot know are
+// null (or omitted).
+// ---------------------------------------------------------------------------
+
+/** How an action is dispatched. */
+export type InspectActionTrigger = 'intent' | 'next' | '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.
+   */
+  trigger: InspectActionTrigger
+  /** sinks of the model entry (STATE, EVENTS, EFFECT, PARENT, custom drivers); [] without a model entry */
+  sinks: string[]
+}
+
+export interface InspectChild {
+  name: string
+  via: 'tag' | 'collection' | 'switchable' | 'slot'
+  /** Collection: the `from` state field, when known */
+  from?: string | null
+  /** runtime: number of live instances behind this entry (e.g. Collection items) */
+  count?: number
+}
+
+export interface InspectSelector {
+  /** CSS selector passed to DOM.select() (chained selects joined with a space) */
+  selector: string
+  /** event types listened to; null when unknown (runtime, real DOM) */
+  events: string[] | null
+  /**
+   * whether it matches an element the component itself renders; null when unknown.
+   * static: the class/id is in the view source. renderComponent: an element of the latest
+   * render matches (a conditionally rendered element that is hidden right now gives false).
+   * real DOM: true once a DOM check saw it match, false after SYG103/SYG104, else null.
+   */
+  matched: boolean | null
+  /** the child component whose (isolated) elements it matches instead, if any */
+  isolationHit: string | null
+}
+
+export interface InspectDiagnostic {
+  code: string
+  severity: DiagnosticSeverity
+  component?: string
+  message: string
+  fix?: string
+  docsUrl?: string
+  data?: any
+  /** static only */
+  file?: string
+  line?: number
+  column?: number
+}
+
+export interface InspectComponent {
+  name: string
+  /** runtime: instance number (as a string); static: 'file:line' of the definition */
+  id: string
+  /** runtime: the parent instance's id; static: null (see the parents' `children`) */
+  parentId: string | null
+  /** static only: source file, relative to the working directory */
+  file?: string
+  /**
+   * runtime: how the instance was created; static: 'root' when no scanned
+   * component renders it, else how it is first rendered
+   */
+  kind: 'root' | 'child' | 'collection-item' | 'switchable'
+  actions: InspectAction[]
+  /** state keys (runtime: current state; static: initialState) */
+  stateKeys: string[]
+  /** calculated field names */
+  calculated: string[]
+  /** context fields this component provides (Component.context) */
+  contextProvides: string[]
+  /** context fields its view reads (static only; null at runtime) */
+  contextConsumes?: string[] | null
+  /** EVENTS types this component emits */
+  eventsEmitted: string[]
+  /** EVENTS types this component selects ('*' = EVENTS.select() without a type) */
+  eventsSelected: string[]
+  children: InspectChild[]
+  selectors: InspectSelector[]
+  diagnostics: InspectDiagnostic[]
+}
+
+export interface InspectGraph {
+  version: 1
+  /** which implementation produced the graph */
+  source?: 'runtime' | 'static'
+  components: InspectComponent[]
+  /** EVENTS bus: type -> names of the components that emit / select it */
+  events: Record<string, { emitters: string[]; selectors: string[] }>
+  /** diagnostics not tied to a listed component */
+  diagnostics: InspectDiagnostic[]
+}
+
+export interface InspectOptions {
+  /** only these component instances (ids as in InspectComponent.id) */
+  ids?: Array<string | number>
+  /** selector details by component id (renderComponent passes its mock-DOM view) */
+  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 }>
+}
+
+/**
+ * The app graph of the live component instances, built from what the
+ * diagnostics hooks have seen (so diagnostics must be on while the app runs).
+ * Disposed components are pruned. Also available as `getDevTools().inspect()`
+ * / `window.__SYGNAL_DEVTOOLS__.inspect()` once the devtools bridge exists
+ * (run() in a browser), and as renderComponent's `t.inspect()`.
+ */
+export function inspect(options?: InspectOptions): InspectGraph

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

@@ -0,0 +1,88 @@
+/**
+ * SYG301 — an RxJS operator was called on an xstream stream (error).
+ *
+ * Without help this fails with a bare "x.switchMap is not a function" inside
+ * the intent function. Mechanism: when 'sygnal/diagnostics' is loaded, every
+ * RxJS operator name below that xstream's Stream does NOT already have is
+ * defined on Stream.prototype (non-enumerable) as a method that throws an
+ * enriched TypeError: same "stream.<op> is not a function" shape, plus the
+ * 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.
+ *
+ * Caveat: `typeof stream.pipe === 'function'` is true while this entry is
+ * loaded (dev only).
+ */
+import {report} from './shared'
+import {docsUrlFor} from '../codes'
+
+/** RxJS operator -> xstream equivalent. */
+export const RXJS_HINTS: Record<string, string> = {
+  pipe: `chain xstream operators directly (.map(...).filter(...)), or use .compose(operator) for extra operators`,
+  switchMap: `.map(x => inner$).flatten()`,
+  mergeMap: `.map(x => inner$).compose(flattenConcurrently) (import { flattenConcurrently } from 'sygnal')`,
+  flatMap: `.map(x => inner$).compose(flattenConcurrently) (import { flattenConcurrently } from 'sygnal')`,
+  concatMap: `.map(x => inner$).compose(flattenSequentially) (import { flattenSequentially } from 'sygnal')`,
+  exhaustMap: `.map(x => inner$).flatten() (xstream has no exhaustMap; ignore new values while busy with .filter())`,
+  switchAll: `.flatten()`,
+  mergeAll: `.compose(flattenConcurrently) (import { flattenConcurrently } from 'sygnal')`,
+  concatAll: `.compose(flattenSequentially) (import { flattenSequentially } from 'sygnal')`,
+  debounceTime: `.compose(debounce(ms)) (import { debounce } from 'sygnal')`,
+  debounce: `.compose(debounce(ms)) (import { debounce } from 'sygnal')`,
+  throttleTime: `.compose(throttle(ms)) (import { throttle } from 'sygnal')`,
+  throttle: `.compose(throttle(ms)) (import { throttle } from 'sygnal')`,
+  auditTime: `.compose(throttle(ms)) (import { throttle } from 'sygnal')`,
+  delay: `.compose(delay(ms)) (import { delay } from 'sygnal')`,
+  distinctUntilChanged: `.compose(dropRepeats()) (import { dropRepeats } from 'sygnal')`,
+  withLatestFrom: `.compose(sampleCombine(other$)) (import { sampleCombine } from 'sygnal')`,
+  combineLatest: `xs.combine(a$, b$) (import { xs } from 'sygnal')`,
+  combineLatestWith: `xs.combine(a$, b$) (import { xs } from 'sygnal')`,
+  merge: `xs.merge(a$, b$) (import { xs } from 'sygnal')`,
+  mergeWith: `xs.merge(a$, b$) (import { xs } from 'sygnal')`,
+  concat: `concat(a$, b$) (import { concat } from 'sygnal')`,
+  scan: `.fold((acc, x) => next, seed)`,
+  reduce: `.fold((acc, x) => next, seed).last()`,
+  skip: `.drop(n)`,
+  first: `.take(1)`,
+  takeUntil: `.endWhen(other$)`,
+  tap: `.debug(fn)`,
+  do: `.debug(fn)`,
+  catchError: `.replaceError(err => fallback$)`,
+  catch: `.replaceError(err => fallback$)`,
+  pluck: `.map(x => x.field)`,
+  share: `xstream streams are already shared (hot); use .remember() to replay the latest value`,
+  shareReplay: `.remember()`,
+  publishReplay: `.remember()`,
+  finalize: `.debug({ complete: fn }) or handle completion in the subscriber`,
+}
+
+const SYG301_URL = docsUrlFor('SYG301')
+
+function rxjsError(op: string): TypeError {
+  const hint = RXJS_HINTS[op]
+  const message = `stream.${op} is not a function: '${op}' is an RxJS operator, but Sygnal streams are xstream streams`
+  const fix = `Use ${hint}`
+  // In 'error' mode report() throws the DiagnosticError itself (we are about to throw anyway).
+  const d = report('SYG301', {message, fix, data: {operator: op, hint}})
+  const err: any = new TypeError(d ? d.text : `[Sygnal SYG301] ${message}. ${fix}. ${SYG301_URL}`)
+  err.diagnostic = d
+  return err
+}
+
+/** Install the hints on xstream's Stream.prototype. Returns an uninstall function. */
+export function installRxjsHints(proto: any): () => void {
+  const added: string[] = []
+  if (!proto) return () => {}
+  for (const op of Object.keys(RXJS_HINTS)) {
+    if (op in proto) continue
+    Object.defineProperty(proto, op, {
+      configurable: true,
+      writable: true,
+      enumerable: false,
+      value: function rxjsOperatorHint() { throw rxjsError(op) },
+    })
+    added.push(op)
+  }
+  return () => { for (const op of added) delete proto[op] }
+}