sygnal 5.3.7 → 6.0.0

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

@@ -0,0 +1,302 @@
+/**
+ * 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), 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
+
+/** 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' | 'reply' | 'builtin' | 'unknown'
+
+export interface InspectAction {
+  name: string
+  /**
+   * 'intent': returned by the component's intent. 'builtin': BOOTSTRAP,
+   * 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 */
+  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
+  /** 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 {
+  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[]
+  /** 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 {
+  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[]
+  /** 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 {
+  /** 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 }>
+  /** PLAN-4 2-C: add `recentActions`: true for every kept one (the last 200), a number for the last n */
+  actions?: boolean | number
+}
+
+/**
+ * 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/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

@@ -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 the core.
+ *
+ * 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] }
+}