chayns-api 3.0.0-beta.4 → 3.1.0-beta.0

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,38 @@
+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;
+    /** 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;
+    /**
+     * 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[];
+    private collectGlobalFromActiveDescendants;
+    /**
+     * 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;
+}
+export {};

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

@@ -0,0 +1,109 @@
+import type { ChaynsHistoryLayer } from '../../handler/history/HistoryLayer';
+import type { ChaynsHistoryActionResult, ChaynsHistoryNavigateOptions, ChaynsHistoryNavigationCommitOptions } from '../../types/history';
+export type NavOp = {
+    kind: 'setRoute';
+    layerId: string;
+    segments: string[];
+    opts: ChaynsHistoryNavigateOptions;
+    /** @internal Force a change notification even when segments appear unchanged (bootstrap via setSegmentCount). */
+    _notifyEvenIfUnchanged?: true;
+    /** @internal Notify subscribers without mutating the browser history (used for segment ownership/bootstrap updates). */
+    _skipCommit?: true;
+} | {
+    kind: 'setState';
+    layerId: string;
+    state: Record<string, unknown>;
+    opts: ChaynsHistoryNavigateOptions;
+} | {
+    kind: 'setParams';
+    layerId: string;
+    params: Record<string, string>;
+    opts: ChaynsHistoryNavigationCommitOptions;
+} | {
+    kind: 'setHash';
+    layerId: string;
+    hash: string;
+    opts: ChaynsHistoryNavigationCommitOptions;
+} | {
+    kind: 'setActiveChild';
+    layerId: string;
+    childId: string | null;
+    init?: {
+        route?: string[];
+        state?: Record<string, unknown>;
+    };
+} | {
+    kind: 'navigate';
+    layerId: string;
+    route?: string[];
+    state?: Record<string, unknown>;
+    params?: Record<string, string>;
+    hash?: string;
+    activeChild?: string | null;
+    activeChildInit?: {
+        route?: string[];
+        state?: Record<string, unknown>;
+    };
+    opts: ChaynsHistoryNavigationCommitOptions;
+} | {
+    kind: 'popstate';
+    rawState: unknown;
+};
+export type NavResult = ChaynsHistoryActionResult;
+export interface NavigationQueueDeps {
+    /** Returns root layer (top window only). */
+    getRoot: () => ChaynsHistoryLayer;
+    /** Find a layer by id starting at root. */
+    findLayer: (id: string) => ChaynsHistoryLayer | undefined;
+    /** Run the block check pipeline for a target layer. Returns true if free to proceed. */
+    checkBlocks: (target: ChaynsHistoryLayer) => Promise<boolean>;
+    /** Project the current memory tree into the URL string. */
+    projectUrl: () => string;
+    /** Project the current memory tree into the history state object (merged with existing foreign keys). */
+    projectState: () => Record<string, unknown>;
+    /**
+     * Compute which layer ids WOULD change without mutating the tree.
+     * Used to identify the block target before applying incoming state.
+     */
+    diffIncomingState: (raw: unknown) => {
+        changedLayerIds: Set<string>;
+    };
+    /** Apply an incoming raw `__chaynsHistory` state onto the memory tree. Returns affected layer ids. */
+    applyIncomingState: (raw: unknown) => {
+        changedLayerIds: Set<string>;
+    };
+    /** Move history without triggering our normal popstate handling (used to undo blocked navigations). */
+    silentGo: (delta: number) => Promise<void>;
+    /** Returns the current navigation index (incremented on every push). */
+    getCurrentIdx: () => number;
+    /** Increments the navigation index and returns the new value. */
+    incrementIdx: () => number;
+    /**
+     * Re-parse segments from `window.location.pathname` and apply them to each
+     * layer in the active chain based on its `segmentCount`. Called after
+     * `applyIncomingState` so the active chain reflects the new `activeChild`.
+     * Returns the ids of layers whose segments actually changed.
+     */
+    applyUrlSegments: () => {
+        changedLayerIds: Set<string>;
+    };
+}
+export declare class NavigationQueue {
+    private readonly queue;
+    private isRunning;
+    private readonly deps;
+    constructor(deps: NavigationQueueDeps);
+    enqueue(op: NavOp): Promise<NavResult>;
+    private tick;
+    private process;
+    private processSetRoute;
+    private processSetParams;
+    private processSetHash;
+    private processSetState;
+    private processSetActiveChild;
+    private processNavigate;
+    private processPopstate;
+    private resolveActiveLayer;
+    private resolveLowestCommonLayer;
+    private commit;
+}

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

@@ -0,0 +1,10 @@
+import type { ChaynsHistoryLayer } from '../../handler/history/HistoryLayer';
+/**
+ * Returns the ordered chain of layers from root to the deepest active layer
+ * (inclusive of root).
+ */
+export declare function getChaynsHistoryActiveChain(root: ChaynsHistoryLayer): ChaynsHistoryLayer[];
+/** Depth-first search for a layer by id starting at `root`. */
+export declare function findChaynsHistoryLayerById(root: ChaynsHistoryLayer, id: string): ChaynsHistoryLayer | undefined;
+/** Returns true if the layer is reachable via active children from the root. */
+export declare function isInChaynsHistoryActiveChain(layer: ChaynsHistoryLayer): boolean;

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

@@ -0,0 +1,14 @@
+/** Increment the current index (call on every real pushState). Returns the new value. */
+export declare function incrementIdx(): number;
+/** Get current index for stamping real entries or direction comparison. */
+export declare function getCurrentIdx(): number;
+/**
+ * Performs a `history.go(delta)` that is silently ignored by our popstate handler.
+ * Returns a promise that resolves when the popstate for this go() fires.
+ */
+export declare function silentGo(delta: number): Promise<void>;
+/**
+ * Called by the popstate handler. Returns true if this popstate is the silent one
+ * and should be suppressed.
+ */
+export declare function consumeSilent(): boolean;

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

@@ -0,0 +1,42 @@
+import { ChaynsHistoryLayer } from '../../handler/history/HistoryLayer';
+/** Parses the URL into a flat segment array and returns all entries after the first `startIndex` entries. */
+export declare function resolveSegmentsFrom(overrideUrl: string | undefined, startIndex: number): string[];
+export interface InitRootChaynsHistoryLayerOptions {
+    /**
+     * The current page URL used to seed initial route segments.
+     * - **Browser**: defaults to `window.location.pathname` — no need to set this.
+     * - **SSR**: pass the request URL (e.g. `req.url` or `router.asPath`) so
+     *   child layers receive the correct initial segments on the server.
+     */
+    url?: string;
+    /**
+     * Number of URL path segments the root layer owns.
+     * When provided, segments are resolved from the URL immediately at construction
+     * so that `getRoute()` is populated on the very first render.
+     */
+    segmentCount?: number;
+}
+export interface InitRootChaynsHistoryLayerResult {
+    rootLayer: ChaynsHistoryLayer;
+}
+/**
+ * Initializes the root ChaynsHistoryLayer for the top window.
+ * - Reads `window.location.pathname` and `window.history.state`.
+ * - If `__chaynsHistory` is absent, replaces the current state with an empty tree.
+ * - Attaches the global `popstate` listener.
+ * - Returns the root ChaynsHistoryLayer instance.
+ *
+ * Call once at application startup (top window only).
+ */
+export declare function initRootChaynsHistoryLayer(opts?: InitRootChaynsHistoryLayerOptions): InitRootChaynsHistoryLayerResult;
+/**
+ * Returns the singleton root ChaynsHistoryLayer for the current window.
+ * Creates it on first call; subsequent calls return the same instance.
+ *
+ * @param url - On SSR, pass the current request URL (e.g. `req.url` or `router.asPath`)
+ *   so child layers receive the correct initial route segments. Ignored after first call.
+ * @param segmentCount - Number of URL segments the root layer owns. When provided the
+ *   segments are resolved from the URL immediately so `getRoute()` is populated on the
+ *   very first render without any subsequent `setSegmentCount` call. Ignored after first call.
+ */
+export declare function getOrInitRootChaynsHistoryLayer(url?: string, segmentCount?: number): InitRootChaynsHistoryLayerResult;

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

@@ -0,0 +1,2 @@
+export declare const normalizeHistorySegments: (segments: string[]) => string[];
+export declare const normalizeHistoryRouteInput: (route: string | string[]) => string[];

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

@@ -0,0 +1,24 @@
+import type { ChaynsHistoryLayer } from '../../handler/history/HistoryLayer';
+import type { ChaynsHistoryLayerStateNode } from '../../types/history';
+/**
+ * Returns the value to store in `window.history.state`, merging with any
+ * pre-existing foreign keys so we never overwrite other consumers' state.
+ */
+export declare function projectToState(root: ChaynsHistoryLayer, existing?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Applies the raw `window.history.state` payload onto the layer tree.
+ * Returns the set of layer ids whose segments OR ownState changed.
+ */
+export declare function applyStateToTree(root: ChaynsHistoryLayer, raw: unknown): {
+    changedLayerIds: Set<string>;
+};
+/**
+ * Like `applyStateToTree` but does NOT mutate the tree.
+ * Returns layer ids that WOULD change if the state were applied.
+ */
+export declare function diffIncomingState(root: ChaynsHistoryLayer, raw: unknown): {
+    changedLayerIds: Set<string>;
+};
+declare function extractNode(raw: unknown): ChaynsHistoryLayerStateNode | null;
+export { extractNode as _extractNode };
+export declare function hasChaynsHistoryState(raw: unknown): boolean;

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

@@ -0,0 +1,17 @@
+import type { ChaynsHistoryLayer } from '../../handler/history/HistoryLayer';
+/**
+ * Concatenates all segments along the active chain into a URL with pathname,
+ * merged query params, and the deepest explicitly-set hash.
+ */
+export declare function projectToUrl(root: ChaynsHistoryLayer): string;
+export interface ParseResult {
+    /** Maps layer id → segments assigned to that layer. */
+    perLayerSegments: Map<string, string[]>;
+    /** Segments that could not be assigned to any layer's segmentCount. */
+    pendingSegments: string[];
+}
+/**
+ * Splits the incoming URL pathname onto layers based on each layer's `segmentCount`.
+ * Traverses the active chain; excess segments go to `pendingSegments`.
+ */
+export declare function parseFromUrl(url: string, root: ChaynsHistoryLayer): ParseResult;

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

@@ -0,0 +1 @@
+export declare function hasWindowHistory(): boolean;

package/dist/types/wrapper/FrameWrapper.d.ts

@@ -5,6 +5,7 @@ export declare class FrameWrapper implements IChaynsReact {
     private exposedCustomFunctions;
     private exposedCustomFunctionNames;
     private resizeListener;
+    private _historyLayer;
     ready: Promise<unknown>;
     values: ChaynsReactValues;
     chaynsApiId: string;

package/dist/types/wrapper/StaticChaynsApi.d.ts

@@ -64,6 +64,7 @@ declare class StaticChaynsApi implements ChaynsReactFunctions {
     addAccessTokenChangeListener: ChaynsReactFunctions['addAccessTokenChangeListener'];
     removeAccessTokenChangeListener: ChaynsReactFunctions['removeAccessTokenChangeListener'];
     redirect: ChaynsReactFunctions['redirect'];
+    getHistoryLayer: ChaynsReactFunctions['getHistoryLayer'];
     ready: Promise<void>;
     addDataListener: (cb: DataChangeCallback) => () => void;
     private _wrapper;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "chayns-api",
-    "version": "3.0.0-beta.4",
+    "version": "3.1.0-beta.0",
     "description": "new chayns api",
     "main": "dist/cjs/index.js",
     "module": "dist/esm/index.js",
@@ -74,6 +74,7 @@
         "chayns-toolkit": "^4.0.0-beta.0",
         "concurrently": "^9.2.1",
         "cross-env": "^10.1.0",
+        "jsdom": "^29.1.1",
         "prettier": "^3.7.4",
         "prettier-plugin-packagejson": "^2.5.20",
         "react": "^18.3.1",