chayns-api 3.0.0 → 3.1.0-beta.0

package/dist/esm/utils/history/stateProjector.js

@@ -0,0 +1,147 @@
+import { shallowEqualObj } from '../equality';
+const ROOT_KEY = '__chaynsHistory';
+const SCHEMA_VERSION = 1;
+function buildNode(layer) {
+  const node = {
+    ...layer._getOwnState()
+  };
+  const params = layer._getOwnParams();
+  if (Object.keys(params).length > 0) node.__params = {
+    ...params
+  };
+  const hash = layer._getOwnHash();
+  if (hash !== undefined) node.__hash = hash;
+  const activeChildId = layer.getActiveChildId();
+  if (activeChildId) {
+    node.activeChild = activeChildId;
+    const child = layer.getChildLayer(activeChildId);
+    if (child) {
+      node.childState = buildNode(child);
+    }
+  }
+  return node;
+}
+export function projectToState(root, existing = {}) {
+  const tree = buildNode(root);
+  return {
+    ...existing,
+    [ROOT_KEY]: {
+      v: SCHEMA_VERSION,
+      tree
+    }
+  };
+}
+function applyNode(layer, node) {
+  const {
+    activeChild,
+    childState,
+    __params,
+    __hash,
+    ...ownProps
+  } = node;
+  layer._setOwnStateSilent(ownProps);
+  layer._setOwnParamsSilent(__params !== null && __params !== void 0 ? __params : {});
+  layer._setOwnHashSilent('__hash' in node ? __hash : undefined);
+  if (activeChild !== undefined) {
+    layer._setActiveChildSilent(activeChild);
+    if (childState) {
+      const child = layer.getChildLayer(activeChild);
+      if (child) applyNode(child, childState);
+    }
+  } else {
+    layer._setActiveChildSilent(null);
+  }
+}
+export function applyStateToTree(root, raw) {
+  const node = extractNode(raw);
+  if (!node) return {
+    changedLayerIds: new Set()
+  };
+  const changedLayerIds = new Set();
+  applyNodeTracked(root, node, changedLayerIds);
+  return {
+    changedLayerIds
+  };
+}
+export function diffIncomingState(root, raw) {
+  const node = extractNode(raw);
+  if (!node) return {
+    changedLayerIds: new Set()
+  };
+  const changedLayerIds = new Set();
+  diffNodeTracked(root, node, changedLayerIds);
+  return {
+    changedLayerIds
+  };
+}
+function extractNode(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const entry = raw[ROOT_KEY];
+  if (!entry || typeof entry !== 'object') return null;
+  const {
+    tree
+  } = entry;
+  return tree !== null && tree !== void 0 ? tree : null;
+}
+function applyNodeTracked(layer, node, changed) {
+  const {
+    activeChild,
+    childState,
+    __params,
+    __hash,
+    ...ownProps
+  } = node;
+  const prevState = layer._getOwnState();
+  const prevActiveChild = layer.getActiveChildId();
+  const prevParams = layer._getOwnParams();
+  const prevHash = layer._getOwnHash();
+  const incomingParams = __params !== null && __params !== void 0 ? __params : {};
+  const incomingHash = '__hash' in node ? __hash : undefined;
+  const ownPropsClean = ownProps;
+  const stateChanged = !shallowEqualObj(prevState, ownPropsClean);
+  const activeChildChanged = prevActiveChild !== (activeChild !== null && activeChild !== void 0 ? activeChild : null);
+  const paramsChanged = !shallowEqualObj(prevParams, incomingParams);
+  const hashChanged = prevHash !== incomingHash;
+  const child = activeChild ? layer.getChildLayer(activeChild) : undefined;
+  layer._setOwnStateSilent(ownPropsClean);
+  layer._setActiveChildSilent(activeChild !== null && activeChild !== void 0 ? activeChild : null);
+  layer._setOwnParamsSilent(incomingParams);
+  layer._setOwnHashSilent(incomingHash);
+  if (stateChanged || activeChildChanged || paramsChanged || hashChanged) {
+    changed.add(layer.id);
+  }
+  if (activeChild && childState) {
+    if (child) applyNodeTracked(child, childState, changed);
+  }
+}
+function diffNodeTracked(layer, node, changed) {
+  const {
+    activeChild,
+    childState,
+    __params,
+    __hash,
+    ...ownProps
+  } = node;
+  const prevState = layer._getOwnState();
+  const prevActiveChild = layer.getActiveChildId();
+  const prevParams = layer._getOwnParams();
+  const prevHash = layer._getOwnHash();
+  const incomingParams = __params !== null && __params !== void 0 ? __params : {};
+  const incomingHash = '__hash' in node ? __hash : undefined;
+  const ownPropsClean = ownProps;
+  const stateChanged = !shallowEqualObj(prevState, ownPropsClean);
+  const activeChildChanged = prevActiveChild !== (activeChild !== null && activeChild !== void 0 ? activeChild : null);
+  const paramsChanged = !shallowEqualObj(prevParams, incomingParams);
+  const hashChanged = prevHash !== incomingHash;
+  const child = activeChild ? layer.getChildLayer(activeChild) : undefined;
+  if (stateChanged || activeChildChanged || paramsChanged || hashChanged) {
+    changed.add(layer.id);
+  }
+  if (activeChild && childState) {
+    if (child) diffNodeTracked(child, childState, changed);
+  }
+}
+export { extractNode as _extractNode };
+export function hasChaynsHistoryState(raw) {
+  return extractNode(raw) !== null;
+}

package/dist/esm/utils/history/url.js

@@ -0,0 +1,40 @@
+import { getChaynsHistoryActiveChain } from './layerTree';
+import { normalizeHistorySegments } from './segments';
+export function projectToUrl(root) {
+  const chain = getChaynsHistoryActiveChain(root);
+  const parts = [];
+  const mergedParams = {};
+  let hash;
+  for (const layer of chain) {
+    for (const seg of normalizeHistorySegments(layer._getOwnSegments())) {
+      parts.push(seg);
+    }
+    Object.assign(mergedParams, layer._getOwnParams());
+    const layerHash = layer._getOwnHash();
+    if (layerHash !== undefined) hash = layerHash;
+  }
+  let url = '/' + parts.join('/');
+  const search = new URLSearchParams(mergedParams).toString();
+  if (search) url += '?' + search;
+  if (hash) url += '#' + hash;
+  return url;
+}
+export function parseFromUrl(url, root) {
+  const perLayerSegments = new Map();
+  const pathname = url.startsWith('/') ? url.slice(1) : url;
+  const all = pathname ? pathname.split('/') : [];
+  let offset = 0;
+  const chain = getChaynsHistoryActiveChain(root);
+  for (const layer of chain) {
+    const count = layer.getSegmentCount();
+    const slice = all.slice(offset, offset + count);
+    while (slice.length < count) slice.push('');
+    perLayerSegments.set(layer.id, slice);
+    offset += count;
+  }
+  const pendingSegments = offset < all.length ? all.slice(offset) : [];
+  return {
+    perLayerSegments,
+    pendingSegments
+  };
+}

package/dist/esm/utils/history/window.js

@@ -0,0 +1,3 @@
+export function hasWindowHistory() {
+  return typeof window !== 'undefined' && typeof window.history !== 'undefined';
+}

package/dist/esm/wrapper/AppWrapper.js

@@ -7,12 +7,12 @@ import { sendMessageToGroup, sendMessageToPage, sendMessageToUser } from '../cal
 import { DefaultLoginDialogOptions } from '../constants';
 import { DeviceLanguage } from '../constants/languages';
 import DialogHandler from '../handler/DialogHandler';
-import { addApiListener, dispatchApiEvent, removeApiListener } from '../helper/apiListenerHelper';
+import { addApiListener, dispatchApiEvent, removeApiListener } from '../utils/apiListener';
 import { AppName, DialogButtonType, DialogType, Environment, Font, Gender, IconType, LoginState, RuntimeEnviroment, TappEvent } from '../types/IChaynsReact';
-import invokeAppCall from '../util/appCall';
-import { addAppStorageListener, clearAppStorage, isAppStorageAvailable, setAppStorageItem } from '../util/appStorage';
-import getDeviceInfo, { getScreenSize } from '../util/deviceHelper';
-import { isAppCallSupported } from '../util/is';
+import invokeAppCall from '../utils/appCall';
+import { addAppStorageListener, clearAppStorage, isAppStorageAvailable, setAppStorageItem } from '../utils/appStorage';
+import getDeviceInfo, { getScreenSize } from '../utils/deviceHelper';
+import { isAppCallSupported } from '../utils/is';
 export class AppWrapper {
   async loadStyleSettings(siteId) {
     try {

package/dist/esm/wrapper/FrameWrapper.js

@@ -6,8 +6,9 @@ import getUserInfo from '../calls/getUserInfo';
 import { sendMessageToGroup, sendMessageToPage, sendMessageToUser } from '../calls/sendMessage';
 import { addVisibilityChangeListener, removeVisibilityChangeListener } from '../calls/visibilityChangeListener';
 import DialogHandler from '../handler/DialogHandler';
-import { setTappHeight } from '../util/heightHelper';
-import { initTransferNestedFunctions } from '../util/transferNestedFunctions';
+import { FrameHistoryLayer } from '../handler/history/FrameHistoryLayer';
+import { setTappHeight } from '../utils/heightHelper';
+import { initTransferNestedFunctions } from '../utils/transferNestedFunctions';
 export class FrameWrapper {
   constructor() {
     _defineProperty(this, "resolve", null);
@@ -15,6 +16,7 @@ export class FrameWrapper {
     _defineProperty(this, "exposedCustomFunctions", {});
     _defineProperty(this, "exposedCustomFunctionNames", []);
     _defineProperty(this, "resizeListener", null);
+    _defineProperty(this, "_historyLayer", null);
     _defineProperty(this, "ready", new Promise(res => {
       this.resolve = res;
     }));
@@ -297,6 +299,12 @@ export class FrameWrapper {
       redirect: async options => {
         if (!this.initialized) await this.ready;
         return this.exposedFunctions.redirect(options);
+      },
+      getHistoryLayer: () => {
+        if (!this._historyLayer) {
+          throw new Error('[chaynsHistory] No history layer available. Ensure historyLayer prop is set on the parent HostIframe.');
+        }
+        return this._historyLayer;
       }
     });
     _defineProperty(this, "customFunctions", new Proxy({}, {
@@ -365,6 +373,31 @@ export class FrameWrapper {
       p[e] = (...args) => this.exposedCustomFunctions[e](...args.map(a => typeof a === 'function' ? comlink.proxy(a) : a));
       return p;
     }, {});
+    const exposedHistory = exposed.history;
+    if (exposedHistory) {
+      const initialState = await exposedHistory.getInitialState();
+      if (initialState) {
+        this._historyLayer = new FrameHistoryLayer({
+          setRoute: (route, opts) => exposedHistory.setRoute(route, opts),
+          setParams: (params, opts) => exposedHistory.setParams(params, opts),
+          setHash: (hash, opts) => exposedHistory.setHash(hash, opts),
+          setState: (state, opts) => exposedHistory.setState(state, opts),
+          navigate: opts => exposedHistory.navigate(opts),
+          setActiveChild: (id, init) => exposedHistory.setActiveChild(id, init),
+          setSegmentCount: n => exposedHistory.setSegmentCount(n),
+          addBlock: async (callback, opts) => {
+            const remoteUnsub = await exposedHistory.addBlock(comlink.proxy(callback), opts);
+            return () => void remoteUnsub();
+          }
+        }, initialState);
+        await exposedHistory.addChangeListener(comlink.proxy(e => {
+          this._historyLayer._applyAndEmit(e);
+        }));
+        await exposedHistory.addPopstateListener(comlink.proxy(e => {
+          this._historyLayer._applyAndEmit(e);
+        }));
+      }
+    }
     this.initialized = true;
     this.resolve(null);
     setTappHeight(this.functions.setHeight);

package/dist/esm/wrapper/ModuleFederationWrapper.js

@@ -2,6 +2,7 @@ function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object
 function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
 function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
 import DialogHandler from '../handler/DialogHandler';
+import { getOrInitRootChaynsHistoryLayer } from '../utils/history/rootLayer';
 import { addVisibilityChangeListener, removeVisibilityChangeListener } from '../calls/visibilityChangeListener';
 import getUserInfo from '../calls/getUserInfo';
 import { sendMessageToGroup, sendMessageToPage, sendMessageToUser } from '../calls/sendMessage';
@@ -38,6 +39,7 @@ export class ModuleFederationWrapper {
     this.functions.createDialog = config => {
       return new DialogHandler(config, functions.openDialog, functions.closeDialog, functions.dispatchEventToDialogClient, functions.addDialogClientEventListener);
     };
+    this.functions.getHistoryLayer = () => getOrInitRootChaynsHistoryLayer().rootLayer;
   }
   async init() {
     return undefined;

package/dist/esm/wrapper/StaticChaynsApi.js

@@ -3,7 +3,7 @@ function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol"
 function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
 import { moduleWrapper } from '../components/moduleWrapper';
 import { AppFlavor } from '../types/IChaynsReact';
-import getDeviceInfo from '../util/deviceHelper';
+import getDeviceInfo from '../utils/deviceHelper';
 import { AppWrapper } from './AppWrapper';
 import { FrameWrapper } from './FrameWrapper';
 import { ModuleFederationWrapper } from './ModuleFederationWrapper';
@@ -74,6 +74,7 @@ class StaticChaynsApi {
     _defineProperty(this, "addAccessTokenChangeListener", void 0);
     _defineProperty(this, "removeAccessTokenChangeListener", void 0);
     _defineProperty(this, "redirect", void 0);
+    _defineProperty(this, "getHistoryLayer", void 0);
     _defineProperty(this, "ready", void 0);
     _defineProperty(this, "addDataListener", void 0);
     _defineProperty(this, "_wrapper", void 0);

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

@@ -227,6 +227,11 @@ export declare const addAnonymousAccount: () => Promise<import("../types/IChayns
  * @category User functions
  */
 export declare const getUser: () => import("../types/IChaynsReact").ChaynsApiUser | undefined;
+/**
+ * Returns the innermost currently mounted HistoryLayer. Falls back to the
+ * root layer when called outside any HistoryLayerProvider.
+ */
+export declare const getChaynsHistoryLayer: () => import("..").ChaynsHistoryLayer | null;
 export declare const getSite: () => ChaynsApiSite;
 export declare const getCurrentPage: () => {
     id: number;

package/dist/types/components/ChaynsProvider.d.ts

@@ -1,5 +1,6 @@
 import React, { ReactNode } from 'react';
 import { ChaynsReactFunctions, ChaynsReactValues, IChaynsReact } from '../types/IChaynsReact';
+import type { ChaynsHistoryLayer } from '../types/history';
 export type ChaynsProviderProps = {
     data?: ChaynsReactValues;
     functions?: ChaynsReactFunctions;
@@ -8,6 +9,26 @@ export type ChaynsProviderProps = {
     isModule?: boolean;
     children?: ReactNode;
     chaynsApiId?: string;
+    /**
+     * Explicit history layer to provide to the React subtree.
+     * When set this layer is used directly and no root layer is auto-initialised.
+     * Use this when the parent already owns a layer and wants to scope children to it.
+     */
+    historyLayer?: ChaynsHistoryLayer;
+    /**
+     * Initial history configuration for the root layer.
+     * Ignored when `layer` is provided explicitly.
+     * - `url`: Current page URL — browser defaults to `window.location.pathname`;
+     *   for SSR pass the request URL (e.g. `req.url` or `router.asPath`).
+     * - `segmentCount`: Number of URL path segments this application claims.
+     *   E.g. `segmentCount: 2` on `/shop/products/detail` → `getLayer().getRoute()` → `['shop', 'products']`.
+     */
+    history?: {
+        url?: string;
+        segmentCount?: number;
+    };
+    segmentCount?: number;
+    isHistoryDisabled?: boolean;
 };
 declare const ChaynsProvider: React.FC<ChaynsProviderProps>;
 export default ChaynsProvider;

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

@@ -1,3 +1 @@
-export * from './hydrationContext';
 export * from './DefaultLoginDialogOptions';
-export * from './moduleContext';

package/dist/types/contexts/HistoryLayerContext.d.ts

@@ -0,0 +1,33 @@
+import React, { type FC, type ReactNode } from 'react';
+import type { ChaynsHistoryLayer } from '../types/history';
+export declare function pushChaynsHistoryLayer(layer: ChaynsHistoryLayer): void;
+export declare function popChaynsHistoryLayer(layer: ChaynsHistoryLayer): void;
+/** Returns the innermost currently mounted ChaynsHistoryLayer, or the root layer as fallback. */
+export declare function getCurrentChaynsHistoryLayer(): ChaynsHistoryLayer | null;
+declare const ChaynsHistoryLayerContext: React.Context<ChaynsHistoryLayer | null>;
+export interface ChaynsHistoryLayerProviderProps {
+    layer: ChaynsHistoryLayer;
+    children: ReactNode;
+}
+/**
+ * Provides a ChaynsHistoryLayer to the React subtree **and** registers it on the
+ * module-level layer stack so that `getCurrentChaynsHistoryLayer()` (static / non-React
+ * call sites) also sees this layer as the current one.
+ *
+ * Use `ChaynsHistoryLayerOverrideProvider` instead if you only want to override the
+ * React context without affecting static call sites.
+ */
+export declare const ChaynsHistoryLayerProvider: FC<ChaynsHistoryLayerProviderProps>;
+/**
+ * Overrides the ChaynsHistoryLayer for the React subtree **only** — hooks such as
+ * `useChaynsHistoryLayer`, `useChaynsHistoryRoute`, `useChaynsHistoryNavigate`, etc. will resolve to the
+ * provided `layer`, but `getCurrentChaynsHistoryLayer()` (the static / non-React accessor
+ * that reads from the module-level layer stack) is left unchanged.
+ *
+ * This is useful when you need to scope history to a specific layer inside a
+ * React tree without affecting imperative call sites outside that tree.
+ */
+export declare const ChaynsHistoryLayerOverrideProvider: FC<ChaynsHistoryLayerProviderProps>;
+/** Returns the nearest ChaynsHistoryLayer from context, or null if none. */
+export declare function useChaynsHistoryLayerContext(): ChaynsHistoryLayer | null;
+export default ChaynsHistoryLayerContext;

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

@@ -0,0 +1,3 @@
+export * from './hydrationContext';
+export * from './moduleContext';
+export * from './HistoryLayerContext';

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';