what-core 0.11.7 → 0.12.0

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,115 @@ 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;
+
+/** Warn when a component function is not PascalCase. Dev-mode only; returns null in production. */
+export function checkComponentName(name: string): GuardrailWarning | null;
+
+export interface GuardrailWarning {
+  code: string;
+  name: string;
+  suggestion: string;
+}
+
+export interface InvalidImport {
+  name: string;
+  message: string;
+  suggestion: string;
+}
+
+/** Report import names that are not valid exports of what-framework. Dev-mode only. */
+export function validateImports(importNames: readonly string[]): InvalidImport[];
+
+// --- Agent registries ---
+// The devtools bridge and MCP server read these to enumerate the live graph.
+// Registration is a no-op in production builds; the getters always return a copy.
+
+export function registerComponent(component: unknown): void;
+export function unregisterComponent(component: unknown): void;
+export function getMountedComponents(): unknown[];
+
+export function registerSignal(sig: unknown): void;
+export function unregisterSignal(sig: unknown): void;
+export function getActiveSignals(): unknown[];

package/jsx-dev-runtime.d.ts

@@ -1,9 +1,9 @@
 // What Framework — JSX dev-runtime type definitions.
 // Re-exports the runtime types (including the JSX namespace) and adds jsxDEV,
 // which the "react-jsxdev" transform emits in development builds.
-import type { VNode } from './index';
+import type { VNode } from './index.js';
 
-export * from './jsx-runtime';
+export * from './jsx-runtime.js';
 
 export function jsxDEV(
   type: any,

package/jsx-runtime.d.ts

@@ -11,9 +11,9 @@
 // documentation, while an index signature keeps arbitrary/custom attributes and
 // web-component tags valid (never false-flagging code the runtime accepts).
 
-import type { VNode, VNodeChild } from './index';
+import type { VNode, VNodeChild } from './index.js';
 
-export { Fragment } from './index';
+export { Fragment } from './index.js';
 
 /** A JSX attribute value in What may be static or a reactive `() => value` thunk. */
 export type Reactive<T> = T | (() => T);

package/package.json

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

package/render.d.ts

@@ -9,7 +9,8 @@ export {
   classList,
   effect,
   untrack,
-} from './index';
+} from './index.js';
+import type { VNodeChild } from './index.js';
 
 // Compiler-internal template alias — identical to template() but never
 // dev-warns. Compiled output imports this (SPRINT v0.11 C5).
@@ -28,3 +29,16 @@ export function setChecked(el: Element, value: any): void;
 // exported from the package index). Emitted by the compiler for branch
 // memoization of conditional JSX (SPRINT v0.11 C1).
 export function memo<T>(fn: () => T): (() => T) & { peek(): T };
+
+// --- Hydration ---
+// hydrate() adopts server-rendered DOM instead of recreating it: it walks the
+// existing nodes, attaches event handlers and reactive bindings in place, and
+// restarts the useId sequence so client ids reproduce the server's.
+export function hydrate(vnode: VNodeChild, container: Element): Node | Node[] | null;
+
+/** True while a hydration pass is walking existing DOM. */
+export function isHydrating(): boolean;
+
+// SVG counterpart to template(): elements are created in the SVG namespace, which
+// a plain innerHTML template cannot do.
+export function svgTemplate(html: string): () => Element;

package/src/a11y.js

@@ -4,6 +4,7 @@
 import { signal, effect } from './reactive.js';
 import { h } from './h.js';
 import { getCurrentComponent } from './dom.js';
+import { getServerContext } from './server-context.js';
 
 // --- Focus Management ---
 
@@ -401,17 +402,48 @@ export function LiveRegion({ children, priority = 'polite', atomic = true }) {
 // --- ID Generator ---
 // Generate unique IDs for ARIA attributes
 
+// The counter is render-scoped on the server and module-global on the client.
+//
+// A bare module-global counter is wrong on the server in two independent ways.
+// Ids drift between the SSR pass and hydration, which breaks exactly the
+// relationships useId exists to create (`for`/`id`, `aria-labelledby`,
+// `aria-describedby`), and concurrent requests interleave into each other's
+// sequence, so two visitors can be served HTML whose ids were allocated in the
+// order the event loop happened to run. Every framework in the cohort ships this
+// primitive as SSR-stable because that is the whole point of shipping it.
+//
+// getServerContext() is the render-scoped store the SSR keystone already
+// maintains (AsyncLocalStorage-backed in Node), so this is wiring rather than
+// new machinery, and it adds no public API.
 let idCounter = 0;
 
+function nextIdSuffix() {
+  const ctx = getServerContext();
+  if (ctx) {
+    ctx.idCounter = (ctx.idCounter || 0) + 1;
+    return ctx.idCounter;
+  }
+  return ++idCounter;
+}
+
+/**
+ * Reset the client-side counter. Called at the start of hydration so the client
+ * reproduces the server's id sequence instead of continuing past it.
+ * @internal
+ */
+export function __resetIdCounter() {
+  idCounter = 0;
+}
+
 export function useId(prefix = 'what') {
-  const id = `${prefix}-${++idCounter}`;
+  const id = `${prefix}-${nextIdSuffix()}`;
   return () => id;
 }
 
 export function useIds(count, prefix = 'what') {
   const ids = [];
   for (let i = 0; i < count; i++) {
-    ids.push(`${prefix}-${++idCounter}`);
+    ids.push(`${prefix}-${nextIdSuffix()}`);
   }
   return ids;
 }

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.12.0';
 
 // --- Component Registry ---
 // Tracks mounted components for agent inspection.