what-core 0.12.4 → 0.13.0

package/src/errors.js

@@ -157,8 +157,294 @@ redirect(ALLOWED.has(query.next) ? query.next : '/');`,
 try { html = renderToString(<App />); }
 catch (e) { if (e.name === 'RouterRedirect') return Response.redirect(e.to, 302); throw e; }`,
   },
+
+  // --- Outside core ---
+  //
+  // Every package in the workspace threw bare `new Error(...)` with good prose
+  // and no code, so nothing downstream could branch on the failure and the
+  // what_errors MCP tool could only ever enumerate core's own. The entries
+  // below are the catalogue for the rest of the framework.
+  //
+  // These are catalogued here but NOT constructed here. A throw outside core
+  // carries only its `code`; the suggestion and the worked example live once,
+  // in this file, and are resolved from the code by classifyError() or by
+  // reading ERROR_CODES directly.
+  //
+  // That split is a size decision, and it was measured. Importing
+  // createWhatError() into what-server's client-shipped action surface retains
+  // this whole catalogue through the bundler: esbuild took that surface from
+  // 8.4 KB minified / 3.5 KB gzipped to 25.9 KB / 9.7 KB. Six kilobytes of
+  // gzipped prose in every visitor's browser is the wrong trade for making
+  // three server-side messages structured.
+  //
+  // The same rule keeps the packages that genuinely cannot import core honest:
+  // what-isr never imports what-server, which is what keeps it usable from any
+  // adapter; the compiler runs inside Babel at build time; the MCP server has
+  // no framework dependency; and the CLI loads the project's runtime, not its
+  // own. `scripts/check-error-codes.mjs` asserts every `ERR_*` literal thrown
+  // anywhere under packages/*/src appears here, so nothing drifts.
+
+  NO_SECURE_RANDOM: {
+    code: 'ERR_NO_SECURE_RANDOM',
+    severity: 'error',
+    template: '[what] No secure random source available for CSRF token generation.',
+    suggestion: 'Neither globalThis.crypto.getRandomValues nor node:crypto was reachable. On Node this means a build older than 18 or a bundler that stripped node:crypto; on an edge runtime it means the Web Crypto global was not provided. A CSRF token from Math.random is not a token, so this refuses rather than degrading.',
+    codeExample: `// Node 18+ exposes Web Crypto globally; nothing to configure.
+// If a bundler dropped it, restore the global before creating the server:
+import { webcrypto } from 'node:crypto';
+globalThis.crypto ??= webcrypto;`,
+  },
+
+  ACTION_FAILED: {
+    code: 'ERR_ACTION_FAILED',
+    severity: 'error',
+    template: '{{message}}',
+    suggestion: 'The server action rejected. The message is the one the action threw, forwarded to the client by the action handler. Throw a typed error from the action and branch on its shape rather than parsing this string.',
+    codeExample: `// In the action, fail with something the client can read:
+export const save = action(async (data) => {
+  if (!data.email) throw Object.assign(new Error('Email required'), { field: 'email' });
+});`,
+  },
+
+  STATIC_WRITE_ESCAPE: {
+    code: 'ERR_STATIC_WRITE_ESCAPE',
+    severity: 'error',
+    template: '[what-server] Refusing to write outside outDir: {{path}}.',
+    suggestion: 'A route path resolved to a location outside the export directory, which a "../" segment in a route or a param can do. Sanitize the route path, or drop the route from the static export.',
+    codeExample: `// Bad — a param that can contain a slash escapes outDir:
+{ path: '/docs/:slug*', mode: 'static' }
+
+// Good — constrain the param, or precompute the exact paths:
+{ path: '/docs/:slug', mode: 'static', paths: () => slugs.map(slug => ({ slug })) }`,
+  },
+
+  INVALID_SSR_TAG: {
+    code: 'ERR_INVALID_SSR_TAG',
+    severity: 'error',
+    template: '[what-server] Invalid tag name in SSR: {{tag}}.',
+    suggestion: 'renderToString reached a vnode whose tag is neither a string nor a component function. This is almost always a component that returned a raw object, or a value interpolated where an element was expected.',
+    codeExample: `// Bad — returns a plain object, not a vnode:
+function Row() { return { name: 'a' }; }
+
+// Good — return elements, and interpolate values as children:
+function Row({ name }) { return <li>{name}</li>; }`,
+  },
+
+  FORM_ACTION_NOT_REGISTERED: {
+    code: 'ERR_FORM_ACTION_NOT_REGISTERED',
+    severity: 'error',
+    template: '[what] <Form action={fn}>: that function is not a server action.',
+    suggestion: 'Wrap it with action() from what-server, or pass the action id as a string. A plain function has no id, so there is nothing for the form post to address.',
+    codeExample: `// Bad — a plain function:
+async function save(data) {}
+<Form action={save} />
+
+// Good — a registered action:
+export const save = action(async (data) => {});
+<Form action={save} />`,
+  },
+
+  FORM_ACTION_MISSING: {
+    code: 'ERR_FORM_ACTION_MISSING',
+    severity: 'error',
+    template: '[what] <Form> requires an `action` prop: a server action or its id.',
+    suggestion: 'Pass the action itself, or the string id it was registered under.',
+    codeExample: `// Bad:
+<Form method="post" />
+
+// Good:
+<Form action={save} />
+<Form action="save-user" />`,
+  },
+
+  ISLAND_STORE_OUTSIDE_RENDER: {
+    code: 'ERR_ISLAND_STORE_OUTSIDE_RENDER',
+    severity: 'error',
+    template: '[what-server] Island store "{{name}}" was accessed outside an active server render.',
+    suggestion: 'A module-scoped island store resolves against the current request, so it can only be read or written from a component rendered by renderDocument/renderPage. Reading one at module scope, or from a background task, has no request to bind to.',
+    codeExample: `// Bad — runs at import time, with no request in scope:
+const count = cart.items.length;
+
+// Good — read it inside a component the server is rendering:
+function Cart() { return <span>{cart.items.length}</span>; }`,
+  },
+
+  ISR_MISSING_CLIENT: {
+    code: 'ERR_ISR_MISSING_CLIENT',
+    severity: 'error',
+    template: '[what-isr] createRedisStore requires { client }.',
+    suggestion: 'what-isr ships no Redis driver on purpose, so the client is injected. Pass an ioredis or node-redis instance (get/set/del/sadd/srem/smembers, optionally expire/scan/keys).',
+    codeExample: `import Redis from 'ioredis';
+const store = createRedisStore({ client: new Redis(process.env.REDIS_URL) });`,
+  },
+
+  ISR_VARY_UNRESOLVED: {
+    code: 'ERR_ISR_VARY_UNRESOLVED',
+    severity: 'error',
+    template: '[what-isr] cannot build a cache key: `vary` is declared but could not be resolved against the request.',
+    suggestion: 'A declared vary is a list of names that must be resolved against real request headers before it can be part of a key. Either pass the request headers alongside the declaration, or pass an already-resolved name -> value object. Guessing would cache one visitor page under another visitor key.',
+    codeExample: `// Bad — a declaration with nothing to resolve it against:
+cacheKey({ path, vary: ['cookie:session'] });
+
+// Good — supply the headers:
+cacheKey({ path, vary: ['cookie:session'], headers: request.headers });
+
+// Good — or resolve it yourself:
+cacheKey({ path, vary: { 'cookie:session': sessionId } });`,
+  },
+
+  ISR_VARY_NO_HEADERS: {
+    code: 'ERR_ISR_VARY_NO_HEADERS',
+    severity: 'error',
+    template: '[what-isr] route declares `vary` but the adapter supplied no request headers; refusing to cache.',
+    suggestion: 'The route varies its output per header, and the adapter called the engine without them. Caching anyway would serve one variant to every request. Forward the request headers from the adapter into the engine call.',
+    codeExample: `// In the adapter:
+await engine.handle(routeMatch, { headers: request.headers });`,
+  },
+
+  DUPLICATE_ACTION_ID: {
+    code: 'ERR_DUPLICATE_ACTION_ID',
+    severity: 'error',
+    template: 'Duplicate server action ID "{{id}}".',
+    suggestion: 'Action ids are the wire address of a server action, so two actions cannot share one. Ids derive from the file path and export name, so this usually means the same action is being registered twice, or an explicit id was reused.',
+    codeExample: `// Bad — two actions pinned to the same id:
+export const save = action(fn, { id: 'save' });
+export const store = action(fn, { id: 'save' });
+
+// Good — let ids derive, or make them distinct:
+export const save = action(fn);
+export const store = action(fn, { id: 'store-user' });`,
+  },
+
+  PAGE_NO_DEFAULT_EXPORT: {
+    code: 'ERR_PAGE_NO_DEFAULT_EXPORT',
+    severity: 'error',
+    template: 'Page module has no default-exported component.',
+    suggestion: 'A page file must default-export the component to render. A named export cannot be found by the file-router.',
+    codeExample: `// Bad:
+export function Home() { return <h1>Hi</h1>; }
+
+// Good:
+export default function Home() { return <h1>Hi</h1>; }`,
+  },
+
+  HOOK_OUTSIDE_RENDER: {
+    code: 'ERR_HOOK_OUTSIDE_RENDER',
+    severity: 'error',
+    template: '[what-react] {{hookName}}() called outside of a component render.',
+    suggestion: 'Hooks can only be called while a what-react component is rendering. When this happens inside a React library, the usual cause is two module instances: make sure every `react` and `react-dom` import is aliased to what-react by the reactCompat() vite plugin.',
+    codeExample: `// vite.config.js
+import { reactCompat } from 'what-react/vite';
+export default { plugins: [reactCompat()] };`,
+  },
+
+  CHILDREN_ONLY: {
+    code: 'ERR_CHILDREN_ONLY',
+    severity: 'error',
+    template: 'React.Children.only expected to receive a single React element child.',
+    suggestion: 'Children.only asserts exactly one element. Pass one child, or use Children.toArray/Children.map when the count can vary.',
+    codeExample: `// Bad:
+<Tooltip><span>a</span><span>b</span></Tooltip>
+
+// Good:
+<Tooltip><span>a</span></Tooltip>`,
+  },
+
+  USE_INVALID_ARG: {
+    code: 'ERR_USE_INVALID_ARG',
+    severity: 'error',
+    template: '[what-react] use() expects a promise or a context.',
+    suggestion: 'use() reads either a thenable or a context object. Anything else has nothing to suspend on or subscribe to.',
+    codeExample: `// Good:
+const value = use(ThemeContext);
+const data = use(fetchUser(id));`,
+  },
+
+  PRETEXT_NOT_INSTALLED: {
+    code: 'ERR_PRETEXT_NOT_INSTALLED',
+    severity: 'error',
+    template: '[what-text] Failed to load @chenglou/pretext: {{message}}.',
+    suggestion: 'what-text declares pretext as an optional peer so the package installs without it. Install it to use the text engine: npm install @chenglou/pretext',
+    codeExample: `npm install @chenglou/pretext`,
+  },
+
+  DESTRUCTURED_PROPS: {
+    code: 'ERR_DESTRUCTURED_PROPS',
+    severity: 'warning',
+    template: "Destructuring '{{binding}}' in the component body snapshots props and loses reactivity.",
+    suggestion: "What components run ONCE, so the body is not re-run when a prop changes. Reading `props.foo` goes through the reactive proxy and tracks; `const { foo } = props` reads the value once and detaches it. Read through the proxy inside JSX and effects, or wrap each field in an accessor.",
+    codeExample: `// Bad - snapshots at first run, never updates:
+function Row(props) {
+  const { label } = props;
+  return <span>{label}</span>;
+}
+
+// Good - reads through the proxy each time:
+function Row(props) {
+  return <span>{props.label}</span>;
+}
+
+// Good - an accessor keeps the destructured name:
+function Row(props) {
+  const label = () => props.label;
+  return <span>{label()}</span>;
+}`,
+  },
+
+  // --- Fallbacks ---
+  // classifyError() returns one of these when a raw Error does not match any
+  // known pattern. They are catalogued so what_errors never reports a code an
+  // agent cannot look up.
+
+  RUNTIME: {
+    code: 'ERR_RUNTIME',
+    severity: 'error',
+    template: '{{message}}',
+    suggestion: 'An error surfaced that the framework could not classify, so the message is the original one verbatim. The stack, file and line on the error narrow it; if the same shape shows up repeatedly it is worth its own code here.',
+    codeExample: `// Inspect the structured form rather than the string:
+try { render(); } catch (e) { console.log(classifyError(e).toJSON()); }`,
+  },
+
+  UNKNOWN: {
+    code: 'ERR_UNKNOWN',
+    severity: 'error',
+    template: 'Unknown error: {{errorCode}}.',
+    suggestion: 'createWhatError() was called with a code that is not in this catalogue. Check the spelling against ERROR_CODES, or add the entry.',
+    codeExample: `// Bad - not a catalogue key:
+createWhatError('MISSING_KEYS');
+
+// Good:
+createWhatError('MISSING_KEY', { component: 'TodoList' });`,
+  },
+
+  UNKNOWN_TOOL: {
+    code: 'ERR_UNKNOWN_TOOL',
+    severity: 'error',
+    template: 'Unknown tool: {{name}}.',
+    suggestion: 'The MCP client called a tool this server does not expose. Call tools/list to enumerate what is available; a stale client cache is the usual cause.',
+    codeExample: `// List what the server actually exposes:
+{ "method": "tools/list" }`,
+  },
 };
 
+// Reverse index: an error carries `code: 'ERR_X'`, and the catalogue is keyed
+// by its short name.
+//
+// Built on first use, NOT at module load. A top-level `new Map(...)` over
+// ERROR_CODES is a side effect that references the catalogue, which pins it
+// into every bundle that imports what-core: it took the counter app from
+// 6.4 KB gzipped to 12.1 KB and tripped check:size. Inside a function, a
+// bundler that drops getErrorDefinition drops the catalogue with it.
+let _codeIndex = null;
+
+/** Look up a catalogue entry by its `ERR_*` code. Returns undefined if unknown. */
+export function getErrorDefinition(code) {
+  if (_codeIndex === null) {
+    _codeIndex = new Map(Object.values(ERROR_CODES).map((def) => [def.code, def]));
+  }
+  return _codeIndex.get(code);
+}
+
 // --- WhatError ---
 // Structured error class with full context for agent consumption.
 
@@ -169,6 +455,18 @@ export class WhatError extends Error {
   // there and `suggestion` had to carry the whole fix in prose. It matters more
   // here than in a framework aimed at humans: the audience reading toJSON() is
   // usually an agent, and a diff-shaped example is the part it can copy.
+  /**
+   * @param {object} init
+   * @param {string} init.code
+   * @param {string} [init.message]
+   * @param {string} [init.suggestion]
+   * @param {{ bad?: string, good?: string } | string} [init.codeExample]
+   * @param {string} [init.file]
+   * @param {number} [init.line]
+   * @param {string} [init.component]
+   * @param {string} [init.signal]
+   * @param {string} [init.effect]
+   */
   constructor({ code, message, suggestion, codeExample, file, line, component, signal, effect }) {
     super(message);
     this.name = 'WhatError';
@@ -265,6 +563,29 @@ export function clearCollectedErrors() {
 export function classifyError(err, context = {}) {
   const msg = err?.message || String(err);
 
+  // An error the framework threw already says what it is. Every throw outside
+  // core carries a `code` and nothing else — the suggestion and the worked
+  // example live once, in ERROR_CODES — so resolving the code here is what
+  // makes them reachable at all. Message sniffing below is only for errors
+  // that predate the code, or that come from user code.
+  if (err && typeof err.code === 'string') {
+    const def = getErrorDefinition(err.code);
+    if (def) {
+      return new WhatError({
+        code: def.code,
+        // The thrown message is the specific one; the template is generic.
+        message: msg,
+        suggestion: def.suggestion,
+        codeExample: def.codeExample,
+        file: context.file,
+        line: context.line,
+        component: context.component,
+        signal: context.signal || context.signalName,
+        effect: context.effect || context.effectName,
+      });
+    }
+  }
+
   // Infinite effect loop
   if (msg.includes('infinite effect loop') || msg.includes('25 iterations')) {
     return createWhatError('INFINITE_EFFECT', context);

package/src/form.js

@@ -21,6 +21,7 @@ function _applyRef(ref, el) {
 function _composeHandlers(registered, callerHandler) {
   if (typeof registered !== 'function') return callerHandler;
   if (typeof callerHandler !== 'function') return registered;
+  /** @this {any} */
   return function composedHandler(...args) {
     registered.apply(this, args);
     return callerHandler.apply(this, args);
@@ -340,7 +341,7 @@ function createFormController(options = {}) {
         if (!el._propEffects) el._propEffects = {};
         const key = 'checked:property';
         if (el._propEffects[key]) {
-          try { el._propEffects[key](); } catch (err) { /* already disposed */ }
+          try { el._propEffects[key](); } catch { /* already disposed */ }
         }
         // radioValueOf(el) is re-read on every run rather than captured, so a
         // registration without a declared value still binds correctly once the

package/src/head.js

@@ -130,7 +130,8 @@ function escapeHtml(str) {
 function escapeSelectorValue(key) {
   const s = String(key);
   if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') return CSS.escape(s);
-  return s.replace(/[^a-zA-Z0-9_-]/g, (c) => `\\${c.codePointAt(0).toString(16)} `);
+  // `c` is a single matched code unit, so codePointAt(0) is always defined.
+  return s.replace(/[^a-zA-Z0-9_-]/g, (c) => `\\${/** @type {number} */ (c.codePointAt(0)).toString(16)} `);
 }
 
 function setHeadTag(tag, key, attrs) {

package/src/hooks.js

@@ -3,7 +3,7 @@
 // Components run ONCE. Hooks return signal accessors (functions) so the
 // fine-grained runtime handles reactive updates automatically via effects.
 
-import { signal, computed, effect, batch, untrack, createRoot, __DEV__ } from './reactive.js';
+import { signal, computed, effect, batch, untrack, __DEV__ } from './reactive.js';
 import { getCurrentComponent } from './dom.js';
 import { getServerContext, isServerRender } from './server-context.js';
 import { getLoaderData as _getLoaderData, getResource as _getResource } from './hydration-data.js';
@@ -138,7 +138,7 @@ export function useEffect(fn, deps) {
       if (ctx.disposed) return;
       hook.dispose = effect(() => {
         if (hook.cleanup) {
-          try { hook.cleanup(); } catch (e) { /* cleanup error */ }
+          try { hook.cleanup(); } catch { /* cleanup error */ }
           hook.cleanup = null;
         }
         const result = fn();
@@ -174,7 +174,7 @@ export function useEffect(fn, deps) {
 
         // Run cleanup from previous execution
         if (hook.cleanup) {
-          try { hook.cleanup(); } catch (e) { /* cleanup error */ }
+          try { hook.cleanup(); } catch { /* cleanup error */ }
           hook.cleanup = null;
         }
 
@@ -195,7 +195,7 @@ export function useEffect(fn, deps) {
 // computed() auto-tracks signal dependencies.
 // Returns a computed signal function (call it to read the value).
 
-export function useMemo(fn, deps) {
+export function useMemo(fn, _deps) {
   const ctx = getCtx('useMemo');
   const { index, exists } = getHook(ctx);
 
@@ -211,7 +211,7 @@ export function useMemo(fn, deps) {
 // executes once, so the callback reference is inherently stable.
 // Simply store and return the function on first call.
 
-export function useCallback(fn, deps) {
+export function useCallback(fn, _deps) {
   const ctx = getCtx('useCallback');
   const { index, exists } = getHook(ctx);
 
@@ -295,7 +295,7 @@ export function createContext(defaultValue) {
   };
   // The context value is only published once the provider body runs, so
   // compiled children must not be built during this call. See createComponent.
-  context.Provider._deferChildren = true;
+  /** @type {any} */ (context.Provider)._deferChildren = true;
   return context;
 }
 
@@ -452,14 +452,7 @@ export function createResource(fetcher, options = {}) {
   return [data, { loading, error, refetch, mutate }];
 }
 
-// --- Dep comparison (kept for potential external use) ---
-
-function depsChanged(oldDeps, newDeps) {
-  if (oldDeps === undefined) return true;
-  if (!oldDeps || !newDeps) return true;
-  if (oldDeps.length !== newDeps.length) return true;
-  for (let i = 0; i < oldDeps.length; i++) {
-    if (!Object.is(oldDeps[i], newDeps[i])) return true;
-  }
-  return false;
-}
+// A local `depsChanged` lived here, commented "kept for potential external
+// use". It was never exported, so there was no external use to keep it for,
+// and nothing in this package called it. react-compat has its own copy, which
+// is the one that is actually used.

package/src/index.js

@@ -178,6 +178,7 @@ export {
 export {
   WhatError,
   ERROR_CODES,
+  getErrorDefinition,
   createWhatError,
   classifyError,
   collectError,

package/src/reactive.js

@@ -30,6 +30,7 @@ export const __DEV__ =
 
 // DevTools hooks — set by what-devtools when installed.
 // These are no-ops in production (dead-code eliminated with __DEV__).
+/** @type {WhatDevToolsHooks | null} */
 export let __devtools = null;
 
 /** @internal Install devtools hooks. Called by what-devtools. */
@@ -96,7 +97,7 @@ export function signal(initial, debugName) {
     // Invalidate lastTracked since value changed — any effect that reads
     // this signal during re-run needs to re-track.
     lastTracked = null;
-    if (__DEV__ && __devtools) __devtools.onSignalUpdate(sig);
+    if (__DEV__ && __devtools) __devtools.onSignalUpdate?.(sig);
     if (subs.size > 0) notify(subs);
   }
 
@@ -134,11 +135,21 @@ export function signal(initial, debugName) {
   sig._signal = true;
   if (__DEV__) {
     sig._subs = subs;
+    // Back-reference from the subscriber Set to its signal, for trackSignals()
+    // in testing.js. An effect records dependencies as the `subs` Sets it
+    // joined (see the read path above), which is one-directional: given an
+    // effect you can count its deps but not name them.
+    //
+    // Deliberately NOT `_owner`. That property is load-bearing for topological
+    // level computation, and a signal's Set is documented above as having
+    // `_owner === undefined` precisely because signals are level 0. A separate
+    // dev-only name keeps that invariant intact.
+    subs._signalOwner = sig;
     if (debugName) sig._debugName = debugName;
   }
 
   // Notify devtools of signal creation
-  if (__DEV__ && __devtools) __devtools.onSignalCreate(sig);
+  if (__DEV__ && __devtools) __devtools.onSignalCreate?.(sig);
 
   return sig;
 }
@@ -337,7 +348,7 @@ export function effect(fn, opts) {
   //   effect could never re-fire anyway, so releasing is safe.
   if (e.deps.length === 0 && e._cleanup === null) {
     e.disposed = true;
-    if (__DEV__ && __devtools) __devtools.onEffectDispose(e);
+    if (__DEV__ && __devtools) __devtools.onEffectDispose?.(e);
     return _noopDispose;
   }
 
@@ -369,6 +380,7 @@ function _createEffect(fn, lazy) {
   // IMPORTANT: V8 optimizes objects with a consistent "hidden class" (shape).
   // All properties must be declared upfront even if null — adding properties
   // later causes shape transitions which deoptimize property access globally.
+  /** @type {WhatEffectNode} */
   const e = {
     fn,
     deps: [],            // array of subscriber sets (cheaper than Set for typical 1-3 deps)
@@ -385,7 +397,7 @@ function _createEffect(fn, lazy) {
     _cleanup: null,       // cleanup function returned by effect fn (declared upfront for shape)
     _epoch: 0,           // incremented on cleanup — used by signal lastTracked cache
   };
-  if (__DEV__ && __devtools) __devtools.onEffectCreate(e);
+  if (__DEV__ && __devtools) __devtools.onEffectCreate?.(e);
   return e;
 }
 
@@ -409,12 +421,12 @@ function _runEffect(e) {
       const result = e.fn();
       if (typeof result === 'function') e._cleanup = result;
     } catch (err) {
-      if (__devtools?.onError) __devtools.onError(err, { type: 'effect', effect: e });
+      if (__devtools?.onError) __devtools.onError?.(err, { type: 'effect', effect: e });
       if (__DEV__) console.warn('[what] Error in stable effect:', err);
     } finally {
       currentEffect = prev;
     }
-    if (__DEV__ && __devtools?.onEffectRun) __devtools.onEffectRun(e);
+    if (__DEV__ && __devtools?.onEffectRun) __devtools.onEffectRun?.(e);
     return;
   }
 
@@ -426,7 +438,7 @@ function _runEffect(e) {
   // Run effect cleanup from previous run
   if (e._cleanup) {
     try { e._cleanup(); } catch (err) {
-      if (__DEV__ && __devtools?.onError) __devtools.onError(err, { type: 'effect-cleanup', effect: e });
+      if (__DEV__ && __devtools?.onError) __devtools.onError?.(err, { type: 'effect-cleanup', effect: e });
       if (__DEV__) console.warn('[what] Error in effect cleanup:', err);
     }
     e._cleanup = null;
@@ -441,7 +453,7 @@ function _runEffect(e) {
     }
   } catch (err) {
     if (err === NEEDS_UPSTREAM) throw err; // Iterative eval sentinel — not a real error
-    if (__DEV__ && __devtools?.onError) __devtools.onError(err, { type: 'effect', effect: e });
+    if (__DEV__ && __devtools?.onError) __devtools.onError?.(err, { type: 'effect', effect: e });
     throw err;
   } finally {
     currentEffect = prev;
@@ -458,12 +470,12 @@ function _runEffect(e) {
     e._stable = true;
   }
 
-  if (__DEV__ && __devtools?.onEffectRun) __devtools.onEffectRun(e);
+  if (__DEV__ && __devtools?.onEffectRun) __devtools.onEffectRun?.(e);
 }
 
 function _disposeEffect(e) {
   e.disposed = true;
-  if (__DEV__ && __devtools) __devtools.onEffectDispose(e);
+  if (__DEV__ && __devtools) __devtools.onEffectDispose?.(e);
   cleanup(e);
   // Run cleanup on dispose
   if (e._cleanup) {
@@ -509,11 +521,11 @@ function _processSubscriber(e) {
       try {
         const result = e.fn();
         if (typeof result === 'function') {
-          if (e._cleanup) try { e._cleanup(); } catch (err) { /* ignore */ }
+          if (e._cleanup) try { e._cleanup(); } catch { /* ignore */ }
           e._cleanup = result;
         }
       } catch (err) {
-        if (__DEV__ && __devtools?.onError) __devtools.onError(err, { type: 'effect', effect: e });
+        if (__DEV__ && __devtools?.onError) __devtools.onError?.(err, { type: 'effect', effect: e });
         if (__DEV__) console.warn('[what] Error in stable effect:', err);
       } finally {
         currentEffect = prev;
@@ -617,7 +629,7 @@ function flush() {
             _runEffect(e);
           } catch (err) {
             if (err === NEEDS_UPSTREAM) throw err;
-            if (__DEV__ && __devtools?.onError) __devtools.onError(err, { type: 'effect', effect: e });
+            if (__DEV__ && __devtools?.onError) __devtools.onError?.(err, { type: 'effect', effect: e });
             // Surface in production too — an uncaught reactive-update error is a
             // real bug; staying silent (as the old throw-out-of-flush did once it
             // escaped) hides it. console.error never aborts the batch.
@@ -786,6 +798,7 @@ export function createRoot(fn) {
   const prevRoot = currentRoot;
   const prevOwner = currentOwner;
   const root = {
+    /** @type {Array<() => void>} */
     disposals: [],
     owner: currentOwner,     // parent owner for ownership tree
     children: [],            // child roots (ownership tree)
@@ -856,6 +869,7 @@ export function _createItemScope(fn) {
   const prevRoot = currentRoot;
   const prevOwner = currentOwner;
   const scope = {
+    /** @type {Array<() => void>} */
     disposals: [],
     owner: null,          // No parent registration
     children: [],         // Kept for compat with effects that create sub-roots
@@ -914,6 +928,7 @@ if (__DEV__ && typeof WeakRef !== 'undefined') {
   // needed before the devtools entry point runs; once devtools install, the
   // buffer is drained and subsequent creations flow through the real hooks.
   const PREINSTALL_CAP = 2000;
+  /** @type {{ signals: Set<any>, effects: Set<any>, components: any[] }} */
   const buffer = { signals: new Set(), effects: new Set(), components: [] };
   __devtools = {
     __isPreinstallBuffer: true,
@@ -940,9 +955,10 @@ if (__DEV__ && typeof WeakRef !== 'undefined') {
  * __setDevToolsHooks replaces the placeholder. Returns arrays of live refs.
  */
 export function __drainPreinstallBuffer() {
-  if (!__DEV__) return { signals: [], effects: [], components: [] };
+  if (!__DEV__) return /** @type {{ signals: any[], effects: any[], components: any[] }} */ ({ signals: [], effects: [], components: [] });
   // If the current __devtools is the real one (no __isPreinstallBuffer), the
   // caller installed late and there is nothing to drain from this side.
+  /** @type {{ signals: any[], effects: any[], components: any[] }} */
   const out = { signals: [], effects: [], components: [] };
   const buf = (typeof __preinstallSnapshot !== 'undefined') ? __preinstallSnapshot : null;
   if (!buf) return out;
@@ -954,6 +970,7 @@ export function __drainPreinstallBuffer() {
 
 // Capture the placeholder buffer at module load so __drainPreinstallBuffer
 // can return it AFTER __setDevToolsHooks has replaced __devtools.
+/** @type {WhatDevToolsHooks['__buffer'] | null} */
 let __preinstallSnapshot = null;
 if (__DEV__ && __devtools?.__isPreinstallBuffer) {
   __preinstallSnapshot = __devtools.__buffer;