what-core 0.6.1 → 0.6.3

package/index.d.ts

@@ -24,15 +24,59 @@ export interface Computed<T> {
   _signal: true;
 }
 
-export function signal<T>(initial: T): Signal<T>;
+/**
+ * Create a reactive signal with an initial value.
+ * Read with `sig()`, write with `sig(newVal)` or `sig.set(newVal)`.
+ * @param initial - Initial value
+ * @param debugName - Optional name for devtools inspection
+ */
+export function signal<T>(initial: T, debugName?: string): Signal<T>;
+
+/**
+ * Create a derived (computed) signal. Lazy: only recomputes when a
+ * dependency changes AND the computed is read.
+ */
 export function computed<T>(fn: () => T): Computed<T>;
+
+/**
+ * Run a side-effect function that auto-tracks signal reads.
+ * Re-runs when any tracked signal changes.
+ * Return a cleanup function from `fn` to run before each re-execution.
+ * @returns Dispose function to stop the effect
+ */
 export function effect(fn: () => void | (() => void), opts?: { stable?: boolean }): () => void;
+
+/**
+ * Eager computed that only propagates when the value actually changes.
+ * Alias: `signalMemo` (exported as `memo` from reactive, renamed to avoid
+ * collision with component `memo`).
+ */
 export function signalMemo<T>(fn: () => T): Computed<T>;
+
+/** Group multiple signal writes; effects run once at the end. */
 export function batch<T>(fn: () => T): T;
+
+/** Read signals without subscribing to them. */
 export function untrack<T>(fn: () => T): T;
+
+/** Force all pending effects to run synchronously. Use sparingly. */
 export function flushSync(): void;
+
+/**
+ * Create an isolated reactive scope with ownership tree.
+ * All effects created inside are tracked and disposed together.
+ */
 export function createRoot<T>(fn: (dispose: () => void) => T): T;
 
+/** Get the current owner context (for advanced async patterns). */
+export function getOwner(): any;
+
+/** Run a function within a specific owner context. */
+export function runWithOwner<T>(owner: any, fn: () => T): T;
+
+/** Register a cleanup function with the current owner/root. */
+export function onRootCleanup(fn: () => void): void;
+
 // --- Virtual DOM ---
 
 export type PrimitiveChild = string | number | boolean | null | undefined;
@@ -62,8 +106,17 @@ export function html(strings: TemplateStringsArray, ...values: any[]): VNode | V
 export function mount(vnode: VNodeChild, container: string | Element): () => void;
 
 // Fine-grained rendering primitives
+
+/**
+ * @internal Compiler internal -- do NOT call directly in application code.
+ * Use JSX instead. The compiler transforms JSX into `_$template()` calls automatically.
+ * Direct use with untrusted input creates XSS vulnerabilities (innerHTML).
+ * @deprecated Use JSX. This export exists only for backward compatibility.
+ */
 export function template(html: string): () => Element;
+/** @internal Compiler internal -- inserts reactive children into DOM. Emitted by the compiler. */
 export function insert(parent: Node, child: any, marker?: Node | null): any;
+/** @internal Compiler internal -- keyed list reconciliation. Emitted by the compiler for `<For>`. */
 export function mapArray<T>(
   source: () => T[],
   mapFn: (item: T | Signal<T>, index: number) => Node,
@@ -163,6 +216,9 @@ export function Island(props: IslandProps): VNode;
 
 export type DerivedFn<T> = ((state: any) => T) & { _isDerived: true };
 export function derived<T>(fn: (state: any) => T): DerivedFn<T>;
+/**
+ * @deprecated Use derived(fn) instead. storeComputed remains as a runtime alias for backward compatibility.
+ */
 export function storeComputed<T>(fn: (state: any) => T): DerivedFn<T>;
 export type StoreDefinition = Record<string, any>;
 export type Store<T extends StoreDefinition> = T;
@@ -505,3 +561,122 @@ export function ErrorMessage(props: {
   errors?: Record<string, FieldError> | (() => Record<string, FieldError>);
   render?: (args: { message?: string; type?: string }) => VNodeChild;
 }): VNodeChild;
+
+// --- Structured Error System ---
+
+export interface ErrorCodeDefinition {
+  code: string;
+  severity: 'error' | 'warning';
+  template: string;
+  suggestion: string;
+  codeExample: string;
+}
+
+export const ERROR_CODES: {
+  INFINITE_EFFECT: ErrorCodeDefinition;
+  MISSING_SIGNAL_READ: ErrorCodeDefinition;
+  HYDRATION_MISMATCH: ErrorCodeDefinition;
+  ORPHAN_EFFECT: ErrorCodeDefinition;
+  SIGNAL_WRITE_IN_RENDER: ErrorCodeDefinition;
+  MISSING_CLEANUP: ErrorCodeDefinition;
+  UNSAFE_INNERHTML: ErrorCodeDefinition;
+  MISSING_KEY: ErrorCodeDefinition;
+};
+
+export class WhatError extends Error {
+  code: string;
+  suggestion?: string;
+  file?: string;
+  line?: number;
+  component?: string;
+  signal?: string;
+  effect?: string;
+  constructor(opts: {
+    code: string;
+    message: string;
+    suggestion?: string;
+    file?: string;
+    line?: number;
+    component?: string;
+    signal?: string;
+    effect?: string;
+  });
+  toJSON(): Record<string, any>;
+}
+
+export function createWhatError(
+  errorCode: string | ErrorCodeDefinition,
+  context?: Record<string, any>,
+): WhatError;
+
+export function classifyError(err: Error, context?: Record<string, any>): WhatError;
+export function collectError(whatError: WhatError): void;
+export function getCollectedErrors(since?: number): Array<Record<string, any>>;
+export function clearCollectedErrors(): void;
+
+// --- Agent Guardrails ---
+
+export interface GuardrailConfig {
+  signalReadDetection: boolean;
+  effectCycleDetection: boolean;
+  componentNaming: boolean;
+  importValidation: boolean;
+}
+
+export function configureGuardrails(overrides: Partial<GuardrailConfig>): void;
+export function getGuardrailConfig(): GuardrailConfig;
+export function installSignalReadGuardrail<T>(signalFn: Signal<T>, debugName?: string): Signal<T>;
+export function checkComponentName(name: string): { code: string; name: string; suggestion: string } | null;
+export function validateImports(importNames: string[]): Array<{ name: string; message: string; suggestion: string }>;
+
+// --- Agent Context ---
+
+export interface AgentHealthReport {
+  effectCycleRisk: boolean;
+  orphanEffects: number;
+  signalLeaks: number;
+  memoryPressure: 'low' | 'medium' | 'high';
+  recentErrorCount: number;
+  totalSignals: number;
+  totalComponents: number;
+}
+
+export function installAgentContext(): void;
+export function registerComponent(component: any): void;
+export function unregisterComponent(component: any): void;
+export function getMountedComponents(): any[];
+export function registerSignal(sig: Signal<any>): void;
+export function unregisterSignal(sig: Signal<any>): void;
+export function getActiveSignals(): Signal<any>[];
+export function getHealth(): AgentHealthReport;
+
+// --- Hydration ---
+
+/**
+ * Hydrate a vnode tree against existing server-rendered DOM in the container.
+ * Reuses existing DOM nodes instead of creating new ones. Attaches reactive
+ * bindings and event handlers to the server-rendered markup.
+ *
+ * In dev mode, logs warnings for every hydration mismatch (text, element,
+ * attribute). After hydration completes, logs a summary if mismatches occurred.
+ *
+ * @param vnode - The component tree (same tree used for SSR)
+ * @param container - The DOM element containing server-rendered HTML
+ * @returns The hydrated DOM node(s)
+ */
+export function hydrate(vnode: VNodeChild, container: Element): any;
+
+/** Returns true if currently inside a hydration pass. */
+export function isHydrating(): boolean;
+
+/**
+ * Returns the number of hydration mismatches from the most recent `hydrate()` call.
+ * Useful for testing and diagnostics.
+ */
+export function getHydrationMismatchCount(): number;
+
+// --- SVG template helper ---
+/**
+ * @internal Parse SVG content inside an SVG namespace container.
+ */
+export function svgTemplate(html: string): () => Element;