@askrjs/askr 0.0.3 → 0.0.4

package/dist/index.d.ts

@@ -1,128 +1,5 @@
-import { J as JSXElement, P as Props } from './types-DLTViI21.js';
-export { Fragment, jsx, jsxs } from './jsx/jsx-runtime.js';
-
-/**
- * Context system: lexical scope + render-time snapshots
- *
- * CORE SEMANTIC (Option A — Snapshot-Based):
- * ============================================
- * An async resource observes the context of the render that created it.
- * Context changes only take effect via re-render, not magically mid-await.
- *
- * This ensures:
- * - Deterministic behavior
- * - Concurrency safety
- * - Replayable execution
- * - Debuggability
- *
- * INVARIANTS:
- * - readContext() only works during component render (has currentContextFrame)
- * - Each render captures a context snapshot
- * - Async continuations see the snapshot from render start (frozen)
- * - Provider (Scope) creates a new frame that shadows parent
- * - Context updates require re-render to take effect
- */
-
-type ContextKey = symbol;
-interface Context<T> {
-    readonly key: ContextKey;
-    readonly defaultValue: T;
-    readonly Scope: (props: {
-        value: unknown;
-        children?: unknown;
-    }) => JSXElement;
-}
-interface ContextFrame {
-    parent: ContextFrame | null;
-    values: Map<ContextKey, unknown> | null;
-}
-declare function defineContext<T>(defaultValue: T): Context<T>;
-declare function readContext<T>(context: Context<T>): T;
-
-/**
- * Component instance lifecycle management
- * Internal only — users never see this
- */
-
-type ComponentFunction = (props: Props, context?: {
-    signal: AbortSignal;
-}) => JSXElement | VNode$1 | string | number | null;
-type VNode$1 = {
-    type: string;
-    props?: Props;
-    children?: (string | VNode$1 | null | undefined | false)[];
-};
-interface ComponentInstance {
-    id: string;
-    fn: ComponentFunction;
-    props: Props;
-    target: Element | null;
-    mounted: boolean;
-    abortController: AbortController;
-    ssr?: boolean;
-    cleanupStrict?: boolean;
-    stateValues: State<unknown>[];
-    evaluationGeneration: number;
-    notifyUpdate: (() => void) | null;
-    _pendingFlushTask?: () => void;
-    _pendingRunTask?: () => void;
-    _enqueueRun?: () => void;
-    stateIndexCheck: number;
-    expectedStateIndices: number[];
-    firstRenderComplete: boolean;
-    mountOperations: Array<() => void | (() => void) | Promise<void | (() => void)>>;
-    cleanupFns: Array<() => void>;
-    hasPendingUpdate: boolean;
-    ownerFrame: ContextFrame | null;
-    isRoot?: boolean;
-    _currentRenderToken?: number;
-    lastRenderToken?: number;
-    _pendingReadStates?: Set<State<unknown>>;
-    _lastReadStates?: Set<State<unknown>>;
-    _placeholder?: Comment;
-}
-/**
- * Get the abort signal for the current component
- * Used to cancel async operations on unmount/navigation
- *
- * The signal is guaranteed to be aborted when:
- * - Component unmounts
- * - Navigation occurs (different route)
- * - Parent is destroyed
- *
- * IMPORTANT: getSignal() must be called during component render execution.
- * It captures the current component instance from context.
- *
- * @returns AbortSignal that will be aborted when component unmounts
- * @throws Error if called outside component execution
- *
- * @example
- * ```ts
- * // ✅ Correct: called during render, used in async operation
- * export async function UserPage({ id }: { id: string }) {
- *   const signal = getSignal();
- *   const user = await fetch(`/api/users/${id}`, { signal });
- *   return <div>{user.name}</div>;
- * }
- *
- * // ✅ Correct: passed to event handler
- * export function Button() {
- *   const signal = getSignal();
- *   return {
- *     type: 'button',
- *     props: {
- *       onClick: async () => {
- *         const data = await fetch(url, { signal });
- *       }
- *     }
- *   };
- * }
- *
- * // ❌ Wrong: called outside component context
- * const signal = getSignal(); // Error: not in component
- * ```
- */
-declare function getSignal(): AbortSignal;
+import { P as Props, J as JSXElement } from './jsx-AzPM8gMS.js';
+import { R as Route } from './router-DaGtH1Sq.js';
 
 /**
  * State primitive for Askr components
@@ -179,94 +56,82 @@ interface State<T> {
  */
 declare function state<T>(initialValue: T): State<T>;
 
-declare function scheduleEventHandler(handler: EventListener): EventListener;
-
-interface DataResult<T> {
-    value: T | null;
-    pending: boolean;
-    error: Error | null;
-    refresh(): void;
-}
 /**
- * Resource primitive — simple, deterministic async primitive
- * Usage: resource(fn, deps)
- * - fn receives { signal }
- * - captures execution context once at creation (synchronous step only)
- * - executes at most once per generation; stale async results are ignored
- * - refresh() cancels in-flight execution, increments generation and re-runs
- * - exposes { value, pending, error, refresh }
- * - during SSR, async results are disallowed and will throw synchronously
+ * Common call contracts: Component signatures
  */
-declare function resource<T>(fn: (opts: {
+
+type ComponentContext = {
     signal: AbortSignal;
-}) => Promise<T> | T, deps?: unknown[]): DataResult<T>;
-declare function derive<TOut>(fn: () => TOut): TOut | null;
-declare function task(fn: () => void | (() => void) | Promise<void | (() => void)>): void;
+};
+type ComponentVNode = {
+    type: string;
+    props?: Props;
+    children?: (string | ComponentVNode | null | undefined | false)[];
+};
+type ComponentFunction = (props: Props, context?: ComponentContext) => JSXElement | ComponentVNode | string | number | null;
 
 /**
- * Route definition and matching
- * Supports dynamic route registration for micro frontends
+ * Context system: lexical scope + render-time snapshots
+ *
+ * CORE SEMANTIC (Option A — Snapshot-Based):
+ * ============================================
+ * An async resource observes the context of the render that created it.
+ * Context changes only take effect via re-render, not magically mid-await.
+ *
+ * This ensures:
+ * - Deterministic behavior
+ * - Concurrency safety
+ * - Replayable execution
+ * - Debuggability
  *
- * Optimization: Index by depth but maintain insertion order within each depth
+ * INVARIANTS:
+ * - readContext() only works during component render (has currentContextFrame)
+ * - Each render captures a context snapshot
+ * - Async continuations see the snapshot from render start (frozen)
+ * - Provider (Scope) creates a new frame that shadows parent
+ * - Context updates require re-render to take effect
  */
-interface RouteHandler {
-    (params: Record<string, string>, context?: {
-        signal: AbortSignal;
-    }): unknown;
-}
-interface Route {
-    path: string;
-    handler: RouteHandler;
-    namespace?: string;
+
+type ContextKey = symbol;
+interface ContextFrame {
+    parent: ContextFrame | null;
+    values: Map<ContextKey, unknown> | null;
 }
+
 /**
- * RouteMatch, RouteQuery, RouteSnapshot
- * These describe the read-only snapshot returned by the render-time route() accessor
+ * Component instance lifecycle management
+ * Internal only — users never see this
  */
-interface RouteMatch {
-    path: string;
-    params: Readonly<Record<string, string>>;
-    name?: string;
-    namespace?: string;
-}
-interface RouteQuery {
-    get(key: string): string | null;
-    getAll(key: string): string[];
-    has(key: string): boolean;
-    toJSON(): Record<string, string | string[]>;
-}
-interface RouteSnapshot {
-    path: string;
-    params: Readonly<Record<string, string>>;
-    query: Readonly<RouteQuery>;
-    hash: string | null;
-    name?: string;
-    namespace?: string;
-    matches: readonly RouteMatch[];
+
+interface ComponentInstance {
+    id: string;
+    fn: ComponentFunction;
+    props: Props;
+    target: Element | null;
+    mounted: boolean;
+    abortController: AbortController;
+    ssr?: boolean;
+    cleanupStrict?: boolean;
+    stateValues: State<unknown>[];
+    evaluationGeneration: number;
+    notifyUpdate: (() => void) | null;
+    _pendingFlushTask?: () => void;
+    _pendingRunTask?: () => void;
+    _enqueueRun?: () => void;
+    stateIndexCheck: number;
+    expectedStateIndices: number[];
+    firstRenderComplete: boolean;
+    mountOperations: Array<() => void | (() => void) | Promise<void | (() => void)>>;
+    cleanupFns: Array<() => void>;
+    hasPendingUpdate: boolean;
+    ownerFrame: ContextFrame | null;
+    isRoot?: boolean;
+    _currentRenderToken?: number;
+    lastRenderToken?: number;
+    _pendingReadStates?: Set<State<unknown>>;
+    _lastReadStates?: Set<State<unknown>>;
+    _placeholder?: Comment;
 }
-declare function setServerLocation(url: string | null): void;
-declare function route(): RouteSnapshot;
-declare function route(path: string, handler?: RouteHandler, namespace?: string): void;
-/**
- * Get all registered routes
- */
-declare function getRoutes(): Route[];
-/**
- * Get routes for a specific namespace
- */
-declare function getNamespaceRoutes(namespace: string): Route[];
-/**
- * Unload all routes from a namespace (for MFE unmounting)
- */
-declare function unloadNamespace(namespace: string): number;
-/**
- * Clear all registered routes (mainly for testing)
- */
-declare function clearRoutes(): void;
-/**
- * Get all loaded namespaces (MFE identifiers)
- */
-declare function getLoadedNamespaces(): string[];
 
 /**
  * App bootstrap and mount
@@ -284,11 +149,6 @@ type SPAConfig = {
     cleanupStrict?: boolean;
     component?: never;
 };
-type HydrateSPAConfig = {
-    root: Element | string;
-    routes: Route[];
-    cleanupStrict?: boolean;
-};
 /**
  * createIsland: Enhances existing DOM (no router, mounts once)
  */
@@ -297,205 +157,12 @@ declare function createIsland(config: IslandConfig): void;
  * createSPA: Initializes router and mounts the app with provided route table
  */
 declare function createSPA(config: SPAConfig): Promise<void>;
-/**
- * hydrateSPA: Hydrate server-rendered HTML with explicit routes
- */
-declare function hydrateSPA(config: HydrateSPAConfig): Promise<void>;
-/**
- * Cleanup an app mounted on a root element (element or id).
- * Safe to call multiple times — no-op when nothing is mounted.
- */
-declare function cleanupApp(root: Element | string): void;
-/**
- * Check whether an app is mounted on the given root
- */
-declare function hasApp(root: Element | string): boolean;
-
-/**
- * Client-side navigation with History API
- */
-
-/**
- * Navigate to a new path
- * Updates URL, resolves route, and re-mounts app with new handler
- */
-declare function navigate(path: string): void;
-
-/**
- * Link component for client-side navigation
- */
-interface LinkProps {
-    href: string;
-    children?: unknown;
-}
-/**
- * Link component that prevents default navigation and uses navigate()
- * Provides declarative way to navigate between routes
- *
- * Respects:
- * - Middle-click (opens in new tab)
- * - Ctrl/Cmd+click (opens in new tab)
- * - Shift+click (opens in new window)
- * - Right-click context menu
- */
-declare function Link({ href, children }: LinkProps): unknown;
-
-/**
- * Layout helper.
- *
- * A layout is just a normal component that wraps children.
- * Persistence and reuse are handled by the runtime via component identity.
- *
- * This helper exists purely for readability and convention.
- */
-type LayoutComponent<P = object> = (props: P & {
-    children?: unknown;
-}) => unknown;
-declare function layout<P = object>(Layout: LayoutComponent<P>): (children?: unknown, props?: P) => unknown;
-
-type SlotProps = {
-    asChild: true;
-    children: JSXElement;
-    [key: string]: unknown;
-} | {
-    asChild?: false;
-    children?: unknown;
-};
-declare function Slot(props: SlotProps): JSXElement | null;
-
-/**
- * Portal / Host primitive.
- *
- * A portal is a named render slot within the existing tree.
- * It does NOT create a second tree or touch the DOM directly.
- */
-interface Portal<T = unknown> {
-    /** Mount point — rendered exactly once */
-    (): unknown;
-    /** Render content into the portal */
-    render(props: {
-        children?: T;
-    }): unknown;
-}
-declare function definePortal<T = unknown>(): Portal<T>;
-/**
- * Reset the default portal state. Used by tests to ensure isolation.
- * @internal
- */
-declare function _resetDefaultPortal(): void;
-declare const DefaultPortal: Portal<unknown>;
-
-/**
- * SSR Context Management
- *
- * Provides context for server-side rendering including:
- * - SSRContext: Full context for sink-based streaming SSR
- * - RenderContext: Lightweight context for sync render passes
- */
-
-type SSRData = Record<string, unknown>;
-/** Lightweight context for synchronous render passes */
-type RenderContext = {
-    seed: number;
-};
-
-/**
- * Shared SSR types
- */
-
-/** VNode representation for SSR rendering */
-type VNode = {
-    type: string | SSRComponent;
-    props?: Props;
-    children?: unknown[];
-};
-/**
- * Component function signature for SSR.
- * Components receive props and an optional context with signal and SSR context.
- */
-type SSRComponent = (props: Props, context?: {
-    signal?: AbortSignal;
-    ssr?: RenderContext;
-}) => VNode | JSXElement | string | number | boolean | null;
-
-/**
- * SSR Data Management
- *
- * Manages render-phase keying for deterministic SSR data lookup.
- * Note: SSR collection/prepass APIs have been removed — SSR is strictly synchronous.
- */
-
-type ResourceDescriptor = {
-    key: string;
-    fn: (opts: {
-        signal?: AbortSignal;
-    }) => Promise<unknown> | unknown;
-    deps: unknown[];
-    index: number;
-};
-type ResourcePlan = {
-    resources: ResourceDescriptor[];
-};
-/** @deprecated SSR prepass has been removed */
-declare function resolvePlan(_plan: ResourcePlan): Promise<Record<string, unknown>>;
-/** @deprecated SSR prepass has been removed */
-declare function collectResources(_opts: {
-    url: string;
-    routes: SSRRoute[];
-}): ResourcePlan;
-/** @deprecated Alias for resolvePlan */
-declare const resolveResources: typeof resolvePlan;
-
-/**
- * SSR - Server-Side Rendering
- *
- * Renders Askr components to static HTML strings for server-side rendering.
- * SSR is synchronous: async components are not supported; async work should use
- * `resource()` which is rejected during synchronous SSR. This module throws
- * when an async component or async resource is encountered during sync SSR.
- */
 
-/**
- * Single synchronous SSR entrypoint: render a component to an HTML string.
- * This is strictly synchronous and deterministic. Optionally provide a seed
- * for deterministic randomness via `options.seed`.
- */
-declare function renderToStringSync(component: (props?: Record<string, unknown>) => VNode | JSXElement | string | number | null, props?: Record<string, unknown>, options?: {
-    seed?: number;
-    data?: SSRData;
-}): string;
-declare function renderToStringSyncForUrl(opts: {
-    url: string;
-    routes: Array<{
-        path: string;
-        handler: RouteHandler;
-        namespace?: string;
-    }>;
-    options?: {
-        seed?: number;
-        data?: SSRData;
-    };
-}): string;
-
-type SSRRoute = {
-    path: string;
-    handler: RouteHandler;
-    namespace?: string;
-};
-declare function renderToString(component: (props?: Record<string, unknown>) => VNode | JSXElement | string | number | null): string;
-declare function renderToString(opts: {
-    url: string;
-    routes: SSRRoute[];
-    seed?: number;
-    data?: SSRData;
-}): string;
-declare function renderToStream(opts: {
-    url: string;
-    routes: SSRRoute[];
-    seed?: number;
-    data?: SSRData;
-    onChunk(html: string): void;
-    onComplete(): void;
-}): void;
+declare function derive<TOut>(fn: () => TOut): TOut | null;
+declare function derive<TIn, TOut>(source: {
+    value: TIn | null;
+    pending?: boolean;
+    error?: Error | null;
+} | TIn | (() => TIn), map: (value: TIn) => TOut): TOut | null;
 
-export { type Context, type DataResult, DefaultPortal, type HydrateSPAConfig, type IslandConfig, type LayoutComponent, Link, type LinkProps, type Portal, Props, type Route, type RouteHandler, type RouteMatch, type RouteSnapshot, type SPAConfig, Slot, type SlotProps, type State, _resetDefaultPortal, cleanupApp, clearRoutes, collectResources, createIsland, createSPA, defineContext, definePortal, derive, getLoadedNamespaces, getNamespaceRoutes, getRoutes, getSignal, hasApp, hydrateSPA, layout, navigate, readContext, renderToStream, renderToString, renderToStringSync, renderToStringSyncForUrl, resolveResources, resource, route, scheduleEventHandler, setServerLocation, state, task, unloadNamespace };
+export { type IslandConfig, Props, type SPAConfig, type State, createIsland, createSPA, derive, state };