what-core 0.12.3 → 0.13.0

package/src/dom.js

@@ -2,8 +2,8 @@
 // Components run ONCE. Signals create individual DOM effects.
 // No VDOM reconciler, no diffing — direct DOM manipulation driven by signals.
 
-import { effect, batch, untrack, signal, __DEV__, __devtools } from './reactive.js';
-import { reportError, _injectGetCurrentComponent, shallowEqual } from './components.js';
+import { effect, untrack, signal, __DEV__, __devtools } from './reactive.js';
+import { reportError, _injectGetCurrentComponent } from './components.js';
 import { _setComponentRef } from './helpers.js';
 // SVG elements that need namespace
 const SVG_ELEMENTS = new Set([
@@ -119,7 +119,7 @@ function disposeComponent(ctx) {
   // Run effect disposals
   if (ctx.effects) {
     for (const dispose of ctx.effects) {
-      try { dispose(); } catch (e) { /* already disposed */ }
+      try { dispose(); } catch { /* already disposed */ }
     }
   }
 
@@ -139,7 +139,7 @@ function disposeComponent(ctx) {
     }
   }
 
-  if (__DEV__ && __devtools?.onComponentUnmount) __devtools.onComponentUnmount(ctx);
+  if (__DEV__ && __devtools?.onComponentUnmount) __devtools.onComponentUnmount?.(ctx);
   mountedComponents.delete(ctx);
 }
 
@@ -169,7 +169,7 @@ export function disposeTree(node) {
     const disposers = node._hydrationDisposers;
     node._hydrationDisposers = null;
     for (let i = 0; i < disposers.length; i++) {
-      try { disposers[i](); } catch (e) { /* already disposed */ }
+      try { disposers[i](); } catch { /* already disposed */ }
     }
   }
   // Check comment node WeakMap for component context — only for comment nodes
@@ -181,12 +181,12 @@ export function disposeTree(node) {
   }
   // Dispose reactive function child effects ({() => ...} wrappers)
   if (node._dispose) {
-    try { node._dispose(); } catch (e) { /* already disposed */ }
+    try { node._dispose(); } catch { /* already disposed */ }
   }
   // Dispose reactive prop effects (value: () => ..., class: () => ..., etc.)
   if (node._propEffects) {
     for (const key in node._propEffects) {
-      try { node._propEffects[key](); } catch (e) { /* already disposed */ }
+      try { node._propEffects[key](); } catch { /* already disposed */ }
     }
   }
   // Recursively dispose children
@@ -384,7 +384,7 @@ const _propsProxyHandler = {
     }
     return undefined;
   },
-  set(target, key) {
+  set(_target, _key) {
     // Props are read-only from the component's perspective.
     // Reject all writes — especially dangerous prototype-chain keys.
     return false;
@@ -436,6 +436,7 @@ export function _beginComponentSSR(Component) {
   const ctx = {
     hooks: [],
     hookIndex: 0,
+    /** @type {Array<() => void>} */
     effects: [],
     cleanups: [],
     mounted: false,
@@ -563,6 +564,7 @@ function createComponent(vnode, parent, isSvg) {
   const ctx = {
     hooks: [],
     hookIndex: 0,
+    /** @type {Array<() => void>} */
     effects: [],
     cleanups: [],
     mounted: false,
@@ -587,7 +589,7 @@ function createComponent(vnode, parent, isSvg) {
 
   // Track for disposal
   mountedComponents.add(ctx);
-  if (__DEV__ && __devtools?.onComponentMount) __devtools.onComponentMount(ctx);
+  if (__DEV__ && __devtools?.onComponentMount) __devtools.onComponentMount?.(ctx);
 
   // Props signal for reactive updates from parent
   const propsChildren = children.length === 0 ? undefined : children.length === 1 ? children[0] : children;
@@ -699,7 +701,9 @@ function createErrorBoundary(vnode, parent) {
   const endComment = document.createComment('eb:end');
 
   const boundaryCtx = {
-    hooks: [], hookIndex: 0, effects: [], cleanups: [],
+    hooks: /** @type {any[]} */ ([]), hookIndex: 0,
+    effects: /** @type {Array<() => void>} */ ([]),
+    cleanups: /** @type {Array<() => void>} */ ([]),
     mounted: false, disposed: false,
     _parentCtx: componentStack[componentStack.length - 1] || null,
     _errorBoundary: handleError,
@@ -719,11 +723,12 @@ function createErrorBoundary(vnode, parent) {
     componentStack.push(boundaryCtx);
 
     // Remove old content between comment boundaries
-    if (startComment.parentNode) {
+    const openParent = startComment.parentNode;
+    if (openParent) {
       while (startComment.nextSibling && startComment.nextSibling !== endComment) {
         const old = startComment.nextSibling;
         disposeTree(old);
-        old.parentNode.removeChild(old);
+        openParent.removeChild(old);
       }
     }
 
@@ -767,7 +772,9 @@ function createSuspenseBoundary(vnode, parent) {
   const endComment = document.createComment('sb:end');
 
   const boundaryCtx = {
-    hooks: [], hookIndex: 0, effects: [], cleanups: [],
+    hooks: /** @type {any[]} */ ([]), hookIndex: 0,
+    effects: /** @type {Array<() => void>} */ ([]),
+    cleanups: /** @type {Array<() => void>} */ ([]),
     mounted: false, disposed: false,
     _parentCtx: componentStack[componentStack.length - 1] || null,
     _suspenseBoundary: boundary,
@@ -795,11 +802,12 @@ function createSuspenseBoundary(vnode, parent) {
     componentStack.push(boundaryCtx);
 
     // Remove old content between comment boundaries
-    if (startComment.parentNode) {
+    const openParent = startComment.parentNode;
+    if (openParent) {
       while (startComment.nextSibling && startComment.nextSibling !== endComment) {
         const old = startComment.nextSibling;
         disposeTree(old);
-        old.parentNode.removeChild(old);
+        openParent.removeChild(old);
       }
     }
 
@@ -830,7 +838,7 @@ function createSuspenseBoundary(vnode, parent) {
 }
 
 // Portal component handler
-function createPortalDOM(vnode, parent) {
+function createPortalDOM(vnode, _parent) {
   const { container } = vnode.props;
   const children = vnode.children;
 
@@ -840,7 +848,9 @@ function createPortalDOM(vnode, parent) {
   }
 
   const portalCtx = {
-    hooks: [], hookIndex: 0, effects: [], cleanups: [],
+    hooks: /** @type {any[]} */ ([]), hookIndex: 0,
+    effects: /** @type {Array<() => void>} */ ([]),
+    cleanups: /** @type {Array<() => void>} */ ([]),
     mounted: false, disposed: false,
     _parentCtx: componentStack[componentStack.length - 1] || null,
   };
@@ -942,7 +952,7 @@ function setProp(el, key, value, isSvg) {
   if (typeof value === 'function' && !_isEventProp(key) && key !== 'ref') {
     if (!el._propEffects) el._propEffects = {};
     if (el._propEffects[key]) {
-      try { el._propEffects[key](); } catch (e) { /* already disposed */ }
+      try { el._propEffects[key](); } catch { /* already disposed */ }
     }
     el._propEffects[key] = effect(() => {
       const resolved = value();
@@ -1056,7 +1066,7 @@ function setProp(el, key, value, isSvg) {
   // reset first so removeAttribute() clears both the attribute and the property.
   if (value == null) {
     if (key in el) {
-      try { el[key] = ''; } catch (e) { /* read-only reflected prop */ }
+      try { el[key] = ''; } catch { /* read-only reflected prop */ }
     }
     el.removeAttribute(key);
     return;

package/src/errors.js

@@ -157,17 +157,322 @@ 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.
 
 export class WhatError extends Error {
-  constructor({ code, message, suggestion, file, line, component, signal, effect }) {
+  // codeExample carries the bad/good pair from the error's ERROR_CODES entry.
+  // Every entry above already had one; the class simply dropped it on the
+  // floor, so the field the docs promise on the serialized error was never
+  // 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';
     this.code = code;
     this.suggestion = suggestion;
+    this.codeExample = codeExample;
     this.file = file;
     this.line = line;
     this.component = component;
@@ -180,6 +485,7 @@ export class WhatError extends Error {
       code: this.code,
       message: this.message,
       suggestion: this.suggestion,
+      codeExample: this.codeExample,
       file: this.file,
       line: this.line,
       component: this.component,
@@ -214,6 +520,9 @@ export function createWhatError(errorCode, context = {}) {
     code: def.code,
     message,
     suggestion: def.suggestion,
+    // Verbatim from the definition: codeExample is a worked bad/good pair, not
+    // a template, so there is nothing in it to interpolate.
+    codeExample: def.codeExample,
     file: context.file,
     line: context.line,
     component: context.component,
@@ -254,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);