what-core 0.11.7 → 0.11.8

package/index.d.ts

@@ -24,7 +24,7 @@ export interface Computed<T> {
   _signal: true;
 }
 
-export function signal<T>(initial: T): Signal<T>;
+export function signal<T>(initial: T, debugName?: string): Signal<T>;
 export function computed<T>(fn: () => T): Computed<T>;
 export function effect(fn: () => void | (() => void), opts?: { stable?: boolean }): () => void;
 export function signalMemo<T>(fn: () => T): Computed<T>;
@@ -33,12 +33,36 @@ export function untrack<T>(fn: () => T): T;
 export function flushSync(): void;
 export function createRoot<T>(fn: (dispose: () => void) => T): T;
 
+/** Opaque ownership scope handle. Pair with runWithOwner() for async work. */
+export interface Owner {
+  disposals: Array<() => void>;
+}
+
+export function getOwner(): Owner | null;
+export function runWithOwner<T>(owner: Owner | null, fn: () => T): T;
+/** Register a cleanup with the current owner/root (root-level onCleanup). */
+export function onRootCleanup(fn: () => void): void;
+
 // --- Virtual DOM ---
 
 export type PrimitiveChild = string | number | boolean | null | undefined;
 export type VNodeChild = PrimitiveChild | VNode | (() => VNodeChild) | VNodeChild[];
 
-export type Component<P = {}> = (props: P & { children?: VNodeChild }) => VNodeChild;
+/** A component may legitimately render nothing, so `null` is part of the contract. */
+export type Component<P = {}> = ((props: P & { children?: VNodeChild }) => VNode | null) & {
+  /**
+   * Opt out of realizing compiled children before the component runs.
+   *
+   * A component that establishes a scope its children depend on (a context
+   * provider, an error or suspense boundary) receives `props.children` as a
+   * zero-argument factory instead of built nodes, and the runtime realizes it
+   * once that scope exists. `ErrorBoundary`, `Suspense` and `Context.Provider`
+   * set this themselves, and the compiler keeps a component that only forwards
+   * its children lazy, so this is only needed by a component that both
+   * inspects its children and forwards them into a boundary or a provider.
+   */
+  _deferChildren?: boolean;
+};
 
 export interface VNode<P = Record<string, any>> {
   tag: string | Component<P>;
@@ -54,15 +78,20 @@ export function h<P extends Record<string, any>>(
   ...children: VNodeChild[]
 ): VNode<P>;
 
-export function Fragment(props: { children?: VNodeChild }): VNodeChild;
+export function Fragment(props: { children?: VNodeChild }): VNode;
 export function html(strings: TemplateStringsArray, ...values: any[]): VNode | VNode[];
 
 // --- DOM ---
 
 export function mount(vnode: VNodeChild, container: string | Element): () => void;
 
+/** Attach reactive bindings to server-rendered DOM instead of creating it. */
+export function hydrate(vnode: VNodeChild, container: Element): Node | null;
+export function isHydrating(): boolean;
+
 // Fine-grained rendering primitives
 export function template(html: string): () => Element;
+export function svgTemplate(html: string): () => Element;
 export function insert(parent: Node, child: any, marker?: Node | null): any;
 export function mapArray<T>(
   source: () => T[],
@@ -132,18 +161,18 @@ export function Show(props: {
   when: boolean | (() => boolean);
   fallback?: VNodeChild;
   children?: VNodeChild;
-}): VNodeChild;
+}): VNode;
 
 export function For<T>(props: {
   each: T[] | (() => T[]);
   fallback?: VNodeChild;
   children: ((item: T, index: number) => VNodeChild) | VNodeChild;
-}): VNodeChild;
+}): VNode;
 
 export function Switch(props: {
   fallback?: VNodeChild;
   children?: VNodeChild;
-}): VNodeChild;
+}): VNode;
 
 export function Match(props: {
   when: boolean | (() => boolean);
@@ -198,6 +227,37 @@ export function Head(props: {
 }): null;
 export function clearHead(): void;
 
+/** Per-render head accumulator used by the SSR renderer. */
+export interface HeadSink {
+  title: string | null;
+  metas: Map<string, Record<string, string>>;
+  links: Map<string, Record<string, string>>;
+}
+
+export function beginHeadCollection(): HeadSink;
+export function endHeadCollection(sink: HeadSink | null): string;
+
+// --- Loader Data ---
+
+export function useLoaderData<T = any>(): T | undefined;
+export function getLoaderData<T = any>(): T | undefined;
+export function getResource<T = any>(key: string): T | undefined;
+
+// --- Server Context ---
+
+export interface ServerContext {
+  loaderData?: any;
+  head?: HeadSink;
+  resources?: Record<string, any>;
+  [key: string]: any;
+}
+
+/** The active render context, or null on the client / outside a render. */
+export function getServerContext(): ServerContext | null;
+/** Set the active context and return the previous one so callers can restore it. */
+export function setServerContext(ctx: ServerContext | null): ServerContext | null;
+export function runWithServerContext<T>(ctx: ServerContext, fn: () => T): T;
+
 // --- Scheduler ---
 
 export function scheduleRead(fn: () => void): () => void;
@@ -334,17 +394,17 @@ export function onKeys(keys: string[], handler: (e: KeyboardEvent) => void): (e:
 
 // --- Skeleton ---
 
-export function Skeleton(props?: Record<string, any>): VNodeChild;
+export function Skeleton(props?: Record<string, any>): VNode;
 export function SkeletonText(props?: Record<string, any>): VNode;
-export function SkeletonAvatar(props?: Record<string, any>): VNodeChild;
+export function SkeletonAvatar(props?: Record<string, any>): VNode;
 export function SkeletonCard(props?: Record<string, any>): VNode;
 export function SkeletonTable(props?: Record<string, any>): VNode;
-export function IslandSkeleton(props?: Record<string, any>): VNodeChild;
+export function IslandSkeleton(props?: Record<string, any>): VNode;
 export function useSkeleton<T>(asyncFn: () => Promise<T> | T, deps?: unknown[]): {
   isLoading: () => boolean;
   data: () => T | null;
   error: () => any;
-  Skeleton: (props?: Record<string, any>) => VNodeChild;
+  Skeleton: (props?: Record<string, any>) => VNode;
 };
 export function Placeholder(props?: Record<string, any>): VNode;
 export function LoadingDots(props?: Record<string, any>): VNode;
@@ -504,4 +564,85 @@ export function ErrorMessage(props: {
   formState?: FormState;
   errors?: Record<string, FieldError> | (() => Record<string, FieldError>);
   render?: (args: { message?: string; type?: string }) => VNodeChild;
-}): VNodeChild;
+}): VNode;
+
+// --- Structured Errors ---
+
+export interface ErrorCodeDefinition {
+  code: string;
+  severity: 'error' | 'warning';
+  template: string;
+  suggestion: string;
+  codeExample?: string;
+}
+
+export const ERROR_CODES: Record<string, ErrorCodeDefinition>;
+
+export interface WhatErrorJSON {
+  code: string;
+  message: string;
+  suggestion?: string;
+  file?: string;
+  line?: number;
+  component?: string;
+  signal?: string;
+  effect?: string;
+}
+
+export class WhatError extends Error {
+  constructor(init: {
+    code: string;
+    message: string;
+    suggestion?: string;
+    file?: string;
+    line?: number;
+    component?: string;
+    signal?: string;
+    effect?: string;
+  });
+  code: string;
+  suggestion?: string;
+  file?: string;
+  line?: number;
+  component?: string;
+  signal?: string;
+  effect?: string;
+  toJSON(): WhatErrorJSON;
+}
+
+export function createWhatError(
+  errorCode: string | ErrorCodeDefinition,
+  context?: Record<string, any>,
+): WhatError;
+export function classifyError(err: unknown, context?: Record<string, any>): WhatError;
+export function collectError(error: WhatError): void;
+export function getCollectedErrors(since?: number): Array<WhatErrorJSON & { timestamp: number }>;
+export function clearCollectedErrors(): void;
+
+// --- Guardrails ---
+
+export interface GuardrailConfig {
+  signalReadDetection: boolean;
+  componentNaming: boolean;
+  importValidation: boolean;
+}
+
+export function configureGuardrails(overrides: Partial<GuardrailConfig>): void;
+export function getGuardrailConfig(): GuardrailConfig;
+export function installSignalReadGuardrail<T>(signalFn: T, debugName?: string): T;
+
+// --- Agent Context ---
+
+export interface HealthReport {
+  effectCycleRisk: boolean;
+  orphanEffects: number;
+  signalLeaks: number;
+  memoryPressure: 'low' | 'medium' | 'high';
+  recentErrorCount: number;
+  totalSignals: number;
+  totalComponents: number;
+}
+
+export function getHealth(): HealthReport;
+/** Expose globalThis.__WHAT_AGENT__ for agent tooling (dev mode only). */
+export function installAgentContext(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "what-core",
-  "version": "0.11.7",
+  "version": "0.11.8",
   "description": "What Framework - Signal-based UI framework built for AI agents",
   "type": "module",
   "main": "src/index.js",

package/src/agent-context.js

@@ -8,7 +8,7 @@ import { getCollectedErrors } from './errors.js';
 // --- Version ---
 // Keep in sync with packages/core/package.json (checked by
 // core/test/guardrails.test.js so it can't silently go stale again).
-const VERSION = '0.11.7';
+const VERSION = '0.11.8';
 
 // --- Component Registry ---
 // Tracks mounted components for agent inspection.

package/src/components.js

@@ -81,19 +81,31 @@ export function lazy(loader) {
 export function Suspense({ fallback, children }) {
   const loading = signal(false);
   const pendingPromises = new Set();
+  let failed = false;
 
   // Suspense boundary marker
   const boundary = {
     _suspense: true,
     onSuspend(promise) {
+      if (failed) return;
       loading.set(true);
       pendingPromises.add(promise);
-      promise.finally(() => {
-        pendingPromises.delete(promise);
-        if (pendingPromises.size === 0) {
-          loading.set(false);
-        }
-      });
+      // Rejection is handled separately from fulfilment. Clearing the fallback
+      // on a rejection re-renders the child, which suspends on the same
+      // rejected thenable again, forever. Latch the failure and stay put.
+      promise.then(
+        () => {
+          pendingPromises.delete(promise);
+          if (pendingPromises.size === 0) {
+            loading.set(false);
+          }
+        },
+        (err) => {
+          failed = true;
+          pendingPromises.delete(promise);
+          console.error('[what] Suspense: a suspended child rejected:', err);
+        },
+      );
     },
   };
 
@@ -105,6 +117,10 @@ export function Suspense({ fallback, children }) {
   };
 }
 
+// The boundary context only exists once createSuspenseBoundary runs, so
+// compiled children must not be built during this call. See createComponent.
+Suspense._deferChildren = true;
+
 // --- ErrorBoundary ---
 // Catch errors in children and show fallback.
 // Uses a signal to track error state so it works with reactive rendering.
@@ -135,6 +151,10 @@ export function ErrorBoundary({ fallback, children, onError }) {
   };
 }
 
+// The boundary context only exists once createErrorBoundary runs, so compiled
+// children must not be built during this call. See createComponent.
+ErrorBoundary._deferChildren = true;
+
 // Helper to report error to nearest boundary
 // Walks the component context tree (not a runtime stack) so async errors are caught
 export function reportError(error, startCtx) {
@@ -216,33 +236,38 @@ export function For({ each, fallback = null, children }) {
 // Multi-condition rendering (like switch statement).
 
 export function Switch({ fallback = null, children }) {
-  // The Match children (marker vnodes) are static — resolve them once. The
-  // match loop, which reads each Match's reactive `when`, must run inside a
-  // reactive thunk (see Show/For above): components run once, so evaluating
-  // `when()` in the body here would snapshot the active arm a single time and
-  // `<Switch>`/`<Match when={() => sig()}>` would render once and never update.
-  // Switch/Match are NOT lowered by the fine-grained compiler, so this runtime
-  // path is the ONLY path — the thunk is what makes them reactive at all.
+  // The Match children are static, so resolve them once. The match loop, which
+  // reads each Match's reactive `when`, must run inside a reactive thunk (see
+  // Show/For above): components run once, so evaluating `when()` in the body
+  // here would snapshot the active arm a single time and `<Switch>`/`<Match
+  // when={() => sig()}>` would render once and never update.
+  // This is the runtime path, for h() and the automatic JSX runtime, where a
+  // <Match> arrives as an unexecuted marker vnode. The fine-grained compiler
+  // lowers <Switch> to the same conditional thunk and never reaches here; a
+  // <Switch> it cannot lower is a build error rather than a call into this.
   const kids = Array.isArray(children) ? children : [children];
 
   return () => {
     for (const child of kids) {
       if (child && child.tag === Match) {
-        const condition = typeof child.props.when === 'function'
-          ? child.props.when()
-          : child.props.when;
-        if (condition) {
-          return child.children;
-        }
+        const when = child.props.when;
+        const condition = typeof when === 'function' ? when() : when;
+        if (condition) return child.children;
       }
     }
     return fallback;
   };
 }
 
-export function Match({ when, children }) {
-  // Match is just a marker component, Switch handles the logic
-  return { tag: Match, props: { when }, children, _vnode: true };
+export function Match(props) {
+  // Executed rather than left as a marker, which is what a lone compiled
+  // <Match> does. Returning a `{ tag: Match }` vnode here would send createDOM
+  // straight back into Match forever, so return a reactive thunk that renders
+  // the arm when it matches.
+  return () => {
+    const condition = typeof props.when === 'function' ? props.when() : props.when;
+    return condition ? props.children : null;
+  };
 }
 
 // --- Island ---