chayns-api 3.0.1 → 3.1.0-beta.1

package/dist/types/handler/history/FrameHistoryLayer.d.ts

@@ -0,0 +1,99 @@
+import type { ChaynsHistoryLayer, ChaynsHistoryNavigateOptions, ChaynsHistoryNavigationCommitOptions, ChaynsHistoryBlockOptions, ChaynsHistoryLayerEvent, ChaynsHistoryActionResult } from '../../types/history';
+/**
+ * Async bridge functions forwarded via comlink from the iframe (FrameWrapper) to
+ * the parent window (HostIframe). All methods are async because they cross the
+ * comlink boundary.
+ *
+ * Callbacks that cross the boundary (addBlock) must be wrapped with
+ * `comlink.proxy()` by the caller (FrameWrapper.init) before being passed in.
+ */
+export interface HistoryBridgeFunctions {
+    setRoute(route: string | string[], opts?: ChaynsHistoryNavigateOptions): Promise<void>;
+    setParams(params: Record<string, string>, opts?: ChaynsHistoryNavigationCommitOptions): Promise<void>;
+    setHash(hash: string, opts?: ChaynsHistoryNavigationCommitOptions): Promise<void>;
+    setState(state: Record<string, unknown>, opts?: ChaynsHistoryNavigateOptions): Promise<void>;
+    navigate(opts: {
+        route?: string | string[];
+        state?: Record<string, unknown>;
+        activeChild?: string | null;
+        activeChildInit?: {
+            route?: string | string[];
+            state?: Record<string, unknown>;
+        };
+    } & ChaynsHistoryNavigateOptions): Promise<ChaynsHistoryActionResult>;
+    setActiveChild(id: string | null, init?: {
+        route?: string | string[];
+        state?: Record<string, unknown>;
+    }): Promise<ChaynsHistoryActionResult>;
+    setSegmentCount(n: number): Promise<void>;
+    /** Callback must be wrapped with comlink.proxy by FrameWrapper. Returns an async unsubscribe fn. */
+    addBlock(callback: () => Promise<boolean>, opts?: ChaynsHistoryBlockOptions): Promise<() => void>;
+}
+/** Snapshot of the host layer's state transferred to the frame at init time. */
+export interface HistoryInitialState {
+    id: string;
+    depth: number;
+    segments: string[];
+    params: Record<string, string>;
+    hash: string;
+    state: Record<string, unknown> | undefined;
+    activeChildId: string | null;
+    segmentCount: number;
+}
+/**
+ * A `ChaynsHistoryLayer` proxy that runs inside an iframe (FrameWrapper).
+ *
+ * - **Reads** are served from a local cache for synchronous access.
+ * - **Writes** are forwarded to the parent window via `bridge` functions.
+ * - The cache is kept in sync by `FrameWrapper.init()`, which sets up a single
+ *   comlink listener and calls `_applyAndEmit()` on every navigation event.
+ * - **Child layers** are not supported in the frame context — manage sub-routing
+ *   with a local `initRootChaynsHistoryLayer` inside the iframe instead.
+ */
+export declare class FrameHistoryLayer implements ChaynsHistoryLayer {
+    readonly id: string;
+    readonly depth: number;
+    private _segments;
+    private _params;
+    private _hash;
+    private _state;
+    private _activeChildId;
+    private _segmentCount;
+    private readonly bus;
+    private readonly bridge;
+    constructor(bridge: HistoryBridgeFunctions, initial: HistoryInitialState);
+    getSegmentCount(): number;
+    setSegmentCount(n: number): void;
+    createChildLayer(_id: string): ChaynsHistoryLayer;
+    destroyChildLayer(_id: string): void;
+    setActiveChild(id: string | null, init?: {
+        route?: string | string[];
+        state?: Record<string, unknown>;
+    }): Promise<ChaynsHistoryActionResult>;
+    getActiveChildId(): string | null;
+    getChildLayer(_id: string): ChaynsHistoryLayer | undefined;
+    getRoute(): string[];
+    setRoute(route: string | string[], opts?: ChaynsHistoryNavigateOptions): void;
+    getParams(): Record<string, string>;
+    setParams(params: Record<string, string>, opts?: ChaynsHistoryNavigationCommitOptions): void;
+    getHash(): string;
+    setHash(hash: string, opts?: ChaynsHistoryNavigationCommitOptions): void;
+    getState<T extends object = Record<string, unknown>>(): T | undefined;
+    setState(state: object, opts?: ChaynsHistoryNavigateOptions): void;
+    navigate(opts: {
+        route?: string | string[];
+        state?: Record<string, unknown>;
+        activeChild?: string | null;
+        activeChildInit?: {
+            route?: string | string[];
+            state?: Record<string, unknown>;
+        };
+    } & ChaynsHistoryNavigateOptions): Promise<ChaynsHistoryActionResult>;
+    addBlock(callback: () => Promise<boolean>, opts?: ChaynsHistoryBlockOptions): () => void;
+    addEventListener(type: 'popstate' | 'change', handler: (e: ChaynsHistoryLayerEvent) => void): () => void;
+    /**
+     * @internal Called by `FrameWrapper` when a navigation event arrives from the host.
+     * Updates the local cache and re-emits the event to all registered listeners.
+     */
+    _applyAndEmit(e: ChaynsHistoryLayerEvent): void;
+}

package/dist/types/handler/history/HistoryLayer.d.ts

@@ -0,0 +1,117 @@
+import type { ChaynsHistoryLayer as IChaynsHistoryLayer, ChaynsHistoryLayerEvent, ChaynsHistoryNavigateOptions, ChaynsHistoryNavigationCommitOptions, ChaynsHistoryBlockOptions, ChaynsHistoryActionResult } from '../../types/history';
+import type { NavigationQueue } from '../../utils/history/NavigationQueue';
+import type { BlockRegistry } from '../../utils/history/BlockRegistry';
+export interface ChaynsHistoryLayerDeps {
+    /** Reference to the root layer for queue + block registry access. */
+    getRoot: () => ChaynsHistoryLayer;
+    /** Top-window navigation queue (singleton). */
+    getQueue: () => NavigationQueue;
+    /** Top-window block registry (singleton). */
+    getBlockRegistry: () => BlockRegistry;
+}
+export interface ChaynsHistoryLayerInit {
+    id: string;
+    parent: ChaynsHistoryLayer | null;
+    deps: ChaynsHistoryLayerDeps;
+    segmentCount?: number;
+    /** Initial URL segments for this layer (length must equal segmentCount). */
+    segments?: string[];
+}
+export declare class ChaynsHistoryLayer implements IChaynsHistoryLayer {
+    readonly id: string;
+    readonly depth: number;
+    readonly parent: ChaynsHistoryLayer | null;
+    /** Insertion-ordered map of children. */
+    private readonly children;
+    /** Currently active child id (null = no child active). */
+    private activeChildId;
+    /** Number of URL segments this layer owns. */
+    private segmentCount;
+    /** This layer's own URL segments (length must equal segmentCount when active). */
+    private segments;
+    /** This layer's own state slice (without reserved keys). */
+    private ownState;
+    /** This layer's own query params. Merged with other active-chain layers when projecting URL. */
+    private _params;
+    /**
+     * This layer's own hash fragment (without `#`).
+     * `undefined` = never explicitly set (unset/no opinion).
+     * `''` = explicitly cleared.
+     * `'foo'` = explicitly set to `'foo'`.
+     */
+    private _hash;
+    /** Pub/sub for change + popstate events scoped to this layer. */
+    private readonly bus;
+    private readonly deps;
+    /** Lazily-resolved bootstrap URL segments. Null = not yet initialised. */
+    private _bootstrapPool;
+    /** Resolver called once on first consume to build the pool. */
+    private _bootstrapUrlResolver;
+    private isDestroyed;
+    constructor(init: ChaynsHistoryLayerInit);
+    getSegmentCount(): number;
+    setSegmentCount(n: number): void;
+    createChildLayer(id: string): ChaynsHistoryLayer;
+    destroyChildLayer(id: string): void;
+    getChildLayer(id: string): ChaynsHistoryLayer | undefined;
+    getActiveChildId(): string | null;
+    setActiveChild(id: string | null, init?: {
+        route?: string | string[];
+        state?: Record<string, unknown>;
+    }): Promise<ChaynsHistoryActionResult>;
+    getRoute(): string[];
+    setRoute(route: string | string[], opts?: ChaynsHistoryNavigateOptions): void;
+    getParams(): Record<string, string>;
+    setParams(params: Record<string, string>, opts?: ChaynsHistoryNavigationCommitOptions): void;
+    getHash(): string;
+    setHash(hash: string, opts?: ChaynsHistoryNavigationCommitOptions): void;
+    getState<T extends object = Record<string, unknown>>(): T | undefined;
+    setState<T extends object>(state: T, opts?: ChaynsHistoryNavigateOptions): void;
+    navigate(opts: {
+        route?: string | string[];
+        state?: Record<string, unknown>;
+        activeChild?: string | null;
+        activeChildInit?: {
+            route?: string | string[];
+            state?: Record<string, unknown>;
+        };
+    } & ChaynsHistoryNavigateOptions): Promise<ChaynsHistoryActionResult>;
+    addBlock(callback: () => Promise<boolean>, opts?: ChaynsHistoryBlockOptions): () => void;
+    addEventListener(type: 'popstate' | 'change', handler: (e: ChaynsHistoryLayerEvent) => void): () => void;
+    /** @internal */
+    _getOwnState(): Record<string, unknown>;
+    /** @internal */
+    _getOwnSegments(): string[];
+    /** @internal */
+    _getChildren(): ReadonlyMap<string, ChaynsHistoryLayer>;
+    /** @internal Apply mutated own state without firing events (used by projectors). */
+    _setOwnStateSilent(next: Record<string, unknown>): void;
+    /** @internal Apply mutated segments without firing events. */
+    _setOwnSegmentsSilent(next: string[]): void;
+    /** @internal */
+    _getOwnParams(): Record<string, string>;
+    /** @internal */
+    _setOwnParamsSilent(params: Record<string, string>): void;
+    /** @internal Returns the raw hash value (`undefined` = never set). */
+    _getOwnHash(): string | undefined;
+    /** @internal */
+    _setOwnHashSilent(hash: string | undefined): void;
+    /** @internal Set active child without enqueueing (used by projectors / queue processor). */
+    _setActiveChildSilent(id: string | null): void;
+    /** @internal Emit a typed event. Called by queue after diff confirms relevance. */
+    _emit(type: 'change' | 'popstate'): void;
+    /** @internal True if this layer is reachable via active chain from root. */
+    _isInActiveChain(): boolean;
+    /** @internal Register a lazy URL resolver (called once on first bootstrap consume). */
+    _setBootstrapUrlResolver(resolver: () => string): void;
+    /** @internal Set the bootstrap pool directly (overrides the lazy resolver). */
+    _setBootstrapPool(segs: string[]): void;
+    /** @internal Consume the next `n` segments from the bootstrap pool. Returns null if pool is exhausted or unset. */
+    _consumeBootstrapSegments(n: number): string[] | null;
+    /** @internal */
+    _isDestroyed(): boolean;
+    private markDestroyed;
+    private getCumulativeSegmentCount;
+    private static normalizeRoute;
+    private static filterReservedKeys;
+}

package/dist/types/handler/history/index.d.ts

@@ -0,0 +1,2 @@
+export { ChaynsHistoryLayer as ChaynsHistoryLayerClass } from './HistoryLayer';
+export { FrameHistoryLayer, type HistoryBridgeFunctions, type HistoryInitialState } from './FrameHistoryLayer';

package/dist/types/hooks/history.d.ts

@@ -0,0 +1,89 @@
+import type { ChaynsHistoryLayer, ChaynsHistoryNavigateOptions, ChaynsHistoryNavigationCommitOptions, ChaynsHistoryBlockOptions, ChaynsHistoryLayerEvent, ChaynsHistoryActionResult } from '../types/history';
+/**
+ * Resolves the active ChaynsHistoryLayer: context first, then
+ * `chaynsHost.history.getOwnLayer()` if available, then throws in dev.
+ */
+export declare function useChaynsHistoryLayer(): ChaynsHistoryLayer;
+export interface UseChaynsHistoryRouteResult {
+    segments: string[];
+    setRoute: (route: string | string[], opts?: ChaynsHistoryNavigateOptions) => void;
+}
+/**
+ * Returns the current route segments and a setter for the nearest ChaynsHistoryLayer.
+ * Re-renders only when the segments change.
+ */
+export declare function useChaynsHistoryRoute(): UseChaynsHistoryRouteResult;
+/**
+ * Returns the current layer state and a setter.
+ * Re-renders only when the own-state changes (shallow comparison performed by layer).
+ */
+export declare function useChaynsHistoryState<T extends object = Record<string, unknown>>(): [
+    T | undefined,
+    (state: T, opts?: ChaynsHistoryNavigateOptions) => void
+];
+/**
+ * Returns a stable `navigate` function for the nearest ChaynsHistoryLayer.
+ */
+export declare function useChaynsHistoryNavigate(): (opts: {
+    route?: string | string[];
+    state?: Record<string, unknown>;
+    /** Switch the active child as part of this navigation. Auto-creates the child if needed. */
+    activeChild?: string | null;
+    /** Initial route/state to seed the child with when it is first activated. */
+    activeChildInit?: {
+        route?: string | string[];
+        state?: Record<string, unknown>;
+    };
+} & ChaynsHistoryNavigateOptions) => Promise<ChaynsHistoryActionResult>;
+/**
+ * Returns the current query params and a setter for the nearest ChaynsHistoryLayer.
+ * Setter replaces all params on this layer; merge manually if needed:
+ * `setParams({ ...params, newKey: 'val' })`.
+ * Re-renders only when params change.
+ */
+export declare function useChaynsHistoryParams(): [
+    Record<string, string>,
+    (params: Record<string, string>, opts?: ChaynsHistoryNavigationCommitOptions) => void
+];
+/**
+ * Returns the current hash fragment (without `#`) and a setter for the nearest ChaynsHistoryLayer.
+ * Pass `''` to explicitly clear the hash.
+ * Re-renders only when the hash changes.
+ */
+export declare function useChaynsHistoryHash(): [string, (hash: string, opts?: ChaynsHistoryNavigationCommitOptions) => void];
+export interface UseChaynsHistoryBlockOptions extends ChaynsHistoryBlockOptions {
+    /** Only register the block when true. Default: true. */
+    isEnabled?: boolean;
+}
+/**
+ * Registers a navigation blocker. The callback must return a Promise<boolean>:
+ * true = allow, false = block.
+ *
+ * The caller is responsible for providing a stable `callback` reference
+ * (e.g. via useCallback) — registrations only change when the reference changes.
+ * `scope` and `isBeforeUnload` are read when the block is registered; changes
+ * after mount are applied on the next registration cycle.
+ */
+export declare function useChaynsHistoryBlock(callback: () => Promise<boolean>, opts?: UseChaynsHistoryBlockOptions): void;
+/**
+ * Low-level subscription to `change` or `popstate` events on the nearest layer.
+ */
+export declare function useChaynsHistoryEvent(type: 'change' | 'popstate', handler: (e: ChaynsHistoryLayerEvent) => void): void;
+/**
+ * Returns the child layer with the given id, creating it on mount if it
+ * doesn't already exist. Does NOT destroy the layer on unmount — the caller
+ * must explicitly call `layer.destroyChildLayer(id)` to remove it.
+ */
+export declare function useChaynsHistoryChildLayer(id: string): ChaynsHistoryLayer;
+export interface UseChaynsHistoryActiveChildResult {
+    activeChildId: string | null;
+    setActiveChild: (id: string | null, init?: {
+        route?: string[];
+        state?: Record<string, unknown>;
+    }) => void;
+}
+/**
+ * Returns the active child id of the nearest layer and a setter.
+ */
+export declare function useChaynsHistoryActiveChild(): UseChaynsHistoryActiveChildResult;
+export { ChaynsHistoryLayerProvider, useChaynsHistoryLayerContext } from '../contexts/HistoryLayerContext';

package/dist/types/hooks/index.d.ts

@@ -19,3 +19,4 @@ export { useCustomCallbackFunction } from './useCustomCallbackFunction';
 export { useCustomFunction } from './useCustomFunction';
 export { useStyleSettings } from './useStyleSettings';
 export { useChaynsApiId } from './useChaynsApiId';
+export { useChaynsHistoryLayer, useChaynsHistoryRoute, useChaynsHistoryParams, useChaynsHistoryHash, useChaynsHistoryState, useChaynsHistoryNavigate, useChaynsHistoryBlock, useChaynsHistoryEvent, useChaynsHistoryChildLayer, useChaynsHistoryActiveChild, type UseChaynsHistoryRouteResult, type UseChaynsHistoryActiveChildResult, type UseChaynsHistoryBlockOptions, } from './history';

package/dist/types/host/ChaynsHost.d.ts

@@ -1,6 +1,7 @@
 import React, { FC } from 'react';
 import { TypeSystem } from './module/ModuleHost';
 import { ChaynsApiDevice, ChaynsApiSite, ChaynsApiUser, ChaynsReactFunctions, ChaynsReactValues, IChaynsReact, Page } from '../types/IChaynsReact';
+import { ChaynsHistoryLayer } from '../types/history';
 type ChaynsHostType = {
     type: `${'client' | 'server'}-${'iframe' | 'module'}`;
     iFrameProps?: {
@@ -26,6 +27,17 @@ type ChaynsHostType = {
     preventStagingReplacement?: boolean;
     dialog: ChaynsReactValues["dialog"];
     styleSettings?: ChaynsReactValues["styleSettings"];
+    /** History layer to provide to hosted children. Defaults to the root layer. */
+    historyLayer?: ChaynsHistoryLayer;
+    /**
+     * ID for this module's dedicated child history layer.
+     * When set, a child layer with this ID is created (or reused) from the parent
+     * `historyLayer` and passed to the module — giving the module its own routing
+     * namespace. Activate it with `layer.navigate({ activeChild: historyChildId })`.
+     */
+    historyChildId?: string;
+    /** Whether the history is disabled for the children */
+    isHistoryDisabled?: boolean;
 } & ({
     type: `${'client' | 'server'}-iframe`;
     src: string;

package/dist/types/host/iframe/HostIframe.d.ts

@@ -1,5 +1,6 @@
 import React, { FC } from 'react';
 import { ChaynsApiDevice, ChaynsApiSite, ChaynsApiUser, ChaynsReactFunctions, ChaynsReactValues, IChaynsReact, Page } from '../../types/IChaynsReact';
+import type { ChaynsHistoryLayer } from '../../types/history';
 type HostIframeProps = {
     iFrameProps: {
         [key: string]: unknown;
@@ -23,6 +24,9 @@ type HostIframeProps = {
     preventStagingReplacement?: boolean;
     dialog: ChaynsReactValues["dialog"];
     styleSettings: ChaynsReactValues["styleSettings"];
+    historyLayer?: ChaynsHistoryLayer;
+    /** Whether the history is disabled for the children */
+    isHistoryDisabled?: boolean;
 };
 declare const HostIframe: FC<HostIframeProps>;
 export default HostIframe;

package/dist/types/host/module/ModuleHost.d.ts

@@ -1,5 +1,6 @@
 import { FC, ReactNode } from 'react';
 import { ChaynsApiDevice, ChaynsApiSite, ChaynsApiUser, ChaynsReactFunctions, ChaynsReactValues, IChaynsReact, Page } from '../../types/IChaynsReact';
+import type { ChaynsHistoryLayer } from '../../types/history';
 export type TypeSystem = {
     scope: string;
     url: string;
@@ -25,6 +26,9 @@ type ModulePropTypes = {
     dialog: ChaynsReactValues["dialog"];
     children?: ReactNode;
     styleSettings: ChaynsReactValues["styleSettings"];
+    historyLayer?: ChaynsHistoryLayer;
+    /** Whether the history is disabled for the children */
+    isHistoryDisabled?: boolean;
 };
 declare const ModuleHost: FC<ModulePropTypes>;
 export default ModuleHost;

package/dist/types/index.d.ts

@@ -1,21 +1,30 @@
 export { default as ChaynsProvider, type ChaynsProviderProps } from './components/ChaynsProvider';
-export { default as getDeviceInfo, getScreenSize, getClientDeviceInfo } from './util/deviceHelper';
+export { default as getDeviceInfo, getScreenSize, getClientDeviceInfo } from './utils/deviceHelper';
 export { default as ChaynsHost } from './host/ChaynsHost';
 export { withCompatMode } from './components/withCompatMode';
 export * from './calls';
 export * from './hooks';
 export * from './components/WaitUntil';
 export * from './types/IChaynsReact';
-export * from './util/is';
+export * from './types/history';
+export * from './utils/is';
 export * from './constants';
 export { default as withHydrationBoundary } from './components/withHydrationBoundary';
 export { default as StaticChaynsApi } from './wrapper/StaticChaynsApi';
 export { default as loadComponent, loadModule } from './host/module/utils/loadComponent';
 export { default as DialogHandler } from './handler/DialogHandler';
+export * from './handler/history';
+export { initRootChaynsHistoryLayer, getOrInitRootChaynsHistoryLayer, type InitRootChaynsHistoryLayerOptions, type InitRootChaynsHistoryLayerResult } from './utils/history/rootLayer';
+export { NavigationQueue } from './utils/history/NavigationQueue';
+export { BlockRegistry } from './utils/history/BlockRegistry';
+export { projectToUrl, parseFromUrl } from './utils/history/url';
+export { projectToState, applyStateToTree, diffIncomingState, hasChaynsHistoryState } from './utils/history/stateProjector';
+export { getChaynsHistoryActiveChain, findChaynsHistoryLayerById, isInChaynsHistoryActiveChain } from './utils/history/layerTree';
 export * as dialog from './calls/dialogs/index';
 export * from './plugins';
-export * from './util/initModuleFederationSharing';
-export * from './util/bindChaynsApi';
-export * from './util/appStorage';
-export * from './util/collectCssChunks';
+export * from './utils/initModuleFederationSharing';
+export * from './utils/bindChaynsApi';
+export * from './utils/appStorage';
+export * from './utils/collectCssChunks';
+export * from './contexts';
 export { getChaynsApi } from './components/moduleWrapper';

package/dist/types/types/IChaynsReact.d.ts

@@ -1,6 +1,7 @@
 import { IBrowser, IEngine } from 'ua-parser-js';
 import DialogHandler from '../handler/DialogHandler';
 import { DialogButtonOld, SelectDialogItem } from './dialog';
+import type { ChaynsHistoryLayer } from './history';
 export type DialogButton = {
     type: DialogButtonType;
     text: string;
@@ -311,6 +312,7 @@ export interface ChaynsReactValues {
     site: ChaynsApiSite;
     user: ChaynsApiUser | undefined;
     isAdminModeActive: boolean;
+    isHistoryDisabled?: boolean;
     pages: Page[];
     currentPage: {
         id: number;
@@ -465,6 +467,7 @@ export interface ChaynsReactFunctions {
         destination: string;
         isPermanent?: boolean;
     }) => Promise<void>;
+    getHistoryLayer(): ChaynsHistoryLayer;
 }
 export type ChaynsReactCustomFunctions = {
     [key: string]: (...args: any[]) => Promise<any>;

package/dist/types/types/history.d.ts

@@ -0,0 +1,74 @@
+export type ChaynsHistoryNavigationCommitOptions = {
+    isReplace?: boolean;
+};
+export type ChaynsHistoryNavigateOptions = ChaynsHistoryNavigationCommitOptions & {
+    /** Query parameters to set on this layer. Replaces existing params for this layer. */
+    params?: Record<string, string>;
+    /** URL hash fragment (without leading `#`). Pass `''` to explicitly clear. */
+    hash?: string;
+};
+export type ChaynsHistoryBlockOptions = {
+    /** @default 'local' */
+    scope?: 'local' | 'global';
+    /** @default false */
+    isBeforeUnload?: boolean;
+};
+export type ChaynsHistoryLayerEvent = {
+    type: 'change' | 'popstate';
+    layerId: string;
+    segments: string[];
+    state: Record<string, unknown>;
+    params: Record<string, string>;
+    hash: string;
+};
+export type ChaynsHistoryActionResult = {
+    isOk: true;
+} | {
+    isOk: false;
+    reason: 'blocked' | 'stale' | 'destroyed' | 'error';
+    error?: unknown;
+};
+export type ChaynsHistoryLayerStateNode = {
+    activeChild?: string;
+    childState?: ChaynsHistoryLayerStateNode;
+    /** @internal Reserved — managed by history core. */
+    __params?: Record<string, string>;
+    /** @internal Reserved — managed by history core. `undefined` = unset, `''` = explicit clear. */
+    __hash?: string;
+    [key: string]: unknown;
+};
+export interface ChaynsHistoryLayer {
+    readonly id: string;
+    readonly depth: number;
+    getSegmentCount(): number;
+    setSegmentCount(n: number): void;
+    createChildLayer(id: string): ChaynsHistoryLayer;
+    destroyChildLayer(id: string): void;
+    setActiveChild(id: string | null, init?: {
+        route?: string | string[];
+        state?: Record<string, unknown>;
+    }): Promise<ChaynsHistoryActionResult>;
+    getActiveChildId(): string | null;
+    getChildLayer(id: string): ChaynsHistoryLayer | undefined;
+    getRoute(): string[];
+    setRoute(route: string | string[], opts?: ChaynsHistoryNavigateOptions): void;
+    getParams(): Record<string, string>;
+    setParams(params: Record<string, string>, opts?: ChaynsHistoryNavigationCommitOptions): void;
+    getHash(): string;
+    setHash(hash: string, opts?: ChaynsHistoryNavigationCommitOptions): void;
+    getState<T extends object = Record<string, unknown>>(): T | undefined;
+    setState<T extends object>(state: T, opts?: ChaynsHistoryNavigateOptions): void;
+    navigate(opts: {
+        route?: string | string[];
+        state?: Record<string, unknown>;
+        /** Switch the active child as part of this navigation. Auto-creates the child if needed. */
+        activeChild?: string | null;
+        /** Initial route/state to seed the child with when it is first activated. */
+        activeChildInit?: {
+            route?: string | string[];
+            state?: Record<string, unknown>;
+        };
+    } & ChaynsHistoryNavigateOptions): Promise<ChaynsHistoryActionResult>;
+    addBlock(callback: () => Promise<boolean>, opts?: ChaynsHistoryBlockOptions): () => void;
+    addEventListener(type: 'popstate' | 'change', handler: (e: ChaynsHistoryLayerEvent) => void): () => void;
+}

package/dist/types/umd.index.d.ts

@@ -1,7 +1,7 @@
-export { default as getDeviceInfo, getScreenSize, getClientDeviceInfo } from './util/deviceHelper';
+export { default as getDeviceInfo, getScreenSize, getClientDeviceInfo } from './utils/deviceHelper';
 export * from './calls';
 export * from './types/IChaynsReact';
-export * from './util/is';
+export * from './utils/is';
 export { default as StaticChaynsApi } from './wrapper/StaticChaynsApi';
 export { default as DialogHandler } from './handler/DialogHandler';
 export * as dialog from './calls/dialogs/index';

package/dist/types/utils/EventBus.d.ts

@@ -0,0 +1,10 @@
+type Listener<E> = (event: E) => void;
+export declare class EventBus<E extends {
+    type: string;
+}> {
+    private listeners;
+    on(type: E['type'], handler: Listener<E>): () => void;
+    emit(type: E['type'], event: E): void;
+    clear(): void;
+}
+export {};

package/dist/types/{util → utils}/collectCssChunks.d.ts

@@ -1,4 +1,4 @@
-import { ModuleContextValueType } from '../constants';
+import { ModuleContextValueType } from '../contexts';
 /**
  * Collects the css chunks from all modules rendered during SSR
  * @experimental Handling for async chunks is not final and subject to change.

package/dist/types/utils/equality.d.ts

@@ -0,0 +1,2 @@
+export declare function shallowEqualArr(a: readonly unknown[], b: readonly unknown[]): boolean;
+export declare function shallowEqualObj(a: Record<string, unknown>, b: Record<string, unknown>): boolean;

package/dist/types/utils/history/BlockRegistry.d.ts

@@ -0,0 +1,45 @@
+import type { ChaynsHistoryLayer } from '../../handler/history/HistoryLayer';
+import type { ChaynsHistoryBlockOptions } from '../../types/history';
+interface BlockEntry {
+    readonly id: string;
+    readonly callback: () => Promise<boolean>;
+    readonly opts: Required<ChaynsHistoryBlockOptions>;
+}
+export declare class BlockRegistry {
+    /** Per-layer block list. */
+    private readonly layerBlocks;
+    private readonly changeListeners;
+    /** Number of blocks with `isBeforeUnload: true`. When > 0, listener is attached. */
+    private beforeUnloadCount;
+    private readonly beforeUnloadHandler;
+    add(layer: ChaynsHistoryLayer, callback: () => Promise<boolean>, opts?: ChaynsHistoryBlockOptions): () => void;
+    remove(layerId: string, entry: BlockEntry): void;
+    /** Remove all blocks registered for a layer (called on destroy). */
+    removeAllForLayer(layerId: string): void;
+    subscribeToChanges(listener: () => void): () => void;
+    /**
+     * Collects all blocks applicable to a navigation targeting `targetLayer`.
+     *
+     * Rules:
+     * - `local` blocks: only those registered on `targetLayer`.
+     * - `global` blocks: those registered on `targetLayer` or any of its
+     *   **active-chain descendants** (not inactive subtrees).
+     */
+    collectApplicableBlocks(targetLayer: ChaynsHistoryLayer): BlockEntry[];
+    hasActiveBlocks(rootLayer: ChaynsHistoryLayer): boolean;
+    checkActiveBlocks(rootLayer: ChaynsHistoryLayer): Promise<boolean>;
+    private collectActiveChainBlocks;
+    private collectGlobalFromActiveDescendants;
+    private collectFromActiveChain;
+    /**
+     * Runs all applicable block callbacks in parallel.
+     * Returns `true` if navigation is allowed (no block), `false` otherwise.
+     * Callbacks that throw or time out count as blocked (with dev-warn).
+     */
+    checkBlocks(targetLayer: ChaynsHistoryLayer): Promise<boolean>;
+    private runBlock;
+    private incrementBeforeUnload;
+    private decrementBeforeUnload;
+    private notifyChange;
+}
+export {};