@lark.js/mvc 0.0.14 → 0.0.15

package/dist/types.d.ts

@@ -0,0 +1,1259 @@
+/**
+ * Lark framework type definitions.
+ * All shared types are defined here to eliminate type cheats across modules.
+ *
+ * Lark is a lightweight MVC frontend framework that provides:
+ * - View: base view class with extend/merge inheritance and mixin support
+ * - Router: hash-based two-phase route confirmation
+ * - State: simple cross-view observable singleton (recommended for simple cases)
+ * - Store: zustand-aligned state management with create/getState/setState/subscribe
+ *   (recommended for complex cases)
+ * - Service: API request management with caching, queuing, and deduplication
+ * - Frame: view frame managing view mount/unmount lifecycle
+ * - Updater: view data binding and DOM diff (in-memory real DOM diff) renderer
+ *
+ * Designed for single-page application (SPA) development.
+ */
+/** Generic function type for event handlers and callbacks.
+ *  Uses any[] to accept callbacks with specific parameter types
+ *  (TypeScript function parameters are contravariant).
+ */
+export type AnyFunc = (...args: any[]) => unknown;
+/** A function that returns void. */
+export type VoidFunc = (...args: any[]) => void;
+export interface CacheEntry<T> {
+    /** Original key without prefix */
+    originalKey: string;
+    /** Cached value */
+    value: T | undefined;
+    /** Access frequency count */
+    frequency: number;
+    /** Last access timestamp */
+    lastTimestamp: number;
+}
+export interface CacheOptions<T> {
+    /** Maximum cache size before eviction triggers (default: 20) */
+    maxSize?: number;
+    /** Buffer size for eviction (default: 5) */
+    bufferSize?: number;
+    /** Callback when entry is removed */
+    onRemove?: (key: string) => void;
+    /** Comparator for sorting entries */
+    sortComparator?: (a: CacheEntry<T>, b: CacheEntry<T>) => number;
+}
+/**
+ * Cache interface providing LFU (Least Frequently Used) cache management.
+ * Cache keys use a special prefix internally for namespace isolation.
+ */
+export interface CacheInterface<T = unknown> {
+    /**
+     * Set a cache resource. If the key exists, updates the value and increments frequency.
+     * Triggers LFU eviction when cache entries exceed capacity (maxSize + bufferSize).
+     * @param key Unique identifier for the cached resource
+     * @param resource The resource to cache
+     */
+    set(key: string, resource: T): void;
+    /**
+     * Get a cached resource. Access increments frequency count and timestamp for LFU ranking.
+     * Returns undefined if the key does not exist.
+     * @param key Cache resource key
+     */
+    get(key: string): T | undefined;
+    /**
+     * Remove a resource from cache by key. Triggers onRemove callback on deletion.
+     * @param key Cache resource key to remove
+     */
+    del(key: string): void;
+    /**
+     * Check if cache contains a resource for the given key.
+     * @param key Cache resource key
+     */
+    has(key: string): boolean;
+    /**
+     * Iterate over all cached resource values.
+     * @param callback Iteration callback receiving the cached value (may be undefined)
+     */
+    forEach(callback: (value: T | undefined) => void): void;
+    /**
+     * Number of cache entries.
+     */
+    readonly size: number;
+    /**
+     * Clear all cache entries. Triggers onRemove callback for each deleted entry.
+     */
+    clear(): void;
+}
+export interface EventListenerEntry {
+    /** Handler function */
+    handler: AnyFunc;
+    /** Whether currently executing (1 = executing, '' = done) */
+    executing: number | string;
+}
+/**
+ * Parsed URL result containing path and parameters.
+ * Returned by `Router.parse()`, includes the path string and parsed key-value parameter pairs.
+ */
+export interface ParsedUri {
+    /** Path portion (before ? or #), excluding query parameters */
+    path: string;
+    /** Key-value params parsed from the URL */
+    params: Record<string, string>;
+}
+/**
+ * Current URL parsing result interface.
+ * Returned by `Router.parse()`, includes both query (after ?) and hash (after #) sections.
+ */
+export interface Location {
+    /** Full href, original href string */
+    href: string;
+    /** Query string (before #), raw query string (after ?, before #) */
+    srcQuery: string;
+    /** Hash string (after #), raw hash string (after #) */
+    srcHash: string;
+    /** Parsed query object, path and params parsed from srcQuery */
+    query: ParsedUri;
+    /** Parsed hash object, path and params parsed from srcHash */
+    hash: ParsedUri;
+    /**
+     * Merged params from query and hash,
+     * hash values take precedence when keys conflict.
+     */
+    params: Record<string, string>;
+    /**
+     * Resolved view path for the current URL.
+     * May be undefined before framework boot.
+     */
+    view?: string;
+    /**
+     * Resolved path computed from hash path and query path based on routing rules.
+     * May be undefined before framework boot.
+     */
+    path?: string;
+    /**
+     * Get param by key with optional default value.
+     * Returns default value or empty string if key does not exist.
+     * @param key Parameter key name
+     * @param defaultValue Default value when key is missing, defaults to empty string
+     */
+    get: (key: string, defaultValue?: string) => string;
+}
+/**
+ * URL parameter change representing a parameter value transition from old to new.
+ * Used in `Router.diff()` return value to describe parameter changes.
+ */
+export interface ParamDiff {
+    /** Value before the change */
+    from: string;
+    /** Value after the change */
+    to: string;
+}
+/**
+ * URL route change object interface describing changes between two routing states.
+ * Returned by `Router.diff()`, includes changes in path, view, and other parameters.
+ */
+export interface LocationDiff {
+    /**
+     * Changed params (key -> {from, to}),
+     * diff for all changed parameters
+     */
+    params: Record<string, ParamDiff>;
+    /** Path diff when path has changed */
+    path?: ParamDiff;
+    /** View diff when rendered view has changed */
+    view?: ParamDiff;
+    /**
+     * Whether this is a first forced change during app initialization.
+     */
+    force: boolean;
+    /** Whether any content has changed */
+    changed: boolean;
+}
+/**
+ * Route pre-change event interface (change phase).
+ * Provides two-phase confirmation: triggers change (can be rejected), then changed.
+ * Can prevent, reject, or accept route changes through this event object.
+ */
+export interface RouteChangeEvent extends ChangeEvent {
+    /**
+     * Reject the URL change, revert to previous URL.
+     */
+    reject: () => void;
+    /**
+     * Accept the URL change, continue navigation.
+     */
+    resolve: () => void;
+    /**
+     * Prevent the URL change, pause subsequent route processing.
+     */
+    prevent: () => void;
+}
+/**
+ * Route post-change event interface (changed phase).
+ * Carries route diff information. Triggered after route change is confirmed and URL is updated.
+ */
+export type RouteChangedEvent = LocationDiff & ChangeEvent;
+export interface DomRef {
+    /** ID update list: [element, newId][] */
+    idUpdates: [Element, string][];
+    /** Views that need post-processing */
+    views: ViewInterface[];
+    /** DOM operation list: [opCode, parent, newChild?, oldChild?][] */
+    domOps: DomOp[];
+    /** Whether anything changed */
+    hasChanged: number;
+}
+/**
+ * Encoded DOM mutation. The op code matches `Node.appendChild` family at the
+ * DOM level — parents are always Elements (you can't appendChild onto text)
+ * but the moving / replaced child can be any ChildNode (Element / Text /
+ * Comment), so the child slots are typed as ChildNode.
+ */
+export type DomOp = [1, Element, ChildNode] | [2, Element, ChildNode] | [4, Element, ChildNode, ChildNode] | [8, Element, ChildNode, ChildNode];
+/**
+ * Virtual DOM node. Produced by `vdomCreate`, consumed by the VDOM diff engine.
+ *
+ * Property semantics:
+ * - Text nodes: tag = 0 (V_TEXT_NODE), html = text content
+ * - Element nodes: tag = string, attrs = serialized opening tag, children = child VDomNodes
+ * - Raw HTML nodes: tag = SPLITTER (\x1e), html = raw HTML string
+ * - Self-closing: selfClose = true (children param was 1)
+ */
+export interface VDomNode {
+    /** Tag name for elements, 0 (V_TEXT_NODE) for text, SPLITTER for raw HTML */
+    tag: string | number;
+    /** Inner HTML (serialized children for elements, text content for text nodes) */
+    html: string;
+    /** Serialized opening tag with attributes, e.g. '<div class="row"' */
+    attrs?: string;
+    /** Attribute key-value map */
+    attrsMap?: Record<string, unknown>;
+    /** Attribute names that are set as DOM properties (not attributes) */
+    attrsSpecials?: Record<string, string>;
+    /** Original specials argument before defaulting (for change detection) */
+    hasSpecials?: Record<string, string> | undefined;
+    /** Child VDomNode array (undefined for text/raw/self-closing) */
+    children?: VDomNode[] | undefined;
+    /** Diff key: from id, #, or v-lark path */
+    compareKey?: string | undefined;
+    /** Keyed children count map (compareKey -> count) */
+    reused?: Record<string, number> | undefined;
+    /** Total count of keyed children */
+    reusedTotal?: number;
+    /** Sub-view references: [viewPath, owner, uri, params] tuples */
+    views?: [string, string, string, Record<string, string>][] | undefined;
+    /** Whether self-closing (children param was literal 1) */
+    selfClose?: boolean;
+    /** Sub-view path if this node hosts a v-lark view, otherwise falsy */
+    isLarkView?: string | undefined;
+}
+/**
+ * VDOM diff operation tracker. Parallel to DomRef but for the VDOM pipeline.
+ */
+export interface VDomRef {
+    /** View ID (for placeholder replacement) */
+    viewId: string;
+    /** Sub-views that need re-rendering after diff */
+    viewRenders: ViewInterface[];
+    /** Deferred DOM property assignments: [element, propName, value][] */
+    nodeProps: [Element, string, unknown][];
+    /** Pending async operation count */
+    asyncCount: number;
+    /** Whether the DOM actually changed */
+    changed: number;
+    /** DOM mutation operations (same format as DomOp) */
+    domOps: DomOp[];
+}
+/** VDOM node creation function signature (vdomCreate) */
+export type VDomCreateFn = (tag: string | number, props?: Record<string, unknown> | number | null, children?: VDomNode[] | number | null, specials?: Record<string, string>) => VDomNode;
+/**
+ * VDOM template function signature.
+ * The compiled template imports vdomCreate via ES module import and
+ * takes only (data, viewId, refData). Extra arguments are ignored.
+ */
+export type VDomTemplate = (data: unknown, viewId: string, refData: unknown) => VDomNode;
+export interface FrameInvokeEntry {
+    /** Method name */
+    name: string;
+    /** Method arguments */
+    args: unknown[];
+    /** Internal key */
+    key: string;
+    /** Whether removed (args match) */
+    removed?: boolean;
+}
+/** Mixin event handler with internal merge marker and handler list */
+export interface MixinEventHandler extends AnyFunc {
+    /** Merged handler list */
+    handlerList?: AnyFunc[];
+    /** Mixin marker: 1 = this is a mixin function */
+    marker?: number;
+}
+/** View event selector map entry: handler name list with selector presence tracking */
+export interface ViewEventSelectorEntry {
+    /** Selector name list */
+    selectors: string[];
+    /** Index signature for checking if selector is already registered */
+    [selector: string]: unknown;
+}
+/**
+ * Compiled template function signature.
+ * `data`/`viewId`/`refData` are required; subsequent encoder args are
+ * injected by the Updater (encodeHTML/encodeSafe/encodeURIExtra/refFn/encodeQ).
+ */
+export type ViewTemplate = (data: unknown, viewId: string, refData: unknown, ...encoders: unknown[]) => string;
+export interface ViewLocationObserved {
+    /** Whether observing location */
+    flag: number;
+    /** Keys to observe */
+    keys: string[];
+    /** Whether observing path */
+    observePath: boolean;
+}
+export interface ViewResourceEntry {
+    /** The resource entity */
+    entity: unknown;
+    /** Whether to destroy when render() is called */
+    destroyOnRender: boolean;
+}
+export interface ViewGlobalEventEntry {
+    /** Handler function */
+    handler: AnyFunc;
+    /** Bound handler wrapper (for removeEventListener) */
+    boundHandler?: AnyFunc;
+    /** DOM element (window/document) */
+    element: EventTarget;
+    /** Event name */
+    eventName: string;
+    /** Modifiers */
+    modifiers: Record<string, boolean>;
+}
+/**
+ * View configuration for listening to URL changes.
+ * Used as object parameter for `observeLocation()` method.
+ */
+export interface ViewObserveLocation {
+    /**
+     * Whether to listen for path changes.
+     */
+    observePath?: boolean;
+    /**
+     * Parameter keys to observe, supports comma-separated string or string array.
+     */
+    params?: string | string[];
+}
+/**
+ * Router interface providing URL parsing, navigation, diff, and event listening capabilities.
+ * Supports two-phase route confirmation mechanism: change (can reject) → changed.
+ * Hash-based implementation using #! as default hash prefix.
+ */
+export interface RouterInterface extends EventEmitterInterface<RouterInterface> {
+    /**
+     * Parse href into Location object.
+     * Parses query and hash sections of href, returns structured routing information.
+     * Defaults to parsing current page `location.href`.
+     * @param href URL to parse, uses `location.href` if not specified
+     */
+    parse(href?: string): Location;
+    /**
+     * Compute diff between current and previous location.
+     * Returns undefined if no routing changes have occurred yet.
+     */
+    diff(): LocationDiff | undefined;
+    /**
+     * Navigate to new URL.
+     * Supports two calling modes:
+     * - `Router.to("/list", { page: 2 })` specify path and params
+     * - `Router.to({ page: 2 })` update params only, keep current path
+     * @param pathOrParams Path string or params object
+     * @param params Query params object (only used when first arg is path string)
+     * @param replace Whether to replace current history entry instead of adding new one
+     * @param silent Whether to silently update without triggering change event
+     */
+    to(pathOrParams: string | Record<string, unknown>, params?: Record<string, unknown>, replace?: boolean, silent?: boolean): void;
+    /** Join path segments */
+    join(...paths: string[]): string;
+    /**
+     * Register an async-friendly navigation guard.
+     *
+     * Each guard is invoked with the parsed `(to, from)` Locations. Guards
+     * may return a Promise; the router awaits all guards in registration
+     * order. If any guard:
+     *
+     * - returns / resolves to `false`,
+     * - throws or rejects,
+     *
+     * the navigation is aborted and the URL is reverted. Returning `true`,
+     * `undefined`, or any non-false value permits the navigation.
+     *
+     * Returns an unsubscribe function so the guard can be torn down (e.g.
+     * inside a view's `destroy` handler).
+     */
+    beforeEach(guard: (to: Location, from: Location) => boolean | Promise<boolean>): () => void;
+    /** Internal: bind hashchange (called by Framework.boot) */
+    _bind(): void;
+    /** Internal: set framework config */
+    _setConfig(cfg: FrameworkConfig): void;
+    /** Internal: notify hash change (for programmatic trigger) */
+    notify?(e?: Event): void;
+    /**
+     * Triggered when URL is about to change (change phase), can reject or prevent navigation via event object.
+     */
+    onChange?: (e?: RouteChangeEvent) => void;
+    /**
+     * Triggered after URL has changed (changed phase), carries route diff information.
+     */
+    onChanged?: (e?: RouteChangedEvent) => void;
+}
+/**
+ * Service event interface, triggered when request starts or ends.
+ * Includes begin/done/fail/end event types.
+ */
+export interface ServiceEvent extends ChangeEvent {
+    /**
+     * Data payload object carrying this request's data.
+     */
+    readonly payload: PayloadInterface;
+    /**
+     * Error object, present if request throws an error, otherwise null.
+     */
+    readonly error: object | string | null;
+}
+/**
+ * View event interface carrying the ID of the node that triggered the event.
+ * Carried in DOM events bound via @event attribute.
+ */
+export interface ViewEvent extends ChangeEvent {
+    /**
+     * DOM node ID that triggered the event.
+     */
+    readonly id: string;
+}
+/**
+ * Frame static event interface carrying associated Frame instance.
+ * Carried in Frame's add/remove static events.
+ */
+export interface FrameStaticEvent extends ChangeEvent {
+    /**
+     * Associated Frame instance object.
+     */
+    readonly frame: FrameInterface;
+}
+export interface ViewInterface extends EventEmitterInterface<ViewInterface> {
+    /**
+     * View ID (same as owner frame ID),
+     * DOM node ID where current view resides.
+     */
+    id: string;
+    /**
+     * Owner frame,
+     * Frame instance holding current view.
+     * May be numeric placeholder 0 before view initialization completes.
+     * TODO: Migrate numeric placeholder 0 to undefined or null
+     */
+    owner: FrameInterface | number;
+    /**
+     * Updater instance managing view data binding and DOM rendering.
+     */
+    updater: UpdaterInterface;
+    /**
+     * Signature: > 0 means active, incremented on render, 0 = destroyed */
+    signature: number;
+    /** Whether rendered at least once */
+    rendered?: boolean;
+    /**
+     * View template function. Receives data + viewId + refData and a set of
+     * encoder helpers wired in by the Updater, and returns the rendered HTML.
+     */
+    template?: ViewTemplate | VDomTemplate;
+    /**
+     * Mixin object array for extending view functionality.
+     * Framework merges properties and methods from mixins into view prototype.
+     * Event method conflicts are automatically merged into sequential calls.
+     */
+    mixins?: Record<string, unknown>[];
+    /** Location observation config */
+    locationObserved: ViewLocationObserved;
+    /** Observed state keys */
+    observedStateKeys?: string[];
+    /** Resource map */
+    resources: Record<string, ViewResourceEntry>;
+    /** Selector event map: eventType -> selector list */
+    eventSelectorMap: Record<string, ViewEventSelectorEntry>;
+    /** Event object map: eventType -> bitmask */
+    eventObjectMap: Record<string, number>;
+    /** Global event list */
+    globalEventList: ViewGlobalEventEntry[];
+    /** Whether endUpdate has been called (1 = pending) */
+    endUpdatePending?: number;
+    /** Last rendered VDOM tree (only used when virtualDom is enabled) */
+    vdom?: VDomNode;
+    /** Render method (wrapped) */
+    render(): void;
+    /**
+     * Init method called after view is mounted.
+     * Used for initialization logic.
+     * Framework passes two arguments during actual invocation:
+     * - initParams: initialization parameter object
+     * - options: contains `node: Element` and `deep: boolean`
+     */
+    init(): void;
+    /** Wrapped render method */
+    renderMethod?: AnyFunc;
+    /** endUpdate pending flag */
+    endUpdatePendingFlag?: number;
+    /**
+     * Notify view that HTML update is about to begin for a specific region.
+     * Framework unmounts child Frames in that region to prevent DOM diff from operating on unmounted nodes.
+     * @param id Region node ID to update, defaults to current view
+     */
+    beginUpdate: (id?: string) => void;
+    /**
+     * Notify view that HTML update has completed for a specific region.
+     * Framework mounts child Frames in that region and executes deferred invoke queue.
+     * @param id Region node ID that finished updating, defaults to current view
+     * @param inner Whether this is an internal framework call
+     */
+    endUpdate: (id?: string, inner?: boolean) => void;
+    /**
+     * Wrap async callback to ensure it only executes if view is not destroyed.
+     * In SPAs, async callbacks (e.g., setTimeout, AJAX) may execute after view is destroyed,
+     * causing errors when manipulating DOM.
+     * After wrapping with `wrapAsync`, framework automatically checks view state and only executes callback if view is alive.
+     * @param fn Callback function to wrap
+     * @param context `this` binding for callback execution, defaults to view itself
+     */
+    wrapAsync: <Fn extends AnyFunc>(fn: Fn, context?: unknown) => (...args: Parameters<Fn>) => ReturnType<Fn> | undefined;
+    /**
+     * Listen for URL bar changes, supports two calling modes:
+     * - `observeLocation("page,size", true)` pass parameter keys (comma-separated) and whether to observe path
+     * - `observeLocation({ params: ["page", "size"], path: true })` pass config object
+     * View automatically re-renders when observed parameters or path change.
+     * @param params Parameter keys to observe, supports comma-separated string, string array, or config object
+     * @param observePath Whether to observe path changes
+     */
+    observeLocation: (params: string | string[] | Record<string, unknown>, observePath?: boolean) => void;
+    /**
+     * Observe data changes for specified keys in State.
+     * View automatically re-renders when observed keys are updated via `State.digest()`.
+     * @param keys Comma-separated key string or string array
+     */
+    observeState: (keys: string | string[]) => void;
+    /**
+     * Hand over resource to current view for lifecycle management.
+     * Framework automatically calls resource's destroy method at appropriate time when view unmounts or re-renders.
+     * @param key Unique key for managed resource; if key already manages different resource, old resource is auto-destroyed
+     * @param resource Resource object to manage
+     * @param destroyOnRender Whether to auto-destroy resource when render method is called; Service instances typically need auto-destroy on render
+     */
+    capture: (key: string, resource?: unknown, destroyOnRender?: boolean) => unknown;
+    /**
+     * Release managed resource, returns the resource object regardless of destruction state.
+     * @param key Managed resource key
+     * @param destroy Whether to destroy resource (call its destroy method), defaults to true
+     */
+    release: (key: string, destroy?: boolean) => unknown;
+    /**
+     * Set leave prompt, e.g., when form has unsaved changes.
+     * Can prompt user to choose between leaving directly or saving before leaving.
+     * Framework calls condition function during route changes (change phase) and page unloads (beforeunload).
+     * Navigation is prevented if condition returns true.
+     * @param message Leave prompt message
+     * @param condition Function to determine whether to show leave prompt; returns true to prevent navigation
+     */
+    leaveTip: (message: string, condition: () => boolean) => void;
+    /**
+     * Assign method for incremental DOM updates.
+     * Framework uses DOM diff (in-memory real DOM diff) to update only changed portions,
+     * automatically handling child view mounting and unmounting.
+     * Returns true if DOM changed, undefined if no change.
+     * @param options Incremental update config, used internally by framework
+     */
+    assign?: (options?: unknown) => boolean | undefined;
+    /**
+     * Triggered when view is destroyed.
+     */
+    onDestroy?: (e?: ChangeEvent) => void;
+    /**
+     * Triggered when render method is called.
+     */
+    onRender?: (e?: ChangeEvent) => void;
+    /**
+     * Inherit View to create new view subclass.
+     * Supports props.ctor constructor, props.mixins, and event methods (e.g., `'name<click>'`).
+     * @param props Prototype object containing init, render, and other methods
+     * @param statics Object of static methods or properties
+     */
+    extend?<TProps = object, TStatics = object>(props?: ExtendThisType<TProps & ViewInterface>, statics?: TStatics): ViewInterface & TStatics;
+    /**
+     * Merge multiple mixin objects into View prototype.
+     * Existing properties are not overwritten; event method conflicts are automatically merged into sequential calls.
+     * @param args Mixin object list
+     */
+    merge?(...args: ExtendThisType<ViewInterface>[]): ViewInterface;
+    navigate?: (path: string, params?: Record<string, unknown>) => void;
+}
+type ExtendThisType<T> = Record<string, unknown> & ThisType<T>;
+/**
+ * Minimal Frame interface needed by View.
+ * Frame (View Frame) is a view container managing view mount, unmount, and parent-child hierarchy.
+ * Each Frame corresponds to one DOM node, associated with view via v-lark attribute.
+ */
+export interface FrameInterface extends EventEmitterInterface<FrameInterface> {
+    /**
+     * DOM node ID where Frame resides.
+     */
+    id: string;
+    /**
+     * View module path currently rendered by this Frame, e.g., "app/views/default".
+     */
+    readonly viewPath?: string;
+    /**
+     * Parent Frame ID, undefined if this is a top-level Frame.
+     */
+    readonly parentId: string | undefined;
+    /**
+     * Mount view to current Frame.
+     * Framework loads view class, creates instance, and renders view.
+     * @param viewPath View module path, e.g., "app/views/default"
+     * @param viewInitParams Parameters passed during view initialization, accessible in view's init method
+     */
+    mountView(viewPath: string, viewInitParams?: Record<string, unknown>): void;
+    /**
+     * Unmount view from current Frame, triggers view's destroy event and cleans up resources.
+     */
+    unmountView(): void;
+    /**
+     * Mount child Frame on specified DOM node and render view.
+     * @param frameId DOM node ID for rendering
+     * @param viewPath View path
+     * @param viewInitParams Parameters passed during view initialization
+     */
+    mountFrame: (frameId: string, viewPath: string, viewInitParams?: Record<string, unknown>) => FrameInterface;
+    /**
+     * Unmount child Frame from specified DOM node.
+     * @param id DOM node ID, defaults to current Frame if omitted
+     */
+    unmountFrame: (id?: string) => void;
+    /**
+     * Render all child views under specified node (scans v-lark attributes and mounts).
+     * @param zoneId DOM node ID, defaults to current Frame
+     */
+    mountZone: (zoneId?: string) => void;
+    /**
+     * Unmount all child views under specified node.
+     * @param zoneId DOM node ID, defaults to current Frame
+     */
+    unmountZone: (zoneId?: string) => void;
+    /**
+     * Get ancestor Frame, defaults to parent Frame (level=1).
+     * @param level Levels to traverse upward, defaults to 1
+     */
+    parent(level?: number): FrameInterface | undefined;
+    /**
+     * Invoke specified method on view in current Frame.
+     * If view is not rendered yet, invocation is deferred until render completes.
+     * @param name Method name
+     * @param args Arguments array passed to method
+     */
+    invoke: (name: string, args?: unknown[]) => unknown;
+    /**
+     * Triggered when all descendant views have been created.
+     */
+    onCreated?: (e?: ChangeEvent) => void;
+    /**
+     * Triggered when descendant views change.
+     */
+    onAlter?: (e?: ChangeEvent) => void;
+    /**
+     * Get Frame instance by ID, returns undefined if not exists.
+     * @param id Frame's DOM node ID
+     */
+    get?(id: string): FrameInterface | undefined;
+    /**
+     * Get all Frame instances map for current page.
+     */
+    getAll?(): Map<string, FrameInterface>;
+    /**
+     * Triggered when Frame is created and registered.
+     */
+    onAdd?: (e?: FrameStaticEvent) => void;
+    /**
+     * Triggered when Frame is destroyed and unregistered.
+     */
+    onRemove?: (e?: FrameStaticEvent) => void;
+    view: ViewInterface | undefined;
+    /**
+     * Get ID array of all child Frames for current Frame.
+     * Note: ID positions in array are not fixed.
+     */
+    children: () => string[];
+    invokeList: FrameInvokeEntry[];
+}
+/**
+ * Minimal Updater interface needed by View.
+ * View updater responsible for view data binding and data/page updates.
+ * Each View instance has an Updater, triggering data/page updates via set/digest.
+ * Internally executes complete pipeline: template rendering → DOM diff (in-memory real DOM diff) → DOM operations.
+ */
+export interface UpdaterInterface {
+    /**
+     * Get data that has been set.
+     * Returns complete data object if key is omitted, otherwise returns value for specified key.
+     * @param key Data key name, omitted returns complete data object
+     */
+    get: <T = unknown>(key?: string) => T;
+    /**
+     * Set data and track changed keys.
+     * After set, must explicitly call `digest()` to commit changes to page.
+     * Returns this for chaining.
+     * @param data Data object, e.g., `{ a: 1, b: 2 }`
+     * @param excludes Set of keys to exclude from change tracking
+     */
+    set: (data: Record<string, unknown>, excludes?: ReadonlySet<string>) => UpdaterInterface;
+    /**
+     * Trigger page re-render.
+     * After set, must explicitly call `digest()` to commit changes to page.
+     * Internally executes complete pipeline: template rendering → DOM diff (in-memory real DOM diff) → DOM operations.
+     * @param data Optional data object, if provided calls `set()` first to set data
+     * @param excludes Set of keys to exclude from change tracking
+     * @param callback Callback executed after render completes
+     */
+    digest: (data?: Record<string, unknown>, excludes?: ReadonlySet<string>, callback?: () => void) => void;
+    /**
+     * Save a snapshot of current data for altered() detection.
+     * Works with `altered()` method to detect whether data has changed.
+     */
+    snapshot: () => UpdaterInterface;
+    /**
+     * Check if data has changed since last snapshot.
+     * Returns undefined if `snapshot()` has not been called.
+     */
+    altered: () => boolean | undefined;
+    /** Ref data for template rendering */
+    refData: Record<string, unknown>;
+    /**
+     * Translate raw reference data starting with @ symbol in template.
+     * Replaces `{{@refData}}` with actual value from refData.
+     * @param data Reference data to translate
+     */
+    translate(data: unknown): unknown;
+    /**
+     * Parse expression string.
+     * @param expr Expression string to parse
+     */
+    parse(expr: string): unknown;
+}
+/**
+ * Data payload interface wrapping API request response data, providing read/write methods.
+ * Payload instances are created internally by Service, developers access via all/one/save callbacks.
+ */
+export interface PayloadInterface {
+    /**
+     * Get data from Payload by key.
+     * @param key Data key name
+     */
+    get<T = unknown>(key: string): T;
+    /**
+     * Set data to Payload, supports three calling modes:
+     * - Key-value pair: `payload.set("name", "value")`
+     * - Data object: `payload.set({ name: "value" })`
+     * - Endpoint metadata object (for internal framework use)
+     * Returns this for chaining.
+     * @param keyOrData Key/value string, data object, or endpoint metadata object
+     * @param value Value when first parameter is a key
+     */
+    set(keyOrData: string | Record<string, unknown> | ServiceMetaEntry, value?: unknown): PayloadInterface;
+    data: Record<string, unknown>;
+    cacheInfo?: ServiceCacheInfo;
+}
+/**
+ * Change event object.
+ */
+export interface ChangeEvent {
+    /**
+     * Event type.
+     */
+    readonly type: string;
+    /**
+     * Set of changed data keys. Use `keys.has(name)` to check membership.
+     */
+    readonly keys?: ReadonlySet<string>;
+}
+/**
+ * Event emitter interface providing on/off/fire methods for publish-subscribe pattern.
+ */
+export interface EventEmitterInterface<T = unknown> {
+    /**
+     * Bind event listener, calls handler when event is triggered.
+     * @param name Event name
+     * @param fn Event handler function
+     */
+    on(name: string, fn: (this: T, e?: ChangeEvent) => void): EventEmitterInterface<T>;
+    /**
+     * Unbind event listener, removes all handlers for event if no handler function is provided.
+     * @param name Event name
+     * @param fn Optional event handler function, if omitted removes all handlers
+     */
+    off(name: string, fn?: AnyFunc): EventEmitterInterface<T>;
+    /**
+     * Fire event, executes all bound handlers, automatically adds type property to event data.
+     * Supports removing all handlers after firing.
+     * Supports executing handler list in reverse order.
+     * @param name Event name
+     * @param data Event data object
+     * @param remove Whether to remove all handlers after firing
+     * @param lastToFirst Whether to execute handler list in reverse order
+     */
+    fire(name: string, data?: Record<string, unknown>, remove?: boolean, lastToFirst?: boolean): EventEmitterInterface<T>;
+}
+/**
+ * Global state interface providing cross-view data sharing and data change notification capabilities.
+ * State is a singleton object managing app-level state data via get/set/digest.
+ * Supports `clean()` method to create a mixin for automatic cleanup on view destruction.
+ *
+ * Use State for SIMPLE cross-view data (lightweight shared values: counters,
+ * toggles, page title, session info, etc.). For COMPLEX reactive state —
+ * handlers, derived data, or fine-grained subscriptions — use `create` instead.
+ */
+export interface StateInterface extends EventEmitterInterface<StateInterface> {
+    /**
+     * Get data from global state, returns complete state object if key is omitted.
+     * @param key Data key name, omitted returns complete state object
+     */
+    get<T = unknown>(key?: string): T;
+    /**
+     * Set global state data.
+     * After set, must explicitly call `digest()` to dispatch changed event and notify views to update.
+     * @param data Data object, e.g., `{ a: 1, b: 2 }`
+     * @param excludes Set of keys to exclude from change tracking
+     */
+    set(data: Record<string, unknown>, excludes?: ReadonlySet<string>): this;
+    /**
+     * Clean data for specified keys in State, can only be used in view's mixins.
+     * For example `mixins: [State.clean("a,b")]`.
+     * Keys registered via this method are automatically cleaned when view is destroyed,
+     * and corresponding key reference counts are decremented; data is auto-deleted when count reaches zero.
+     * @param keys Comma-separated key string
+     * @returns Object with ctor method, called by mixins mechanism
+     */
+    clean(keys: string): {
+        ctor: AnyFunc;
+    };
+    /**
+     * Detect data changes and dispatch changed event.
+     * After set, must explicitly call `digest()` to dispatch changed event and notify views to update.
+     * @param data Optional data object, if provided calls `set()` first to set data
+     * @param excludes Set of keys to exclude from change tracking
+     */
+    digest(data?: Record<string, unknown>, excludes?: ReadonlySet<string>): void;
+    /**
+     * Get the set of keys changed in the most recent digest.
+     */
+    diff: () => ReadonlySet<string>;
+    onChanged?: (e?: ChangeEvent) => void;
+}
+export interface ServiceOptions {
+    /** Request URL */
+    url: string;
+    /** Request params */
+    params?: Record<string, unknown>;
+    /** HTTP method */
+    method?: "GET" | "POST" | "PUT" | "DELETE" | string;
+    /** Cache: true for default, number for TTL */
+    cache?: boolean | number;
+    /** POST data */
+    data?: unknown;
+}
+/** Pending cache entry for deduplication (internal to Service) */
+export interface PendingCacheEntry extends Array<unknown> {
+    /** Reference to the pending Payload entity */
+    entity?: unknown;
+}
+/**
+ * Endpoint metadata configuration for registering an API endpoint with Service.
+ * Each meta describes endpoint's URL, cache strategy, before/after interceptors, etc.
+ */
+export interface ServiceMetaEntry {
+    /**
+     * Endpoint name,
+     * Unique name for endpoint metadata, must be unique within same Service.
+     */
+    name: string;
+    /** Request URL, required. */
+    url: string;
+    /**
+     * Cache TTL in ms, 0 = no cache.
+     * Cache validity time in milliseconds.
+     * 0 means no caching.
+     * Greater than 0 means cache TTL, reuse cached data within this time range.
+     */
+    cache?: number;
+    /**
+     * Before-fetch hook,
+     * Hook function called before request is sent, can process request data.
+     * `this` points to current Payload instance.
+     * @param payload Data carrier for current request
+     */
+    before?: (this: PayloadInterface, payload: PayloadInterface) => void;
+    /**
+     * After-fetch hook.
+     * Hook function called after request succeeds, before data is passed to view.
+     * Can process response data in this method.
+     * `this` points to current Payload instance.
+     * @param payload Data carrier for current request
+     */
+    after?: (this: PayloadInterface, payload: PayloadInterface) => void;
+    /** Clean keys on destroy,
+     * Comma-separated endpoint name string for clearing other endpoints' cache.
+     * For example, if an endpoint creates new data,
+     * after successful call, should clear all data-fetching endpoints' cache,
+     * otherwise new data cannot be retrieved.
+     */
+    cleanKeys?: string;
+    /** Additional properties */
+    [key: string]: unknown;
+}
+/** Cache info attached to Payload entity */
+export interface ServiceCacheInfo {
+    /** Endpoint name */
+    name: string;
+    /** After-fetch hook */
+    after?: AnyFunc | undefined;
+    /** Clean keys */
+    cleans?: string | undefined;
+    /** Cache key */
+    key: string;
+    /** Timestamp when cached */
+    time: number;
+}
+export interface FrameworkInterface {
+    /**
+     * Read framework configuration.
+     * - Without arguments: returns the complete config object.
+     * - With a key: returns just `config[key]` (untyped — use a generic to
+     *   constrain the return type if you know the key's shape).
+     *
+     * `getConfig` is a pure read — call `setConfig(patch)` to mutate.
+     */
+    getConfig(): FrameworkConfig;
+    getConfig<T = unknown>(key: string): T | undefined;
+    /**
+     * Merge a patch into the framework configuration and return the merged
+     * config object.
+     */
+    setConfig<T extends object = Partial<FrameworkConfig>>(patch: Partial<FrameworkConfig> & T): FrameworkConfig & T;
+    /**
+     * App initialization entry point, starts framework and renders root view.
+     * After invocation: merge config → bind route events → create root Frame → mount default view.
+     * @param cfg Config object
+     */
+    boot(cfg: FrameworkConfig): void;
+    /**
+     * Convert array to hash map object.
+     * - Simple array: `Framework.toMap([1,2,3])` => `{1:1, 2:1, 3:1}`
+     * - Object array: `Framework.toMap([{id:20},{id:30}], 'id')` => `{20:{id:20}, 30:{id:30}}`
+     * @param list Source array
+     * @param key Use object's key value from array as map key
+     */
+    toMap<T>(list: T[] | null | undefined, key?: keyof T): Record<string, T | number>;
+    /**
+     * Execute methods in try-catch manner, catches exceptions.
+     * Returns return value of last successfully executed method.
+     * @param fns Function or function array
+     * @param args Arguments array passed to functions
+     * @param context `this` binding during function execution
+     * @param configError Optional error callback, receives the caught exception
+     */
+    toTry(fns: AnyFunc | AnyFunc[], args?: unknown[], context?: unknown, configError?: (e: unknown) => void): unknown;
+    /**
+     * Convert path and params to URL string.
+     * Example: `Framework.toUrl('/xxx/', {a:'b',c:'d'})` => `/xxx/?a=b&c=d`
+     * @param path Path string
+     * @param params Params object
+     * @param keepEmpty Set of keys whose empty values should be preserved
+     */
+    toUrl(path: string, params?: Record<string, unknown>, keepEmpty?: Set<string>): string;
+    /**
+     * Parse URL string to path and params object.
+     * Example: `Framework.parseUrl('/xxx/?a=b&c=d')` => `{path:'/xxx/', params:{a:'b',c:'d'}}`
+     * @param url URL string
+     */
+    parseUrl(url: string): ParsedUri;
+    /**
+     * Merge source object properties into target object.
+     * @param target Target object
+     * @param sources One or more source objects
+     */
+    mix<T extends object>(target: T, ...sources: Record<string, unknown>[]): T;
+    /**
+     * Check if object has specified own property (safe hasOwnProperty).
+     * @param owner Object to check, supports undefined/null
+     * @param prop Property key name
+     */
+    has<T extends object>(owner: T | undefined | null, prop: PropertyKey): boolean;
+    /**
+     * Get enumerable property keys of object as array.
+     * @param src Source object
+     */
+    keys<T extends object>(src: T): string[];
+    /**
+     * Check if one DOM node is contained within another.
+     * Returns true if both nodes are the same.
+     * @param node Node or node ID
+     * @param container Container node or node ID
+     */
+    inside(node: HTMLElement | string, container: HTMLElement | string): boolean;
+    /**
+     * Shorthand for document.getElementById.
+     * Returns directly if Element is passed.
+     * @param id Node ID or Element object
+     */
+    node(id: string | Element | null): Element | null;
+    /**
+     * Ensure DOM element has an ID, auto-generates one if missing.
+     * Returns element's ID.
+     * @param node DOM element object
+     */
+    nodeId(node: HTMLElement): string;
+    /**
+     * Load modules using configured module loader.
+     * @param names Module names, supports string or string array
+     * @param callback Callback after modules are loaded
+     */
+    use(names: string | string[], callback?: (...modules: unknown[]) => void): void;
+    /**
+     * Dynamically inject CSS styles into page. Returns cleanup function to remove injected styles.
+     * Supports single and batch injection.
+     * - `Framework.applyStyle("my-style", "body { color: red; }")` single injection
+     * - `Framework.applyStyle(["style1", "css1", "style2", "css2"])` batch injection
+     * @param styleIdOrPairs Style unique key or [id1, css1, id2, css2, ...] batch array
+     * @param cssText CSS style string (only used when first param is string)
+     */
+    applyStyle(styleIdOrPairs: string | string[], cssText?: string): () => void;
+    /**
+     * Generate globally unique identifier (GUID).
+     * @param prefix GUID prefix, defaults to "lark-"
+     */
+    guid(prefix?: string): string;
+    /**
+     * Create async callback validity marker.
+     * Returns a check function; if host object is unmarked (e.g., view re-rendered), check function returns false, preventing expired async callbacks from executing.
+     * Typical usage: `const check = Framework.mark(this, 'render'); setTimeout(() => { if (check()) ... })`
+     * @param host Host object (usually view instance)
+     * @param key Marker key name (usually "render" or specific async operation identifier)
+     */
+    mark(host: object, key: string): () => boolean;
+    /**
+     * Delay wait, Promise-based setTimeout wrapper.
+     * @param time Delay time in milliseconds
+     */
+    delay(time: number): Promise<void>;
+    /**
+     * Whether framework has booted
+     */
+    isBooted(): boolean;
+    /**
+     * Invalidate (unmark) async callback markers for a host object.
+     * Typically called when a view is re-rendered or destroyed.
+     * @param host The host object whose markers should be invalidated
+     */
+    unmark(host: object): void;
+    /**
+     * Fire a custom DOM event on a target element.
+     * @param target Target element or EventTarget
+     * @param eventType Event type string
+     * @param eventInit CustomEvent init options
+     */
+    dispatch(target: EventTarget, eventType: string, eventInit?: CustomEventInit): void;
+    /**
+     * Execute a function in try-catch with chunked scheduling.
+     * @param fn Function to execute
+     * @param args Arguments to pass
+     * @param context `this` context
+     */
+    task(fn: AnyFunc, args?: unknown[], context?: unknown): void;
+    /**
+     * Wait for all views in a zone to be rendered.
+     * Returns WAIT_OK if rendered, WAIT_TIMEOUT_OR_NOT_FOUND if timeout or not found.
+     * @param viewId Zone view ID
+     * @param timeout Timeout in milliseconds (default: 30000)
+     */
+    waitZoneViewsRendered(viewId: string, timeout?: number): Promise<number>;
+    /** Wait result: views rendered successfully */
+    WAIT_OK: number;
+    /** Wait result: timeout or view not found */
+    WAIT_TIMEOUT_OR_NOT_FOUND: number;
+    /**
+     * Base class with EventEmitter.
+     * Inherits EventEmitter for use as a base class in the framework.
+     */
+    Base: typeof import("./event-emitter").EventEmitter;
+    /**
+     * View class.
+     * Use `View.extend()` to create subclasses.
+     */
+    View: typeof import("./view").View;
+    /**
+     * Cache class.
+     * Use `new Cache()` to create cache instances.
+     */
+    Cache: typeof import("./cache").Cache;
+    /**
+     * Global state object.
+     */
+    State: StateInterface;
+    /**
+     * Router object.
+     */
+    Router: RouterInterface;
+    /**
+     * Frame class.
+     * Frame tree for view lifecycle management. Do not extend or instantiate directly.
+     */
+    Frame: typeof import("./frame").Frame;
+}
+/**
+ * Framework configuration interface, global config passed to app during `Framework.boot()`.
+ * All config items can be accessed at runtime via `Framework.getConfig('key')`.
+ */
+export interface FrameworkConfig {
+    /**
+     * Root element ID.
+     * DOM root node ID where root view resides, framework renders root view within this node.
+     * This field is required, defaults to "root".
+     */
+    rootId: string;
+    /**
+     * Routing mode.
+     * - `"history"` (default): uses `history.pushState` / `popstate`, clean URLs like `/home`
+     * - `"hash"`: uses URL hash fragment with `#!` prefix, e.g. `#!/home`
+     */
+    routeMode?: "history" | "hash";
+    /**
+     * Default view path.
+     * Default root view path to load when URL doesn't match any route.
+     */
+    defaultView?: string;
+    /**
+     * Default path when no hash present,
+     * Path used when URL hash is empty, defaults to "/".
+     */
+    defaultPath?: string;
+    /**
+     * Route mapping: path -> view.
+     * Mapping relationship between paths and views.
+     * - Simple mapping: `{ "/home": "app/views/home" }`
+     * - Config mapping: `{ "/detail": { view: "app/views/detail", title: "Detail" } }`
+     * Use rewrite config item for path rewriting logic.
+     */
+    routes?: Record<string, string | RouteViewConfig>;
+    /** Hashbang prefix (only used in hash mode) */
+    hashbang?: string;
+    /**
+     * Error handler.
+     * Global error handling function, framework uses try-catch to execute some core logic.
+     * When errors are thrown, allows developers to catch them via this config item.
+     * Note: Do not re-throw any errors in this method.
+     */
+    error?: (error: Error) => void;
+    /**
+     * Extensions to load.
+     * Array of extension view paths to load during app startup.
+     * These extension views are loaded before app initialization.
+     */
+    extensions?: string[];
+    /** Init module to load */
+    initModule?: string;
+    /** Rewrite function for routes */
+    rewrite?: (path: string, params: Record<string, string>, routes: Record<string, string>) => string;
+    /**
+     * Unmatched view (404).
+     * View path to use when no matching view is found in routes, e.g., 404 page.
+     */
+    unmatchedView?: string;
+    /**
+     * Module require function for asynchronous view loading.
+     * Called by `Framework.use()` when a view class is not found in the registry.
+     * Integrate with Webpack Module Federation or other dynamic loading strategies.
+     *
+     * @param names - Array of module names to load (e.g., `["remote-app/views/home"]`)
+     * @param params - Optional parameters passed to the module initializer
+     * @returns Promise resolving to an array of loaded modules, or undefined if not available
+     */
+    require?: (names: string[], params?: Record<string, unknown>) => Promise<unknown[]> | undefined;
+    /** Skip view rendered check */
+    skipViewRendered?: boolean;
+    /**
+     * Project name of the current application.
+     * Used by the micro-frontend bridge to determine if a view path
+     * belongs to the current project or a remote project.
+     */
+    projectName?: string;
+    /**
+     * Cross-site (micro-frontend) configuration list.
+     * Defines remote projects that can be loaded via Module Federation.
+     * Also accessible via `window.crossConfigs` for build-time injection.
+     */
+    crossConfigs?: CrossSiteConfig[];
+    /** Default false. */
+    virtualDom?: boolean;
+    /** Dynamic config access, custom config items */
+    [key: string]: unknown;
+}
+export interface RouteViewConfig {
+    /** View path */
+    view: string;
+    /** Additional properties merged into location */
+    [key: string]: unknown;
+}
+/**
+ * Configuration for a remote (cross-site) project in the micro-frontend setup.
+ * Each entry defines how to load views from a different project via Module Federation.
+ */
+export interface CrossSiteConfig {
+    /** Project name, used as the prefix in view paths (e.g., "remote-app" in "remote-app/views/home") */
+    projectName: string;
+    /**
+     * Remote source URL or Module Federation remote name.
+     * For Webpack MF: the remote entry URL (e.g., "remote_app@//cdn.example.com/remote-app/remoteEntry.js")
+     */
+    source: string;
+    /** Optional API host for the remote project */
+    apiHost?: string;
+    /** Optional business code for multi-tenant scenarios */
+    bizCode?: string;
+}
+/** Element with DOM diff cached compare key */
+export interface DomElement extends Element {
+    /** Whether compare key is cached */
+    compareKeyCached?: number | undefined;
+    /** Cached compare key */
+    cachedCompareKey?: string | undefined;
+    /** Whether auto-generated ID */
+    autoId?: number;
+}
+/** Element with frame binding */
+export interface FrameBoundElement extends HTMLElement {
+    /** Frame instance bound to this element */
+    frame?: FrameInterface;
+    /** Whether frame is bound (1 = bound) */
+    frameBound?: number;
+    /** View rendered flag */
+    viewRendered?: number;
+    /** Range frame ID */
+    rangeFrameId?: string;
+    /** Range element guid */
+    rangeElementGuid?: number;
+}
+/** Options for compileTemplate() */
+export interface CompileOptions {
+    /** Enable debug mode with line tracking (default: false) */
+    debug?: boolean;
+    /** Global variable names to destructure from $$ (refData) */
+    globalVars?: string[];
+    /** File path for debug error messages (default: undefined) */
+    file?: string;
+    /** Generate VDOM output instead of HTML string (default: false) */
+    virtualDom?: boolean;
+}
+export {};