@jasonshimmy/custom-elements-runtime 2.5.1 → 2.5.5

package/dist/runtime/builtin-components.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Built-in utility components provided by the custom-elements runtime.
+ *
+ * These components are registered automatically when this module is imported.
+ * They are designed to be minimal, tree-shakeable, and zero-dependency.
+ *
+ * Included components:
+ * - `<cer-suspense>` — Shows a fallback while async work is pending
+ * - `<cer-error-boundary>` — Catches render errors and shows a fallback UI
+ * - `<cer-keep-alive>` — Preserves component state across DOM removal/re-insertion
+ */
+/**
+ * A built-in component that conditionally renders either the default slot
+ * content or the `fallback` slot content, controlled by the `pending` prop.
+ *
+ * Use the `pending` attribute/property to signal that async work is in
+ * progress; the component will swap to the `fallback` slot until `pending`
+ * becomes falsy.
+ *
+ * @example
+ * ```html
+ * <cer-suspense pending>
+ *   <!-- shown when pending=false -->
+ *   <my-async-content></my-async-content>
+ *
+ *   <!-- shown while pending=true -->
+ *   <div slot="fallback">Loading…</div>
+ * </cer-suspense>
+ * ```
+ *
+ * @example Programmatic usage
+ * ```ts
+ * component('my-data-loader', () => {
+ *   const pending = ref(true);
+ *   useOnConnected(async () => {
+ *     await fetchData();
+ *     pending.value = false;
+ *   });
+ *   return html`
+ *     <cer-suspense pending="${pending.value}">
+ *       <my-data-view></my-data-view>
+ *       <div slot="fallback">Loading data…</div>
+ *     </cer-suspense>
+ *   `;
+ * });
+ * ```
+ */
+export declare function registerSuspense(): void;
+/**
+ * A built-in component that catches errors thrown during child component
+ * rendering and displays a fallback UI instead of crashing the page.
+ *
+ * Errors are caught via the `useOnError` lifecycle hook. Once an error is
+ * caught the component switches to showing the `fallback` named slot (or a
+ * default "Something went wrong" message if no fallback slot is provided).
+ *
+ * Call the custom `reset()` method on the element to clear the error and
+ * attempt re-rendering the default slot.
+ *
+ * @example
+ * ```html
+ * <cer-error-boundary>
+ *   <my-risky-component></my-risky-component>
+ *
+ *   <div slot="fallback">
+ *     <p>Something went wrong. <button onclick="this.closest('cer-error-boundary').reset()">Retry</button></p>
+ *   </div>
+ * </cer-error-boundary>
+ * ```
+ */
+export declare function registerErrorBoundary(): void;
+/**
+ * Register all built-in components (`cer-suspense`, `cer-error-boundary`,
+ * `cer-keep-alive`).
+ * Safe to call multiple times — each registration is guarded by a
+ * `customElements.get()` check.
+ */
+export declare function registerBuiltinComponents(): void;

package/dist/runtime/component/element-class.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentConfig } from '../types';
+export declare function createElementClass<S extends object, C extends object, P extends object, T extends object = object>(tag: string, config: ComponentConfig<S, C, P, T>): CustomElementConstructor | {
+    new (): object;
+};

package/dist/runtime/component/factory.d.ts

@@ -0,0 +1,39 @@
+import type { VNode } from '../types';
+/**
+ * Streamlined functional component API with automatic reactive props and lifecycle hooks.
+ *
+ * @example
+ * ```ts
+ * // Simple component with no parameters
+ * component('simple-header', () => {
+ *   return html`<h1>Hello World</h1>`;
+ * });
+ *
+ * // With props using useProps() hook
+ * component('with-props', () => {
+ *   const { message } = useProps({ message: 'Hello' });
+ *   return html`<div>${message}</div>`;
+ * });
+ *
+ * // With props and lifecycle hooks
+ * component('my-switch', () => {
+ *   const { modelValue, label } = useProps({ modelValue: false, label: '' });
+ *   const emit = useEmit();
+ *
+ *   useOnConnected(() => console.log('Switch connected!'));
+ *   useOnDisconnected(() => console.log('Switch disconnected!'));
+ *
+ *   return html`
+ *     <label>
+ *       ${label}
+ *       <input
+ *         type="checkbox"
+ *         :checked="${modelValue}"
+ *         @change="${(e) => emit('update:modelValue', e.target.checked)}"
+ *       />
+ *     </label>
+ *   `;
+ * });
+ * ```
+ */
+export declare function component(tag: string, renderFn: () => VNode | VNode[] | Promise<VNode | VNode[]>): void;

package/dist/runtime/component/registry.d.ts

@@ -0,0 +1,16 @@
+import type { ComponentConfig } from '../types';
+/**
+ * @internal
+ * Runtime registry of component configs.
+ * NOTE: This is an internal implementation detail. Do not import from the
+ * published package in consumer code — it is intended for runtime/HMR and
+ * internal tests only. Consumers should use the public `component` API.
+ */
+export declare const registry: Map<string, ComponentConfig<object, object, object>>;
+/**
+ * Lazily initialize the global registry slot with SSR safety.
+ * This avoids performing a write to globalThis at module-import time
+ * (which is a side-effect that prevents bundlers from tree-shaking).
+ * Enhanced with SSR detection and multi-tenant safety.
+ */
+export declare function initGlobalRegistryIfNeeded(): void;

package/dist/runtime/component.d.ts

@@ -1,50 +1,3 @@
-import type { ComponentConfig, VNode } from './types';
-/**
- * @internal
- * Runtime registry of component configs.
- * NOTE: This is an internal implementation detail. Do not import from the
- * published package in consumer code — it is intended for runtime/HMR and
- * internal tests only. Consumers should use the public `component` API.
- */
-export declare const registry: Map<string, ComponentConfig<object, object, object>>;
-export declare function createElementClass<S extends object, C extends object, P extends object, T extends object = object>(tag: string, config: ComponentConfig<S, C, P, T>): CustomElementConstructor | {
-    new (): object;
-};
-/**
- * Streamlined functional component API with automatic reactive props and lifecycle hooks.
- *
- * @example
- * ```ts
- * // Simple component with no parameters
- * component('simple-header', () => {
- *   return html`<h1>Hello World</h1>`;
- * });
- *
- * // With props using useProps() hook
- * component('with-props', () => {
- *   const { message } = useProps({ message: 'Hello' });
- *   return html`<div>${message}</div>`;
- * });
- *
- * // With props and lifecycle hooks
- * component('my-switch', () => {
- *   const { modelValue, label } = useProps({ modelValue: false, label: '' });
- *   const emit = useEmit();
- *
- *   useOnConnected(() => console.log('Switch connected!'));
- *   useOnDisconnected(() => console.log('Switch disconnected!'));
- *
- *   return html`
- *     <label>
- *       ${label}
- *       <input
- *         type="checkbox"
- *         :checked="${modelValue}"
- *         @change="${(e) => emit('update:modelValue', e.target.checked)}"
- *       />
- *     </label>
- *   `;
- * });
- * ```
- */
-export declare function component(tag: string, renderFn: () => VNode | VNode[] | Promise<VNode | VNode[]>): void;
+export { registry } from './component/registry';
+export { createElementClass } from './component/element-class';
+export { component } from './component/factory';

package/dist/runtime/discovery-state.d.ts

@@ -0,0 +1,30 @@
+/**
+ * discovery-state.ts
+ *
+ * Isolated discovery-render flag. Extracted from hooks.ts to break the
+ * circular dependency between hooks.ts and reactive.ts — both modules need
+ * to check `isDiscoveryRender()`, but hooks.ts also imports from reactive.ts.
+ *
+ * All side-effectful hooks (watchEffect, watch, useOnConnected, useStyle,
+ * provide, inject, useEmit, …) must guard their setup with
+ * `isDiscoveryRender()` and return early / return no-ops when it is true.
+ */
+/**
+ * Returns `true` while a discovery render is in progress.
+ * Used by `html` tagged templates and hooks to short-circuit side effects.
+ * @internal
+ */
+export declare function isDiscoveryRender(): boolean;
+/**
+ * Mark the start of a discovery render pass.
+ * Call this immediately before invoking the render function for the first time
+ * (before `useProps` prop-name collection).
+ * @internal
+ */
+export declare function beginDiscoveryRender(): void;
+/**
+ * Mark the end of a discovery render pass.
+ * Call this in a `finally` block after the discovery render function returns.
+ * @internal
+ */
+export declare function endDiscoveryRender(): void;

package/dist/runtime/hooks.d.ts

@@ -2,6 +2,13 @@
  * Context-based hooks for functional components
  * Provides React-like hooks with perfect TypeScript inference
  */
+export { beginDiscoveryRender, endDiscoveryRender } from './discovery-state';
+/**
+ * Returns true while a discovery render is in progress.
+ * Used by `html` and other primitives to short-circuit side effects.
+ * @internal
+ */
+export declare function isDiscoveryRender(): boolean;
 /**
  * Set the current component context (called internally during render)
  * @internal
@@ -12,6 +19,12 @@ export declare function setCurrentComponentContext(context: Record<string, unkno
  * @internal
  */
 export declare function clearCurrentComponentContext(): void;
+/**
+ * Get the current component context. Useful for advanced composable patterns
+ * that need to access or pass the context explicitly.
+ * @internal
+ */
+export declare function getCurrentComponentContext(): Record<string, unknown> | null;
 /**
  * Get the emit function for the current component
  * Must be called during component render
@@ -137,3 +150,105 @@ export declare function useProps<T extends Record<string, unknown>>(defaults: T)
  * ```
  */
 export declare function useStyle(callback: () => string): void;
+/**
+ * Store a value under a key so that descendant components can retrieve it
+ * with `inject()`. Must be called during component render.
+ *
+ * @example
+ * ```ts
+ * component('theme-provider', () => {
+ *   provide('theme', 'dark');
+ *   return html`<slot></slot>`;
+ * });
+ * ```
+ */
+export declare function provide<T>(key: string | symbol, value: T): void;
+/**
+ * Retrieve a value provided by an ancestor component. Traverses the shadow
+ * DOM tree upward through ShadowRoot host elements looking for the nearest
+ * `provide()` call with the matching key. Returns `defaultValue` (or
+ * `undefined`) when no provider is found. Must be called during render.
+ *
+ * @example
+ * ```ts
+ * component('themed-button', () => {
+ *   const theme = inject<string>('theme', 'light');
+ *   return html`<button class="btn-${theme}">Click</button>`;
+ * });
+ * ```
+ */
+export declare function inject<T>(key: string | symbol, defaultValue?: T): T | undefined;
+/**
+ * Execute a function that calls hooks (useOnConnected, useOnDisconnected, etc.)
+ * using an explicit component context rather than requiring the call to happen
+ * directly inside a render function. This enables composable utility functions
+ * that register lifecycle callbacks from outside the render body.
+ *
+ * @example
+ * ```ts
+ * function useLogger(label: string) {
+ *   return createComposable(() => {
+ *     useOnConnected(() => console.log(`${label} connected`));
+ *     useOnDisconnected(() => console.log(`${label} disconnected`));
+ *   });
+ * }
+ *
+ * component('my-comp', () => {
+ *   const stopLogger = useLogger('my-comp');
+ *   stopLogger(context); // pass the component context explicitly
+ *   return html`<div>Hello</div>`;
+ * });
+ * ```
+ *
+ * More commonly, use it as a direct wrapper inside render:
+ * ```ts
+ * component('my-comp', () => {
+ *   // Accepts context automatically from getCurrentComponentContext()
+ *   createComposable(() => {
+ *     useOnConnected(() => console.log('connected from composable'));
+ *   })();
+ *   return html`<div>Hello</div>`;
+ * });
+ * ```
+ */
+export declare function createComposable<T>(fn: () => T): (ctx?: Record<string, unknown>) => T;
+/**
+ * Expose a public interface from the current component so that parent
+ * components holding a template ref to this element can call its methods
+ * or read its properties. Must be called during component render.
+ *
+ * @example
+ * ```ts
+ * component('my-counter', () => {
+ *   const count = ref(0);
+ *   useExpose({ increment: () => count.value++, get count() { return count.value; } });
+ *   return html`<div>${count.value}</div>`;
+ * });
+ *
+ * // Parent: counterRef.value.increment()
+ * ```
+ */
+export declare function useExpose<T extends Record<string, unknown>>(exposed: T): void;
+/**
+ * Access named slots provided to the current component. Returns helpers to
+ * check slot presence and retrieve slotted elements. Must be called during
+ * component render.
+ *
+ * @example
+ * ```ts
+ * component('my-card', () => {
+ *   const slots = useSlots();
+ *   return html`
+ *     <div class="card">
+ *       <slot></slot>
+ *       ${slots.has('footer') ? html`<footer><slot name="footer"></slot></footer>` : ''}
+ *     </div>
+ *   `;
+ * });
+ * ```
+ */
+export declare function useSlots(): {
+    has(name?: string): boolean;
+    getNodes(name?: string): Element[];
+    names(): string[];
+};

package/dist/runtime/logger.d.ts

@@ -6,6 +6,14 @@
  * Programmatically toggle dev-mode logging at runtime.
  * Prefer setting `globalThis.__CE_RUNTIME_DEV__ = true` before importing
  * the runtime so logs are enabled as early as possible.
+ *
+ * @param v - `true` to enable dev logging, `false` to disable it.
+ *
+ * @example
+ * ```ts
+ * import { setDevMode } from '@jasonshimmy/custom-elements-runtime';
+ * setDevMode(true); // enable verbose dev logs
+ * ```
  */
 export declare function setDevMode(v: boolean): void;
 /**
@@ -17,6 +25,16 @@ export declare function devError(message: string, ...args: unknown[]): void;
  */
 export declare function devWarn(message: string, ...args: unknown[]): void;
 /**
- * Log info only in development mode
+ * Log an informational message only in development mode.
+ * No-ops in production builds or when dev mode is disabled.
+ *
+ * @param message - Message to log.
+ * @param args - Additional values to pass to `console.log`.
+ *
+ * @example
+ * ```ts
+ * import { devLog } from '@jasonshimmy/custom-elements-runtime';
+ * devLog('[my-component] mounted', { props });
+ * ```
  */
 export declare function devLog(message: string, ...args: unknown[]): void;

package/dist/runtime/monitoring/health-monitor.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Runtime Health Monitoring System
+ * Tracks framework health metrics and provides early warning for potential issues
+ */
+interface HealthMetric {
+    name: string;
+    value: number;
+    threshold: number;
+    status: 'healthy' | 'warning' | 'critical';
+    lastUpdated: number;
+    history: number[];
+}
+interface HealthReport {
+    overall: 'healthy' | 'warning' | 'critical';
+    metrics: Record<string, HealthMetric>;
+    timestamp: number;
+    recommendations: string[];
+}
+export type { HealthReport };
+/**
+ * Public interface for a health monitor instance.
+ * All state is managed internally via closures — no class syntax.
+ */
+export interface HealthMonitorInstance {
+    /** Update a specific health metric value */
+    updateMetric(name: string, value: number): void;
+    /** Get the current health report */
+    getHealthReport(): HealthReport;
+    /** Add a listener to be notified when a health check runs */
+    addListener(listener: (report: HealthReport) => void): void;
+    /** Remove a previously registered listener */
+    removeListener(listener: (report: HealthReport) => void): void;
+    /** Stop the periodic health monitoring timer */
+    stop(): void;
+    /** Get historical values for a specific metric */
+    getMetricHistory(name: string): number[];
+    /** Clear all metric history */
+    clearHistory(): void;
+}
+/**
+ * Create a new health monitor instance.
+ * All mutable state lives in closures — no `class` or `this`.
+ */
+export declare function createHealthMonitor(): HealthMonitorInstance;
+/**
+ * Get the global health monitor singleton instance.
+ */
+export declare function getHealthMonitor(): HealthMonitorInstance;
+/**
+ * Update a health metric from anywhere in the framework.
+ */
+export declare function updateHealthMetric(name: string, value: number): void;
+/**
+ * Get the current health status report.
+ */
+export declare function getHealthStatus(): HealthReport;

package/dist/runtime/reactive.d.ts

@@ -1,3 +1,4 @@
+import type { WatchOptions } from './types';
 /**
  * Global reactive system for tracking dependencies and triggering updates
  */
@@ -71,6 +72,22 @@ export declare class ReactiveState<T> {
     constructor(initialValue: T);
     get value(): T;
     set value(newValue: T);
+    /**
+     * Read the current value without registering a reactive dependency.
+     * Useful for internal infrastructure (e.g. stable hook slots) that must
+     * inspect the stored value without re-triggering the containing component.
+     * @internal
+     */
+    peek(): T;
+    /**
+     * Set the initial value without triggering any reactive updates or warnings.
+     * Only intended for internal/infrastructure use (e.g. storing a stable hook
+     * handle in a reactive slot without causing a spurious re-render).
+     * The value is stored as-is without reactive proxy wrapping so that opaque
+     * objects (e.g. TeleportHandle) are not accidentally instrumented.
+     * @internal
+     */
+    initSilent(value: T): void;
     addDependent(componentId: string): void;
     removeDependent(componentId: string): void;
     getDependents(): Set<string>;
@@ -101,18 +118,37 @@ export declare function ref<T>(initialValue: T): ReactiveState<T>;
  */
 export declare function isReactiveState(v: unknown): v is ReactiveState<unknown>;
 /**
- * Create computed state that derives from other reactive state
+ * Create computed state that derives from other reactive state.
+ * The result is cached and only recomputed when tracked reactive dependencies change.
  *
  * @example
  * ```ts
  * const firstName = ref('John');
  * const lastName = ref('Doe');
  * const fullName = computed(() => `${firstName.value} ${lastName.value}`);
+ * console.log(fullName.value); // 'John Doe' — cached until firstName or lastName changes
  * ```
  */
 export declare function computed<T>(fn: () => T): {
     readonly value: T;
 };
+/**
+ * Run a side-effect function immediately and automatically re-run it whenever
+ * any reactive state accessed inside `fn` changes. Similar to Vue's `watchEffect`.
+ *
+ * @returns A cleanup function that stops the effect.
+ *
+ * @example
+ * ```ts
+ * const count = ref(0);
+ * const stop = watchEffect(() => {
+ *   document.title = `Count: ${count.value}`;
+ * });
+ * count.value++; // automatically re-runs the effect
+ * stop(); // cancel the effect
+ * ```
+ */
+export declare function watchEffect(fn: () => void): () => void;
 /**
  * Create a watcher that runs when dependencies change
  *
@@ -124,9 +160,5 @@ export declare function computed<T>(fn: () => T): {
  * });
  * ```
  */
-export declare function watch<T>(source: ReactiveState<T>, callback: (newValue: T, oldValue?: T) => void, options?: {
-    immediate?: boolean;
-}): () => void;
-export declare function watch<T>(source: () => T, callback: (newValue: T, oldValue?: T) => void, options?: {
-    immediate?: boolean;
-}): () => void;
+export declare function watch<T>(source: ReactiveState<T>, callback: (newValue: T, oldValue?: T) => void, options?: WatchOptions): () => void;
+export declare function watch<T>(source: () => T, callback: (newValue: T, oldValue?: T) => void, options?: WatchOptions): () => void;

package/dist/runtime/render.d.ts

@@ -11,18 +11,34 @@ export declare function registerChildComponent(shadowRoot: ShadowRoot, childEl:
  */
 export declare function unregisterChildComponent(shadowRoot: ShadowRoot, childEl: HTMLElement): void;
 /**
- * Renders the component output.
+ * Renders the component output with optimized error handling and loading states.
  */
 export declare function renderComponent<S extends object, C extends object, P extends object, T extends object>(shadowRoot: ShadowRoot | null, cfg: ComponentConfig<S, C, P, T>, context: ComponentContext<S, C, P, T>, refs: Refs['refs'], setHtmlString: (html: string) => void, setLoading: (val: boolean) => void, setError: (err: Error | null) => void, applyStyle: (html: string) => void): void;
 /**
- * Renders VNode(s) to the shadowRoot.
+ * Renders VNode(s) to the shadowRoot with performance optimizations.
  */
 export declare function renderOutput<S extends object, C extends object, P extends object, T extends object>(shadowRoot: ShadowRoot | null, output: VNode | VNode[], context: ComponentContext<S, C, P, T>, refs: Refs['refs'], setHtmlString: (html: string) => void): void;
 /**
- * Debounced render request with infinite loop protection.
+ * Advanced render request with intelligent throttling and loop detection.
  */
 export declare function requestRender(renderFn: () => void, lastRenderTime: number, renderCount: number, setLastRenderTime: (t: number) => void, setRenderCount: (c: number) => void, renderTimeoutId: ReturnType<typeof setTimeout> | null, setRenderTimeoutId: (id: ReturnType<typeof setTimeout> | null) => void): void;
 /**
- * Applies styles to the shadowRoot.
+ * Optimized style application with intelligent caching and generation tracking.
  */
 export declare function applyStyle<S extends object, C extends object, P extends object, T extends object>(shadowRoot: ShadowRoot | null, context: ComponentContext<S, C, P, T>, htmlString: string, styleSheet: CSSStyleSheet | null, setStyleSheet: (sheet: CSSStyleSheet | null) => void): void;
+/**
+ * Clean up render-related caches for a shadow root
+ * @internal
+ */
+export declare function cleanupRenderCaches(shadowRoot: ShadowRoot): void;
+/**
+ * Get render performance metrics for debugging
+ * @internal
+ */
+export declare function getRenderStats(shadowRoot: ShadowRoot): {
+    renderCount: number;
+    lastRenderTime: number;
+    isThrottled: boolean;
+    childComponentCount: number;
+    hasCachedHtml: boolean;
+};