what-core 0.5.6 → 0.6.0

package/src/errors.js

@@ -0,0 +1,253 @@
+// What Framework - Structured Error System
+// Agent-first error reporting with actionable codes, suggestions, and JSON output.
+// Every error tells an AI agent exactly what went wrong and how to fix it.
+
+import { __DEV__ } from './reactive.js';
+
+// --- Error Codes ---
+// Each code maps to a specific, well-documented mistake pattern.
+
+export const ERROR_CODES = {
+  INFINITE_EFFECT: {
+    code: 'ERR_INFINITE_EFFECT',
+    severity: 'error',
+    template: 'Effect "{{effectName}}" exceeded 25 flush iterations — likely an infinite loop.',
+    suggestion: 'An effect is writing to a signal it also reads, creating a cycle. Use untrack() to read the signal without subscribing, or restructure so the write and read are in separate effects.',
+    codeExample: `// Bad — reads and writes count, creating a cycle:
+effect(() => { count(count() + 1); });
+
+// Good — use untrack() so the read doesn't subscribe:
+effect(() => { count(untrack(count) + 1); });
+
+// Better — split into separate logic:
+const doubled = computed(() => count() * 2);`,
+  },
+
+  MISSING_SIGNAL_READ: {
+    code: 'ERR_MISSING_SIGNAL_READ',
+    severity: 'warning',
+    template: 'Signal "{{signalName}}" used without calling () — renders as "[Function]" instead of its value.',
+    suggestion: 'Signals are functions. Call them to read: count() not count. In JSX: {count()} not {count}.',
+    codeExample: `// Bad — signal reference, not value:
+<span>{count}</span>       // renders "[Function]"
+
+// Good — call the signal:
+<span>{count()}</span>     // renders the actual value`,
+  },
+
+  HYDRATION_MISMATCH: {
+    code: 'ERR_HYDRATION_MISMATCH',
+    severity: 'error',
+    template: 'Hydration mismatch in component "{{component}}": server rendered "{{serverHTML}}" but client expects "{{clientHTML}}".',
+    suggestion: 'Ensure server and client render identical initial HTML. Avoid reading browser-only APIs (window, localStorage) during the initial render. Use onMount() for client-only logic.',
+    codeExample: `// Bad — different on server vs client:
+function App() {
+  return <p>{window.innerWidth}</p>;
+}
+
+// Good — use onMount for client-only values:
+function App() {
+  const width = signal(0);
+  onMount(() => width(window.innerWidth));
+  return <p>{width()}</p>;
+}`,
+  },
+
+  ORPHAN_EFFECT: {
+    code: 'ERR_ORPHAN_EFFECT',
+    severity: 'warning',
+    template: 'Effect "{{effectName}}" was created outside a reactive root — it will never be cleaned up.',
+    suggestion: 'Wrap effect creation in createRoot() or create effects inside component functions where they are automatically tracked.',
+    codeExample: `// Bad — orphaned, leaks memory:
+effect(() => console.log(count()));
+
+// Good — inside a root with cleanup:
+createRoot(dispose => {
+  effect(() => console.log(count()));
+  // later: dispose() cleans up
+});`,
+  },
+
+  SIGNAL_WRITE_IN_RENDER: {
+    code: 'ERR_SIGNAL_WRITE_IN_RENDER',
+    severity: 'error',
+    template: 'Signal "{{signalName}}" written during render of component "{{component}}". This triggers re-execution.',
+    suggestion: 'Move signal writes into event handlers, effects, or onMount(). The component body should only read signals, not write them.',
+    codeExample: `// Bad — write during render:
+function Counter() {
+  count(count() + 1);  // triggers infinite loop
+  return <span>{count()}</span>;
+}
+
+// Good — write in event handler:
+function Counter() {
+  return <button onclick={() => count(c => c + 1)}>{count()}</button>;
+}`,
+  },
+
+  MISSING_CLEANUP: {
+    code: 'ERR_MISSING_CLEANUP',
+    severity: 'warning',
+    template: 'Effect sets up "{{resource}}" but does not return a cleanup function.',
+    suggestion: 'Effects that add event listeners, set timers, or open connections should return a cleanup function to prevent memory leaks.',
+    codeExample: `// Bad — no cleanup:
+effect(() => {
+  window.addEventListener('resize', handler);
+});
+
+// Good — return cleanup:
+effect(() => {
+  window.addEventListener('resize', handler);
+  return () => window.removeEventListener('resize', handler);
+});`,
+  },
+
+  UNSAFE_INNERHTML: {
+    code: 'ERR_UNSAFE_INNERHTML',
+    severity: 'warning',
+    template: 'innerHTML set on element without using the __html safety marker.',
+    suggestion: 'Use the html tagged template literal or pass { __html: content } to mark innerHTML as intentional and reviewed.',
+    codeExample: `// Bad — raw innerHTML (XSS risk):
+<div innerHTML={userInput} />
+
+// Good — explicit opt-in:
+<div innerHTML={{ __html: sanitizedContent }} />
+
+// Better — use the html template literal:
+html\`<div>\${sanitizedContent}</div>\``,
+  },
+
+  MISSING_KEY: {
+    code: 'ERR_MISSING_KEY',
+    severity: 'warning',
+    template: 'List rendered without key prop in component "{{component}}". Items may re-order incorrectly.',
+    suggestion: 'Add a unique key prop to each item in a list. Use a stable identifier (like an ID), not the array index.',
+    codeExample: `// Bad — no key:
+<For each={items()}>{item => <li>{item.name}</li>}</For>
+
+// Good — stable key:
+<For each={items()}>{item => <li key={item.id}>{item.name}</li>}</For>`,
+  },
+};
+
+// --- WhatError ---
+// Structured error class with full context for agent consumption.
+
+export class WhatError extends Error {
+  constructor({ code, message, suggestion, file, line, component, signal, effect }) {
+    super(message);
+    this.name = 'WhatError';
+    this.code = code;
+    this.suggestion = suggestion;
+    this.file = file;
+    this.line = line;
+    this.component = component;
+    this.signal = signal;
+    this.effect = effect;
+  }
+
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      suggestion: this.suggestion,
+      file: this.file,
+      line: this.line,
+      component: this.component,
+      signal: this.signal,
+      effect: this.effect,
+    };
+  }
+}
+
+// --- Error Factory ---
+// Create WhatError instances from error codes with template interpolation.
+
+export function createWhatError(errorCode, context = {}) {
+  const def = typeof errorCode === 'string' ? ERROR_CODES[errorCode] : errorCode;
+  if (!def) {
+    return new WhatError({
+      code: 'ERR_UNKNOWN',
+      message: `Unknown error: ${errorCode}`,
+      suggestion: 'Check the error code and try again.',
+    });
+  }
+
+  // Interpolate template with context values
+  let message = def.template;
+  for (const [key, val] of Object.entries(context)) {
+    message = message.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), String(val));
+  }
+  // Clean up any unreplaced placeholders
+  message = message.replace(/\{\{[^}]+\}\}/g, '(unknown)');
+
+  return new WhatError({
+    code: def.code,
+    message,
+    suggestion: def.suggestion,
+    file: context.file,
+    line: context.line,
+    component: context.component,
+    signal: context.signal || context.signalName,
+    effect: context.effect || context.effectName,
+  });
+}
+
+// --- Error Collector ---
+// Dev-mode error accumulator for agent retrieval.
+
+let collectedErrors = [];
+const MAX_COLLECTED = 200;
+
+export function collectError(whatError) {
+  if (!__DEV__) return;
+  collectedErrors.push({
+    ...whatError.toJSON(),
+    timestamp: Date.now(),
+  });
+  if (collectedErrors.length > MAX_COLLECTED) {
+    collectedErrors = collectedErrors.slice(-MAX_COLLECTED);
+  }
+}
+
+export function getCollectedErrors(since) {
+  if (since) return collectedErrors.filter(e => e.timestamp > since);
+  return collectedErrors.slice();
+}
+
+export function clearCollectedErrors() {
+  collectedErrors = [];
+}
+
+// --- Error Classification ---
+// Classify a raw Error into a structured WhatError if possible.
+
+export function classifyError(err, context = {}) {
+  const msg = err?.message || String(err);
+
+  // Infinite effect loop
+  if (msg.includes('infinite effect loop') || msg.includes('25 iterations')) {
+    return createWhatError('INFINITE_EFFECT', context);
+  }
+
+  // Hydration mismatch
+  if (msg.includes('hydration') || msg.includes('Hydration')) {
+    return createWhatError('HYDRATION_MISMATCH', context);
+  }
+
+  // Signal write in computed
+  if (msg.includes('Signal.set() called inside a computed')) {
+    return createWhatError('SIGNAL_WRITE_IN_RENDER', {
+      ...context,
+      signalName: msg.match(/signal: (\w+)/)?.[1] || context.signalName,
+    });
+  }
+
+  // Fallback — return a generic WhatError with the original message
+  return new WhatError({
+    code: 'ERR_RUNTIME',
+    message: msg,
+    suggestion: 'Check the stack trace and component context for more details.',
+    ...context,
+  });
+}

package/src/guardrails.js

@@ -0,0 +1,224 @@
+// What Framework - Agent Guardrails
+// Dev-mode runtime checks that catch common mistakes BEFORE they become bugs.
+// Designed for AI agents: structured warnings with fix suggestions.
+
+import { __DEV__ } from './reactive.js';
+import { createWhatError, collectError } from './errors.js';
+
+// --- Guardrail Registry ---
+// Each guardrail can be enabled/disabled independently.
+
+const guardrails = {
+  signalReadDetection: true,
+  effectCycleDetection: true,
+  componentNaming: true,
+  importValidation: true,
+};
+
+export function configureGuardrails(overrides) {
+  Object.assign(guardrails, overrides);
+}
+
+export function getGuardrailConfig() {
+  return { ...guardrails };
+}
+
+// --- Guardrail 1: Signal Read Detection ---
+// Detect when a signal function reference is used where its value was intended.
+// This catches the pattern: <span>{count}</span> (should be count())
+//
+// At runtime, we can detect this when a signal is coerced to string (via toString/valueOf)
+// and warn that it should be called.
+
+export function installSignalReadGuardrail(signalFn, debugName) {
+  if (!__DEV__ || !guardrails.signalReadDetection) return signalFn;
+
+  // Override toString to catch template literal coercion
+  const originalToString = signalFn.toString;
+  signalFn.toString = function () {
+    const err = createWhatError('MISSING_SIGNAL_READ', {
+      signalName: debugName || '(unnamed)',
+    });
+    console.warn(`[what] ${err.message}\n  Suggestion: ${err.suggestion}`);
+    collectError(err);
+    // Still return the value so the app doesn't crash
+    return String(signalFn());
+  };
+
+  // Override valueOf for numeric coercion contexts
+  signalFn.valueOf = function () {
+    const err = createWhatError('MISSING_SIGNAL_READ', {
+      signalName: debugName || '(unnamed)',
+    });
+    console.warn(`[what] ${err.message}\n  Suggestion: ${err.suggestion}`);
+    collectError(err);
+    return signalFn();
+  };
+
+  return signalFn;
+}
+
+// --- Guardrail 2: Enhanced Effect Cycle Detection ---
+// Track which signals an effect reads AND writes.
+// If an effect writes to a signal it reads, warn about the specific cycle.
+
+const effectWriteTracking = new WeakMap(); // effect -> Set of signal debug names
+
+export function trackEffectSignalWrite(effectRef, signalDebugName) {
+  if (!__DEV__ || !guardrails.effectCycleDetection) return;
+
+  if (!effectWriteTracking.has(effectRef)) {
+    effectWriteTracking.set(effectRef, new Set());
+  }
+  effectWriteTracking.get(effectRef).add(signalDebugName);
+}
+
+export function checkEffectCycle(effectRef, readSignals) {
+  if (!__DEV__ || !guardrails.effectCycleDetection) return null;
+
+  const writes = effectWriteTracking.get(effectRef);
+  if (!writes || writes.size === 0) return null;
+
+  const overlapping = [];
+  for (const sigName of readSignals) {
+    if (writes.has(sigName)) {
+      overlapping.push(sigName);
+    }
+  }
+
+  if (overlapping.length > 0) {
+    const err = createWhatError('INFINITE_EFFECT', {
+      effectName: effectRef.fn?.name || '(anonymous)',
+      signalName: overlapping.join(', '),
+    });
+    collectError(err);
+    return err;
+  }
+
+  return null;
+}
+
+// --- Guardrail 3: Component Naming ---
+// Warn if a component function is not PascalCase.
+
+export function checkComponentName(name) {
+  if (!__DEV__ || !guardrails.componentNaming) return null;
+  if (!name) return null;
+
+  // PascalCase: starts with uppercase letter
+  if (/^[A-Z]/.test(name)) return null;
+
+  const suggestion = `Component "${name}" should use PascalCase (e.g., "${capitalize(name)}"). ` +
+    'PascalCase distinguishes components from HTML elements in JSX and is required by the What Framework compiler.';
+
+  console.warn(`[what] ${suggestion}`);
+  return { code: 'WARN_COMPONENT_NAMING', name, suggestion };
+}
+
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+// --- Guardrail 4: Import Validation ---
+// Verify that all named imports from 'what-framework' are valid exports.
+
+const VALID_EXPORTS = new Set([
+  // Reactive primitives
+  'signal', 'computed', 'effect', 'signalMemo', 'batch', 'untrack', 'flushSync',
+  'createRoot', 'getOwner', 'runWithOwner', 'onRootCleanup', '__setDevToolsHooks',
+  // Rendering
+  'template', '_template', 'svgTemplate', 'insert', 'mapArray', 'spread',
+  'setProp', 'delegateEvents', 'on', 'classList', 'hydrate', 'isHydrating',
+  '_$createComponent',
+  // JSX
+  'h', 'Fragment', 'html',
+  // DOM
+  'mount',
+  // Hooks
+  'useState', 'useSignal', 'useComputed', 'useEffect', 'useMemo', 'useCallback',
+  'useRef', 'useContext', 'useReducer', 'createContext', 'onMount', 'onCleanup',
+  'createResource',
+  // Components
+  'memo', 'lazy', 'Suspense', 'ErrorBoundary', 'Show', 'For', 'Switch', 'Match', 'Island',
+  // Store
+  'createStore', 'derived', 'storeComputed', 'atom',
+  // Head
+  'Head', 'clearHead',
+  // Utilities
+  'each', 'cls', 'style', 'debounce', 'throttle', 'useMediaQuery',
+  'useLocalStorage', 'useClickOutside', 'Portal', 'transition',
+  // Scheduler
+  'scheduleRead', 'scheduleWrite', 'flushScheduler', 'measure', 'mutate',
+  'useScheduledEffect', 'nextFrame', 'raf', 'onResize', 'onIntersect', 'smoothScrollTo',
+  // Animation
+  'spring', 'tween', 'easings', 'useTransition', 'useGesture', 'useAnimatedValue',
+  'createTransitionClasses', 'cssTransition',
+  // Accessibility
+  'useFocus', 'useFocusRestore', 'useFocusTrap', 'FocusTrap', 'announce',
+  'announceAssertive', 'SkipLink', 'useAriaExpanded', 'useAriaSelected',
+  'useAriaChecked', 'useRovingTabIndex', 'VisuallyHidden', 'LiveRegion',
+  'useId', 'useIds', 'useDescribedBy', 'useLabelledBy', 'Keys', 'onKey', 'onKeys',
+  // Skeleton
+  'Skeleton', 'SkeletonText', 'SkeletonAvatar', 'SkeletonCard', 'SkeletonTable',
+  'IslandSkeleton', 'useSkeleton', 'Placeholder', 'LoadingDots', 'Spinner',
+  // Data fetching
+  'useFetch', 'useSWR', 'useQuery', 'useInfiniteQuery', 'invalidateQueries',
+  'prefetchQuery', 'setQueryData', 'getQueryData', 'clearCache', '__getCacheSnapshot',
+  // Form
+  'useForm', 'useField', 'rules', 'simpleResolver', 'zodResolver', 'yupResolver',
+  'Input', 'Textarea', 'Select', 'Checkbox', 'Radio', 'ErrorMessage',
+]);
+
+export function validateImports(importNames) {
+  if (!__DEV__ || !guardrails.importValidation) return [];
+
+  const invalid = [];
+  for (const name of importNames) {
+    if (!VALID_EXPORTS.has(name)) {
+      invalid.push({
+        name,
+        message: `"${name}" is not a valid export from what-framework.`,
+        suggestion: `Check the API reference. Did you mean: ${findClosest(name)}?`,
+      });
+    }
+  }
+  return invalid;
+}
+
+// Simple Levenshtein-based closest match
+function findClosest(input) {
+  const lower = input.toLowerCase();
+  let best = null;
+  let bestDist = Infinity;
+
+  for (const name of VALID_EXPORTS) {
+    const dist = levenshtein(lower, name.toLowerCase());
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = name;
+    }
+  }
+
+  return bestDist <= 3 ? best : '(no close match found)';
+}
+
+function levenshtein(a, b) {
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+
+  const matrix = [];
+  for (let i = 0; i <= b.length; i++) matrix[i] = [i];
+  for (let j = 0; j <= a.length; j++) matrix[0][j] = j;
+
+  for (let i = 1; i <= b.length; i++) {
+    for (let j = 1; j <= a.length; j++) {
+      const cost = b[i - 1] === a[j - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(
+        matrix[i - 1][j] + 1,
+        matrix[i][j - 1] + 1,
+        matrix[i - 1][j - 1] + cost,
+      );
+    }
+  }
+  return matrix[b.length][a.length];
+}

package/src/h.js

@@ -1,11 +1,11 @@
-// What Framework - Hyperscript / VDOM
-// Minimal virtual DOM nodes. No classes, no fibers, just plain objects.
+// What Framework - Element Descriptors
+// Minimal element descriptor objects. No classes, no fibers, just plain objects.
 
 // h(tag, props, ...children) -> VNode
 // h(Component, props, ...children) -> VNode
 // VNode = { tag, props, children, key }
 
-const EMPTY_OBJ = {};
+const EMPTY_OBJ = Object.create(null);
 const EMPTY_ARR = [];
 
 export function h(tag, props, ...children) {