chayns-api 3.0.1 → 3.1.0-beta.1

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

@@ -0,0 +1,205 @@
+import { ChaynsHistoryLayer } from '../../handler/history/HistoryLayer';
+import { NavigationQueue } from './NavigationQueue';
+import { BlockRegistry } from './BlockRegistry';
+import { findChaynsHistoryLayerById } from './layerTree';
+import { projectToUrl, parseFromUrl } from './url';
+import { projectToState, applyStateToTree, diffIncomingState, hasChaynsHistoryState } from './stateProjector';
+import { silentGo, consumeSilent, incrementIdx, getCurrentIdx, syncCurrentIdxFromState } from './navigationIndex';
+import { hasWindowHistory } from './window';
+import { shallowEqualArr } from '../equality';
+import { getSite } from '../../calls';
+import { normalizeHistorySegments } from './segments';
+import { NativeBackHandler } from './nativeBackHandling';
+function getInitialPathname(overrideUrl) {
+  if (overrideUrl) {
+    try {
+      return new URL(overrideUrl).pathname;
+    } catch {}
+    return overrideUrl.startsWith('/') ? overrideUrl : `/${overrideUrl}`;
+  }
+  if (hasWindowHistory()) {
+    return window.location.pathname;
+  }
+  try {
+    const siteUrl = getSite().url;
+    if (siteUrl) return new URL(siteUrl).pathname;
+  } catch {}
+  return '/';
+}
+function resolveInitialSegments(overrideUrl, n) {
+  const pathname = getInitialPathname(overrideUrl);
+  const all = pathname.replace(/^\//, '').split('/').filter(Boolean);
+  const taken = all.slice(0, n);
+  while (taken.length < n) taken.push('');
+  return taken;
+}
+export function resolveSegmentsFrom(overrideUrl, startIndex) {
+  const pathname = getInitialPathname(overrideUrl);
+  const all = pathname.replace(/^\//, '').split('/').filter(Boolean);
+  return all.slice(startIndex);
+}
+export function initRootChaynsHistoryLayer(opts = {}) {
+  var _opts$segmentCount;
+  const blockRegistry = new BlockRegistry();
+  let queueRef = null;
+  const deps = {
+    getRoot: () => rootLayer,
+    getQueue: () => {
+      if (!queueRef) {
+        throw new Error('[chaynsHistory] NavigationQueue not initialized yet.');
+      }
+      return queueRef;
+    },
+    getBlockRegistry: () => blockRegistry
+  };
+  const rootLayer = new ChaynsHistoryLayer({
+    id: 'root',
+    parent: null,
+    deps,
+    segmentCount: (_opts$segmentCount = opts.segmentCount) !== null && _opts$segmentCount !== void 0 ? _opts$segmentCount : 0,
+    segments: opts.segmentCount ? resolveInitialSegments(opts.url, opts.segmentCount) : []
+  });
+  const nativeBackHandler = new NativeBackHandler({
+    rootLayer,
+    blockRegistry
+  });
+  const syncNativeHandling = nativeBackHandler.sync;
+  const queue = new NavigationQueue({
+    getRoot: () => rootLayer,
+    findLayer: id => findChaynsHistoryLayerById(rootLayer, id),
+    checkBlocks: target => blockRegistry.checkBlocks(target),
+    projectUrl: () => projectToUrl(rootLayer),
+    projectState: () => {
+      var _ref;
+      const existing = hasWindowHistory() ? {
+        ...((_ref = window.history.state) !== null && _ref !== void 0 ? _ref : {})
+      } : {};
+      delete existing.__chaynsHistory;
+      return projectToState(rootLayer, existing);
+    },
+    diffIncomingState: raw => diffIncomingState(rootLayer, raw),
+    applyIncomingState: raw => applyStateToTree(rootLayer, raw),
+    silentGo: delta => silentGo(delta),
+    getCurrentIdx: () => getCurrentIdx(),
+    incrementIdx: () => incrementIdx(),
+    onCommit: syncNativeHandling,
+    applyUrlSegments: () => {
+      if (!hasWindowHistory()) return {
+        changedLayerIds: new Set()
+      };
+      const {
+        perLayerSegments
+      } = parseFromUrl(window.location.pathname, rootLayer);
+      const changed = new Set();
+      for (const [id, segs] of perLayerSegments) {
+        const layer = findChaynsHistoryLayerById(rootLayer, id);
+        if (!layer) continue;
+        const normalizedSegs = normalizeHistorySegments(segs);
+        const prev = layer._getOwnSegments();
+        if (!shallowEqualArr(prev, normalizedSegs)) {
+          layer._setOwnSegmentsSilent(normalizedSegs);
+          changed.add(id);
+        }
+      }
+      return {
+        changedLayerIds: changed
+      };
+    }
+  });
+  queueRef = queue;
+  const existingState = hasWindowHistory() ? window.history.state : null;
+  syncCurrentIdxFromState(existingState);
+  if (!hasChaynsHistoryState(existingState)) {
+    var _opts$segmentCount2, _opts$url;
+    const segmentCount = (_opts$segmentCount2 = opts.segmentCount) !== null && _opts$segmentCount2 !== void 0 ? _opts$segmentCount2 : 0;
+    if (segmentCount > 0) {
+      const pathname = getInitialPathname(opts.url);
+      const all = pathname.replace(/^\//, '').split('/').filter(Boolean);
+      rootLayer._setBootstrapPool(all.slice(segmentCount));
+    } else {
+      rootLayer._setBootstrapUrlResolver(() => getInitialPathname(opts.url));
+    }
+    const rawUrl = (_opts$url = opts.url) !== null && _opts$url !== void 0 ? _opts$url : hasWindowHistory() ? window.location.href : null;
+    if (rawUrl) {
+      try {
+        const base = rawUrl.startsWith('http') ? rawUrl : `http://x${rawUrl.startsWith('/') ? rawUrl : '/' + rawUrl}`;
+        const parsed = new URL(base);
+        const params = {};
+        parsed.searchParams.forEach((v, k) => {
+          params[k] = v;
+        });
+        if (Object.keys(params).length > 0) rootLayer._setOwnParamsSilent(params);
+        const hash = parsed.hash.replace(/^#/, '');
+        if (hash) rootLayer._setOwnHashSilent(hash);
+      } catch {}
+    }
+  }
+  if (hasWindowHistory()) {
+    const existing = existingState;
+    if (!hasChaynsHistoryState(existing)) {
+      const foreign = {
+        ...(existing !== null && existing !== void 0 ? existing : {})
+      };
+      delete foreign.__chaynsHistory;
+      const initialState = projectToState(rootLayer, foreign);
+      const idx = getCurrentIdx();
+      window.history.replaceState({
+        ...initialState,
+        __chaynsHistory: {
+          ...initialState.__chaynsHistory,
+          __idx: idx
+        }
+      }, '', window.location.href);
+    } else {
+      applyStateToTree(rootLayer, existing);
+      if (syncCurrentIdxFromState(existing) === null) {
+        const foreign = {
+          ...(existing !== null && existing !== void 0 ? existing : {})
+        };
+        delete foreign.__chaynsHistory;
+        const currentState = projectToState(rootLayer, foreign);
+        const idx = getCurrentIdx();
+        window.history.replaceState({
+          ...currentState,
+          __chaynsHistory: {
+            ...currentState.__chaynsHistory,
+            __idx: idx
+          }
+        }, '', window.location.href);
+      }
+    }
+    blockRegistry.subscribeToChanges(syncNativeHandling);
+    window.addEventListener('popstate', event => {
+      syncCurrentIdxFromState(event.state);
+      if (consumeSilent()) {
+        syncNativeHandling();
+        return;
+      }
+      const raw = event.state;
+      if (!hasChaynsHistoryState(raw)) {
+        syncNativeHandling();
+      } else {
+        const skipBlockCheck = nativeBackHandler.consumeBypassFlag();
+        void queue.enqueue({
+          kind: 'popstate',
+          rawState: raw,
+          skipBlockCheck
+        }).finally(syncNativeHandling);
+      }
+    });
+    syncNativeHandling();
+  }
+  return {
+    rootLayer
+  };
+}
+let _rootLayerResult = null;
+export function getOrInitRootChaynsHistoryLayer(url, segmentCount) {
+  if (!_rootLayerResult) {
+    _rootLayerResult = initRootChaynsHistoryLayer({
+      url,
+      segmentCount
+    });
+  }
+  return _rootLayerResult;
+}

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

@@ -0,0 +1,7 @@
+export const normalizeHistorySegments = segments => segments.filter(segment => segment.length > 0);
+export const normalizeHistoryRouteInput = route => {
+  if (Array.isArray(route)) {
+    return normalizeHistorySegments([...route]);
+  }
+  return route.split('/').filter(Boolean);
+};

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 {
@@ -83,7 +83,7 @@ export class AppWrapper {
         runtimeEnvironment: RuntimeEnviroment.App
       },
       language: {
-        site: AppInfo.Language || 'de',
+        site: language,
         translation: null,
         device: language,
         active: language

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