i18n-scroll-restore 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Grzegorz Kućmierz (https://7u.pl)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,176 @@
-# Temporary Holding Version
+# i18n-scroll-restore
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Zero-dependency, semantic heading & relative ratio scroll preservation for multi-language websites, SPA routers, and VitePress.**
+
+[![npm version](https://img.shields.io/npm/v/i18n-scroll-restore.svg?style=flat-square&color=059669)](https://www.npmjs.com/package/i18n-scroll-restore)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-success.svg?style=flat-square)](https://www.npmjs.com/package/i18n-scroll-restore)
+
+---
+
+## The Problem: The Broken i18n Reading Experience
+
+When readers switch languages on a long article or technical manual, standard browser and router mechanisms fail:
+
+1. **The Scroll-to-Top Drop:** The router treats the language change as a new route (e.g. `/posts/guide` $\to$ `/en/posts/guide`) and forces `window.scrollTo(0, 0)`. The reader loses their place and must scroll searchingly down the page.
+2. **The Pixel-Coordinate Trap:** If the router retains pixel position (`scrollY: 2450px`), the reader lands on a completely mismatched paragraph because translated languages have drastically different heights:
+   - English is often 15–25% shorter than Spanish or German.
+   - Chinese and Japanese have completely different line heights and typographic rhythms.
+   - Code blocks, formula heights, and hyphenation vary across languages.
+
+`i18n-scroll-restore` solves this with a **dual-strategy algorithm**:
+1. **Semantic Heading Matching (Primary):** Identifies the active heading ($H_2, H_3$) currently in the reader's viewport. When the new language renders, it matches the equivalent structural heading and restores scroll position relative to your sticky navbar.
+2. **Relative Viewport Progress Fallback (Secondary):** If no matching heading exists, it computes the exact proportional progress ($p = \frac{\text{scrollY}}{\text{scrollHeight} - \text{innerHeight}}$) and projects it onto the target language's dynamic page height.
+3. **Async DOM Reflow Resilience:** Markdown content frequently loads formulas (MathJax, KaTeX), diagrams (Mermaid), custom fonts, and lazy images asynchronously. An adaptive `requestAnimationFrame` loop accommodates content reflows (~500ms headroom) and instantly unlocks if the user touches the screen or scrolls with their mouse wheel.
+
+---
+
+## Real-World Case Studies & Production Proof
+
+`i18n-scroll-restore` powers multilingual production platforms across Europe:
+
+- 🚀 **[tech.7u.pl](https://tech.7u.pl)** – High-performance engineering portal published in **6 languages** (Polish, English, Spanish, French, Chinese, Hindi) with instant reading state preservation across script directions and typography densities.
+- 🔬 **[science.7u.pl](https://science.7u.pl)** – Mathematical physics and computational journal with heavy LaTeX formulas, 3D Canvas visualizers, and bilingual translations.
+- 🛡️ **[safe.7u.pl](https://safe.7u.pl)** – Privacy, digital hygiene, and telemetry analysis portal with dual-tier high-contrast theming.
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install i18n-scroll-restore
+
+# pnpm
+pnpm add i18n-scroll-restore
+
+# yarn
+yarn add i18n-scroll-restore
+```
+
+---
+
+## Quick Start
+
+### 1. VitePress Integration (1 Line)
+
+In your `.vitepress/theme/Layout.vue` or custom theme setup:
+
+```vue
+<script setup>
+import { onMounted } from 'vue';
+import { useRouter } from 'vitepress';
+import DefaultTheme from 'vitepress/theme';
+import { setupVitePressScrollRestore } from 'i18n-scroll-restore/vue';
+
+const { Layout } = DefaultTheme;
+const router = useRouter();
+
+onMounted(() => {
+  // Automatically attaches click intercepts on language switchers
+  // and restores reading position on route change
+  setupVitePressScrollRestore({ router });
+});
+</script>
+
+<template>
+  <Layout />
+</template>
+```
+
+---
+
+### 2. Vue 3 Composable (`useI18nScrollRestore`)
+
+```vue
+<script setup>
+import { useI18nScrollRestore } from 'i18n-scroll-restore/vue';
+
+const { save, restore, isRestoring } = useI18nScrollRestore({
+  headerOffset: 80, // Height of your sticky navbar in px
+  headingSelector: 'main h1, main h2, main h3'
+});
+
+const switchLanguage = async (newLocale) => {
+  // Capture current heading + relative ratio before route switch
+  save();
+  
+  await changeLocale(newLocale);
+  
+  // Smoothly or instantly restore in the new language DOM
+  await restore();
+};
+</script>
+```
+
+---
+
+### 3. Vue Router 4 Setup
+
+```js
+import { createRouter, createWebHistory } from 'vue-router';
+import { setupVitePressScrollRestore } from 'i18n-scroll-restore/vue';
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [/* ... */]
+});
+
+// Automatically captures scroll before language hops and restores on mount
+setupVitePressScrollRestore({ router });
+```
+
+---
+
+### 4. Vanilla JavaScript / Headless Frameworks (Astro, Svelte, React, Next.js)
+
+```javascript
+import {
+  captureScrollSnapshot,
+  restoreScrollPosition
+} from 'i18n-scroll-restore';
+
+// 1. Right before switching language / pushing new state:
+captureScrollSnapshot({ headerOffset: 72 });
+
+// 2. In your new page render callback / componentDidMount:
+restoreScrollPosition();
+```
+
+---
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `headerOffset` | `number` | `72` | Height in pixels of your fixed/sticky top navigation bar. |
+| `headingSelector` | `string` | `'h1, h2, h3, h4, h5, h6, [data-i18n-anchor]'` | CSS selector used to identify semantic anchors. |
+| `behavior` | `'instant' \| 'smooth'` | `'instant'` | Scroll behavior during restoration. Instant is recommended to prevent visible motion sickness. |
+| `maxAttempts` | `number` | `35` | RAF frame budget (~550ms at 60fps) to allow async formulas and images to settle. |
+| `storagePrefix` | `string` | `'i18n_sr_'` | Storage prefix key for `sessionStorage`. |
+
+---
+
+## Custom Heading Anchoring
+
+If your headings differ between translations or you want to anchor by explicit custom milestones, add the `data-i18n-anchor` attribute to any element:
+
+```html
+<section data-i18n-anchor="benchmarks">
+  <!-- When this section is in viewport, switching language will find the matching anchor -->
+</section>
+```
+
+---
+
+## Architecture: Zero User Hijacking
+
+`i18n-scroll-restore` adheres to strict non-intrusive ergonomics:
+- If the user touches the touchscreen (`touchstart`) or spins the mouse wheel (`wheel`) during restoration, the process **immediately aborts** and relinquishes full control to the user.
+- No permanent locks, no synthetic scroll delays.
+
+---
+
+## License
+
+[MIT](LICENSE) © 2026 Grzegorz Kućmierz (https://7u.pl)

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "i18n-scroll-restore",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Zero-dependency, semantic heading & relative ratio scroll preservation for multi-language sites, SPA routers, and VitePress.",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./vue": {
+      "types": "./src/index.d.ts",
+      "import": "./src/vue.js",
+      "default": "./src/vue.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test tests/**/*.test.js"
+  },
+  "keywords": [
+    "i18n",
+    "scroll",
+    "scroll-restoration",
+    "scroll-restore",
+    "vue",
+    "vue3",
+    "vitepress",
+    "docusaurus",
+    "nuxt",
+    "nextjs",
+    "internationalization",
+    "reading-position",
+    "anchor",
+    "headings",
+    "zero-dependency"
+  ],
+  "author": "Grzegorz Kućmierz <gkucmierz@gmail.com> (https://7u.pl)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://gitea.7u.pl/gkucmierz/i18n-scroll-restore.git"
+  },
+  "homepage": "https://gitea.7u.pl/gkucmierz/i18n-scroll-restore",
+  "peerDependencies": {
+    "vue": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vue": {
+      "optional": true
+    }
+  }
+}

package/src/core.js

@@ -0,0 +1,406 @@
+/**
+ * i18n-scroll-restore
+ * Core zero-dependency scroll preservation engine for multi-language sites and SPAs.
+ *
+ * Supports:
+ * - Semantic heading hierarchy & index matching
+ * - Relative viewport ratio progress calculation
+ * - Custom scrollable DOM containers (e.g. split-pane studios, app shells) as well as window
+ * - Async DOM layout reflow resilience (Mermaid, MathJax, fonts, lazy images)
+ * - Non-intrusive cancellation on user interaction
+ *
+ * @author Grzegorz Kućmierz <gkucmierz@gmail.com> (https://7u.pl)
+ * @license MIT
+ */
+
+const DEFAULT_STORAGE_PREFIX = 'i18n_sr_';
+const DEFAULT_HEADING_SELECTOR = 'h1, h2, h3, h4, h5, h6, [data-i18n-anchor]';
+const DEFAULT_HEADER_OFFSET = 72; // px headroom for fixed/sticky navbar
+const MAX_ATTEMPTS = 35; // ~550ms headroom for DOM reflow
+
+let activeSnapshot = null;
+let isRestoring = false;
+let userCancelled = false;
+
+/**
+ * Resolves an optional custom scrollable container element (`Element`, selector string, or getter function).
+ * Returns null when scrolling the global `window`.
+ *
+ * @param {object} [options]
+ * @returns {Element|null}
+ */
+export const resolveScrollContainer = (options = {}) => {
+  if (!options || !options.container) return null;
+  const raw = typeof options.container === 'function' ? options.container() : options.container;
+  if (!raw) return null;
+  if (typeof raw === 'string') {
+    if (typeof document !== 'undefined' && typeof document.querySelector === 'function') {
+      return document.querySelector(raw);
+    }
+    return null;
+  }
+  // Support Vue template refs (`ref.value` or direct Element)
+  if (raw && typeof raw === 'object' && 'value' in raw) {
+    return raw.value || null;
+  }
+  return raw;
+};
+
+const getStorageBackend = (options = {}) => {
+  if (typeof window === 'undefined') return null;
+  if (options.persist && typeof localStorage !== 'undefined') return localStorage;
+  if (typeof sessionStorage !== 'undefined') return sessionStorage;
+  return null;
+};
+
+/**
+ * Calculates relative scroll progress between 0 and 1.
+ *
+ * @param {number} scrollY
+ * @param {number} scrollHeight
+ * @param {number} innerHeight
+ * @returns {number}
+ */
+export const calculateRelativeProgress = (scrollY, scrollHeight, innerHeight) => {
+  const maxScroll = Math.max(0, scrollHeight - innerHeight);
+  if (maxScroll <= 0) return 0;
+  const ratio = scrollY / maxScroll;
+  return Math.min(1, Math.max(0, ratio));
+};
+
+/**
+ * Calculates target scroll position in pixels from relative progress.
+ *
+ * @param {number} ratio
+ * @param {number} scrollHeight
+ * @param {number} innerHeight
+ * @returns {number}
+ */
+export const calculateTargetScroll = (ratio, scrollHeight, innerHeight) => {
+  const maxScroll = Math.max(0, scrollHeight - innerHeight);
+  return Math.round(Math.min(1, Math.max(0, ratio)) * maxScroll);
+};
+
+/**
+ * Finds the currently active heading closest to the top reading area.
+ *
+ * @param {Document|Element} root
+ * @param {object} options
+ * @returns {object|null}
+ */
+export const findActiveHeading = (root = (typeof document !== 'undefined' ? document : null), options = {}) => {
+  const containerEl = resolveScrollContainer(options);
+  const queryRoot = containerEl || root;
+  if (!queryRoot || typeof queryRoot.querySelectorAll !== 'function') return null;
+
+  const selector = options.headingSelector || DEFAULT_HEADING_SELECTOR;
+  const containerTop =
+    containerEl && typeof containerEl.getBoundingClientRect === 'function'
+      ? containerEl.getBoundingClientRect().top
+      : 0;
+  const headerOffset = containerTop + (options.headerOffset ?? (containerEl ? 16 : DEFAULT_HEADER_OFFSET));
+  const headings = Array.from(queryRoot.querySelectorAll(selector)).filter((el) => {
+    return el.offsetParent !== null && el.getBoundingClientRect().height > 0;
+  });
+
+  if (headings.length === 0) return null;
+
+  let bestHeading = null;
+  let bestDistance = Infinity;
+
+  headings.forEach((heading) => {
+    const rect = heading.getBoundingClientRect();
+    const distance = rect.top - headerOffset;
+
+    if (distance <= 120 && Math.abs(distance) < bestDistance) {
+      bestDistance = Math.abs(distance);
+      bestHeading = heading;
+    }
+  });
+
+  if (!bestHeading) {
+    for (let i = headings.length - 1; i >= 0; i--) {
+      const rect = headings[i].getBoundingClientRect();
+      if (rect.top - headerOffset <= 200) {
+        bestHeading = headings[i];
+        break;
+      }
+    }
+  }
+
+  if (!bestHeading) {
+    bestHeading = headings[0];
+  }
+
+  const tag = bestHeading.tagName ? bestHeading.tagName.toUpperCase() : 'H2';
+  const tagList = headings.filter((h) => (h.tagName ? h.tagName.toUpperCase() : '') === tag);
+  const indexInTag = tagList.indexOf(bestHeading);
+  const indexOverall = headings.indexOf(bestHeading);
+  const rect = bestHeading.getBoundingClientRect();
+
+  return {
+    tag,
+    indexInTag: indexInTag >= 0 ? indexInTag : 0,
+    indexOverall: indexOverall >= 0 ? indexOverall : 0,
+    id: bestHeading.id || null,
+    topOffset: Math.round(rect.top - headerOffset)
+  };
+};
+
+/**
+ * Creates a complete snapshot of current scroll & reading context.
+ *
+ * @param {object} options
+ * @returns {object|null}
+ */
+export const captureScrollSnapshot = (options = {}) => {
+  if (typeof window === 'undefined' || typeof document === 'undefined') return null;
+
+  const containerEl = resolveScrollContainer(options);
+  const scrollY = containerEl ? containerEl.scrollTop || 0 : window.scrollY || window.pageYOffset || 0;
+  const scrollX = containerEl ? containerEl.scrollLeft || 0 : window.scrollX || window.pageXOffset || 0;
+  const scrollHeight = containerEl
+    ? containerEl.scrollHeight || 0
+    : Math.max(
+        document.documentElement.scrollHeight,
+        document.body ? document.body.scrollHeight : 0
+      );
+  const innerHeight = containerEl ? containerEl.clientHeight || 800 : window.innerHeight || 800;
+
+  const relativeProgress = calculateRelativeProgress(scrollY, scrollHeight, innerHeight);
+  const heading = findActiveHeading(containerEl || document, options);
+
+  const snapshot = {
+    scrollY,
+    scrollX,
+    scrollHeight,
+    innerHeight,
+    relativeProgress,
+    heading,
+    timestamp: Date.now()
+  };
+
+  activeSnapshot = snapshot;
+
+  const prefix = options.storagePrefix || DEFAULT_STORAGE_PREFIX;
+  const store = getStorageBackend(options);
+  try {
+    if (store) store.setItem(`${prefix}snapshot`, JSON.stringify(snapshot));
+  } catch (e) {}
+
+  return snapshot;
+};
+
+/**
+ * Retrieves the last captured snapshot from memory or sessionStorage/localStorage.
+ *
+ * @param {object} options
+ * @returns {object|null}
+ */
+export const getSavedSnapshot = (options = {}) => {
+  if (activeSnapshot && !options.storagePrefix) return activeSnapshot;
+
+  if (typeof window === 'undefined') return null;
+  const prefix = options.storagePrefix || DEFAULT_STORAGE_PREFIX;
+  const store = getStorageBackend(options);
+  try {
+    const raw = store ? store.getItem(`${prefix}snapshot`) : null;
+    if (raw) {
+      const parsed = JSON.parse(raw);
+      activeSnapshot = parsed;
+      return parsed;
+    }
+  } catch (e) {}
+
+  return activeSnapshot;
+};
+
+/**
+ * Clears the saved snapshot from memory and storage.
+ *
+ * @param {object} options
+ */
+export const clearSavedSnapshot = (options = {}) => {
+  activeSnapshot = null;
+  if (typeof window === 'undefined') return;
+  const prefix = options.storagePrefix || DEFAULT_STORAGE_PREFIX;
+  const store = getStorageBackend(options);
+  try {
+    if (store) store.removeItem(`${prefix}snapshot`);
+  } catch (e) {}
+};
+
+/**
+ * Resolves the target scroll position in the current DOM from a snapshot.
+ *
+ * @param {object} snapshot
+ * @param {object} options
+ * @returns {number}
+ */
+export const resolveTargetScrollPosition = (snapshot, options = {}) => {
+  if (!snapshot || typeof window === 'undefined' || typeof document === 'undefined') return 0;
+
+  const containerEl = resolveScrollContainer(options);
+  const queryRoot = containerEl || document;
+  const containerTop =
+    containerEl && typeof containerEl.getBoundingClientRect === 'function'
+      ? containerEl.getBoundingClientRect().top
+      : 0;
+  const headerOffset = containerTop + (options.headerOffset ?? (containerEl ? 16 : DEFAULT_HEADER_OFFSET));
+  const selector = options.headingSelector || DEFAULT_HEADING_SELECTOR;
+  const scrollHeight = containerEl
+    ? containerEl.scrollHeight || 0
+    : Math.max(
+        document.documentElement.scrollHeight,
+        document.body ? document.body.scrollHeight : 0
+      );
+  const innerHeight = containerEl ? containerEl.clientHeight || 800 : window.innerHeight || 800;
+
+  // 1. Semantic Heading Match
+  if (snapshot.heading && typeof queryRoot.querySelectorAll === 'function') {
+    const headings = Array.from(queryRoot.querySelectorAll(selector)).filter((el) => {
+      return el.offsetParent !== null && el.getBoundingClientRect().height > 0;
+    });
+
+    if (headings.length > 0) {
+      let matched = null;
+
+      if (snapshot.heading.id && typeof document.getElementById === 'function') {
+        matched = document.getElementById(snapshot.heading.id);
+      }
+
+      if (!matched && snapshot.heading.tag) {
+        const sameTagList = headings.filter(
+          (h) => (h.tagName ? h.tagName.toUpperCase() : '') === snapshot.heading.tag
+        );
+        if (sameTagList[snapshot.heading.indexInTag]) {
+          matched = sameTagList[snapshot.heading.indexInTag];
+        }
+      }
+
+      if (!matched && headings[snapshot.heading.indexOverall]) {
+        matched = headings[snapshot.heading.indexOverall];
+      }
+
+      if (matched) {
+        const rect = matched.getBoundingClientRect();
+        const currentScroll = containerEl
+          ? containerEl.scrollTop || 0
+          : window.scrollY || window.pageYOffset || 0;
+        const savedTopOffset = typeof snapshot.heading.topOffset === 'number' ? snapshot.heading.topOffset : 0;
+        const targetY = currentScroll + rect.top - headerOffset - savedTopOffset;
+        const maxScroll = Math.max(0, scrollHeight - innerHeight);
+        return Math.round(Math.min(maxScroll, Math.max(0, targetY)));
+      }
+    }
+  }
+
+  // 2. Relative Ratio Fallback
+  return calculateTargetScroll(snapshot.relativeProgress || 0, scrollHeight, innerHeight);
+};
+
+/**
+ * Restores the scroll position smoothly or instantly with layout reflow resilience.
+ *
+ * @param {object} [customSnapshot]
+ * @param {object} [options]
+ * @returns {Promise<boolean>}
+ */
+export const restoreScrollPosition = (customSnapshot = null, options = {}) => {
+  if (typeof window === 'undefined') return Promise.resolve(false);
+
+  const snapshot = customSnapshot || getSavedSnapshot(options);
+  if (!snapshot) return Promise.resolve(false);
+
+  return new Promise((resolve) => {
+    isRestoring = true;
+    userCancelled = false;
+
+    let attempts = 0;
+    const maxAttempts = options.maxAttempts || MAX_ATTEMPTS;
+
+    const cancel = () => {
+      userCancelled = true;
+      isRestoring = false;
+      cleanup();
+      resolve(false);
+    };
+
+    const cleanup = () => {
+      window.removeEventListener('wheel', cancel);
+      window.removeEventListener('touchstart', cancel);
+      window.removeEventListener('keydown', cancel);
+    };
+
+    window.addEventListener('wheel', cancel, { passive: true });
+    window.addEventListener('touchstart', cancel, { passive: true });
+    window.addEventListener('keydown', cancel, { passive: true });
+
+    let consecutiveStableFrames = 0;
+
+    const applyScrollTop = (targetY) => {
+      const containerEl = resolveScrollContainer(options);
+      if (containerEl) {
+        if (typeof containerEl.scrollTo === 'function') {
+          containerEl.scrollTo({
+            top: targetY,
+            left: 0,
+            behavior: options.behavior || 'instant'
+          });
+        } else {
+          containerEl.scrollTop = targetY;
+        }
+        return containerEl.scrollTop || 0;
+      }
+      window.scrollTo({
+        top: targetY,
+        left: 0,
+        behavior: options.behavior || 'instant'
+      });
+      return window.scrollY || window.pageYOffset || 0;
+    };
+
+    const tick = () => {
+      if (userCancelled || !isRestoring) {
+        cleanup();
+        resolve(false);
+        return;
+      }
+
+      const targetY = resolveTargetScrollPosition(snapshot, options);
+      const actualY = applyScrollTop(targetY);
+
+      attempts++;
+      const diff = Math.abs(actualY - targetY);
+
+      if (diff <= 2) {
+        consecutiveStableFrames++;
+      } else {
+        consecutiveStableFrames = 0;
+      }
+
+      if (consecutiveStableFrames >= 2 || attempts >= maxAttempts) {
+        applyScrollTop(targetY);
+        setTimeout(() => {
+          isRestoring = false;
+          cleanup();
+          if (!options.persist) {
+            clearSavedSnapshot(options);
+          }
+          resolve(true);
+        }, 50);
+      } else {
+        requestAnimationFrame(tick);
+      }
+    };
+
+    requestAnimationFrame(tick);
+  });
+};
+
+/**
+ * Returns whether a scroll restoration sequence is currently active.
+ *
+ * @returns {boolean}
+ */
+export const isScrollRestoring = () => isRestoring;

package/src/index.d.ts

@@ -0,0 +1,82 @@
+export interface HeadingAnchor {
+  tag: string;
+  indexInTag: number;
+  indexOverall: number;
+  id: string | null;
+  topOffset: number;
+}
+
+export interface I18nScrollSnapshot {
+  scrollY: number;
+  scrollX: number;
+  scrollHeight: number;
+  innerHeight: number;
+  relativeProgress: number;
+  heading: HeadingAnchor | null;
+  timestamp: number;
+}
+
+export interface ScrollRestoreOptions {
+  storagePrefix?: string;
+  headingSelector?: string;
+  headerOffset?: number;
+  maxAttempts?: number;
+  behavior?: ScrollBehavior;
+}
+
+export function calculateRelativeProgress(
+  scrollY: number,
+  scrollHeight: number,
+  innerHeight: number
+): number;
+
+export function calculateTargetScroll(
+  ratio: number,
+  scrollHeight: number,
+  innerHeight: number
+): number;
+
+export function findActiveHeading(
+  root?: Document | Element | null,
+  options?: ScrollRestoreOptions
+): HeadingAnchor | null;
+
+export function captureScrollSnapshot(
+  options?: ScrollRestoreOptions
+): I18nScrollSnapshot | null;
+
+export function getSavedSnapshot(
+  options?: ScrollRestoreOptions
+): I18nScrollSnapshot | null;
+
+export function clearSavedSnapshot(
+  options?: ScrollRestoreOptions
+): void;
+
+export function resolveTargetScrollPosition(
+  snapshot: I18nScrollSnapshot | null,
+  options?: ScrollRestoreOptions
+): number;
+
+export function restoreScrollPosition(
+  customSnapshot?: I18nScrollSnapshot | null,
+  options?: ScrollRestoreOptions
+): Promise<boolean>;
+
+export function isScrollRestoring(): boolean;
+
+export function useI18nScrollRestore(options?: ScrollRestoreOptions): {
+  save: () => I18nScrollSnapshot | null;
+  restore: (customSnapshot?: I18nScrollSnapshot | null) => Promise<boolean>;
+  clear: () => void;
+  isRestoring: () => boolean;
+};
+
+export function setupVitePressScrollRestore(params?: {
+  router?: any;
+  options?: ScrollRestoreOptions;
+}): () => void;
+
+export function createI18nScrollRestorePlugin(defaultOptions?: ScrollRestoreOptions): {
+  install(app: any, options?: ScrollRestoreOptions): void;
+};

package/src/index.js

@@ -0,0 +1,26 @@
+/**
+ * i18n-scroll-restore
+ * Entry point for vanilla JS and bundlers.
+ * 
+ * @author Grzegorz Kućmierz <gkucmierz@gmail.com> (https://7u.pl)
+ * @license MIT
+ */
+
+export {
+  resolveScrollContainer,
+  calculateRelativeProgress,
+  calculateTargetScroll,
+  findActiveHeading,
+  captureScrollSnapshot,
+  getSavedSnapshot,
+  clearSavedSnapshot,
+  resolveTargetScrollPosition,
+  restoreScrollPosition,
+  isScrollRestoring
+} from './core.js';
+
+export {
+  useI18nScrollRestore,
+  setupVitePressScrollRestore,
+  createI18nScrollRestorePlugin
+} from './vue.js';

package/src/vue.js

@@ -0,0 +1,140 @@
+/**
+ * i18n-scroll-restore/vue
+ * Vue 3 and VitePress composable & integration helper.
+ * 
+ * @author Grzegorz Kućmierz <gkucmierz@gmail.com> (https://7u.pl)
+ * @license MIT
+ */
+
+import {
+  captureScrollSnapshot,
+  restoreScrollPosition,
+  clearSavedSnapshot,
+  isScrollRestoring
+} from './core.js';
+
+/**
+ * Vue 3 Composable for i18n scroll preservation.
+ * 
+ * @param {object} [options] 
+ * @returns {object}
+ */
+export const useI18nScrollRestore = (options = {}) => {
+  const save = () => captureScrollSnapshot(options);
+  const restore = (customSnapshot = null) => restoreScrollPosition(customSnapshot, options);
+  const clear = () => clearSavedSnapshot(options);
+
+  return {
+    save,
+    restore,
+    clear,
+    isRestoring: isScrollRestoring
+  };
+};
+
+/**
+ * Sets up automatic scroll restoration for VitePress or Vue Router.
+ * 
+ * @param {object} params
+ * @param {object} [params.router] Vue Router or VitePress router instance
+ * @param {object} [params.options] Scroll restore configuration options
+ * @returns {function} Cleanup function
+ */
+export const setupVitePressScrollRestore = ({ router, options = {} } = {}) => {
+  if (typeof window === 'undefined') return () => {};
+
+  let lastPath = window.location.pathname;
+
+  // Intercept before language / route transition
+  const handleBeforeNavigate = () => {
+    captureScrollSnapshot(options);
+  };
+
+  // Watch clicks on language links (e.g. .VPNavBarTranslations, flags, [data-i18n-link])
+  const handleDocumentClick = (event) => {
+    const target = event.target;
+    if (!target || typeof target.closest !== 'function') return;
+
+    const link = target.closest('a, button.VPLink, .VPNavBarTranslations a, .VPNavScreenTranslations a');
+    if (link) {
+      captureScrollSnapshot(options);
+    }
+  };
+
+  document.addEventListener('click', handleDocumentClick, { capture: true, passive: true });
+  window.addEventListener('beforeunload', handleBeforeNavigate);
+  window.addEventListener('pagehide', handleBeforeNavigate);
+
+  let unwatchRouter = null;
+
+  if (router && typeof router.onAfterRouteChanged === 'function') {
+    // VitePress Router
+    router.onBeforeRouteChange = () => {
+      captureScrollSnapshot(options);
+    };
+
+    const originalAfter = router.onAfterRouteChanged;
+    router.onAfterRouteChanged = (to) => {
+      if (typeof originalAfter === 'function') {
+        originalAfter(to);
+      }
+      // Small tick to let Vue mount the new content
+      requestAnimationFrame(() => {
+        restoreScrollPosition(null, options);
+      });
+    };
+
+    unwatchRouter = () => {
+      router.onAfterRouteChanged = originalAfter;
+    };
+  } else if (router && typeof router.beforeEach === 'function') {
+    // Standard Vue Router 4
+    const removeBefore = router.beforeEach((to, from, next) => {
+      if (to.path !== from.path) {
+        captureScrollSnapshot(options);
+      }
+      next();
+    });
+
+    const removeAfter = router.afterEach(() => {
+      requestAnimationFrame(() => {
+        restoreScrollPosition(null, options);
+      });
+    });
+
+    unwatchRouter = () => {
+      removeBefore();
+      removeAfter();
+    };
+  }
+
+  // Initial mount restoration if returning to page or switching
+  requestAnimationFrame(() => {
+    restoreScrollPosition(null, options);
+  });
+
+  return () => {
+    document.removeEventListener('click', handleDocumentClick, { capture: true });
+    window.removeEventListener('beforeunload', handleBeforeNavigate);
+    window.removeEventListener('pagehide', handleBeforeNavigate);
+    if (unwatchRouter) unwatchRouter();
+  };
+};
+
+/**
+ * Vue 3 Plugin wrapper.
+ */
+export const createI18nScrollRestorePlugin = (defaultOptions = {}) => {
+  return {
+    install(app, options = {}) {
+      const mergedOptions = { ...defaultOptions, ...options };
+      app.config.globalProperties.$i18nScrollRestore = {
+        save: () => captureScrollSnapshot(mergedOptions),
+        restore: (snap) => restoreScrollPosition(snap, mergedOptions),
+        clear: () => clearSavedSnapshot(mergedOptions),
+        isRestoring: isScrollRestoring
+      };
+      app.provide('i18nScrollRestore', app.config.globalProperties.$i18nScrollRestore);
+    }
+  };
+};