@devzwo/ngx-magic-scroll 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -0,0 +1,133 @@
+# Changelog
+
+## Release v1.1.1 (2026-10-18)
+
+### Features
+
+- Bundle offline Markdown documentation (`ai/usage.md`, `getting-started.md`, concepts, recipes, migrations, changelog) directly in the npm distribution package.
+- Provide machine-readable AI Agent Guide (`ai/usage.md`) and dynamic `llms.txt` ecosystem index for AI coding assistants.
+- Add version-specific migration guides covering `v0.0.1-rc.1 -> v0.0.1-rc.2`, `v0.0.1-rc.2 -> v1.0.0`, and `v1.0.x -> v1.1.0` with verified Angular 22 before/after code transformations.
+- Export raw Markdown documentation endpoints (`.md`) across all documentation routes.
+- Add automated validation scripts for package archive structure, Markdown link resolution, version consistency, and Angular `ngc` recipe/migration snippet compilation.
+
+### Bug Fixes & Behavioral Changes
+
+- Fix duplicate H1 headings rendered on documentation pages in Starlight.
+
+### Deprecations
+
+- None.
+
+### Breaking Changes
+
+- None.
+
+## Release v1.1.0 (2026-10-18)
+
+### Features
+
+- Add opt-in `preserveOnLayoutChange` configuration option to maintain section-relative scroll positions during asynchronous layout reflows (e.g., accordions, lazy images, form expansions).
+- Preserve section-relative pixel displacement (`displacement`) across automatic layout corrections and data updates to keep the reader's exact reading position intact.
+- Add accessible focus management (`focus: true`) to `scrollTo()` with temporary `tabindex="-1"` handling and completion coordination for smooth scrolling.
+- Optimize layout reflow tracking using region-scoped `ResizeObserver` and `requestAnimationFrame` coalescing to prevent layout thrashing.
+- Guard against scroll interruptions by deferring layout preservation during active smooth scrolling and skipping redundant sub-pixel (`< 1px`) scroll adjustments.
+- Update demo application with layout preservation controls, accordion examples, accessible navigation toggles, and refreshed architecture documentation.
+
+### Bug Fixes & Behavioral Changes
+
+- None.
+
+### Deprecations
+
+- None.
+
+### Breaking Changes
+
+- None.
+
+### Migration Guide
+
+- See [Migration Guide: v1.0 to v1.1](./docs/migrations/v1.0-to-v1.1.md) for upgrade instructions and before/after code examples.
+
+## Release v1.0.0
+
+### Features
+
+- Handle subsequent Angular router fragment navigations automatically after initial page load without requiring consumer coordination.
+- Queue pending scroll targets and retry navigation via `MutationObserver` until asynchronous data and matching DOM elements are rendered.
+- Tag scroll-spy navigation origins to distinguish internal fragment updates from external navigation and prevent navigation loops.
+- Support browser history navigation (back/forward popstate) with scroll position restoration while preserving custom router history state.
+- Support multiple anchor prefixes via `anchorPrefixes` array configuration.
+- Add strict explicit anchor selection mode (`explicitOnly`) to restrict anchor resolution exclusively to `[scrollAnchor]` directives.
+- Add parameter help tooltips and interactive anchor strategy toggles to the demo application.
+- Integrate Mermaid architecture and lifecycle flow diagrams into the documentation.
+- Add mascot branding in demo header and update favicons across docs and demo app.
+- Expand test matrix and Playwright configuration with dedicated per-browser test suites.
+
+### Bug Fixes & Behavioral Changes
+
+- None.
+
+### Deprecations
+
+- None.
+
+### Breaking Changes
+
+- None.
+
+### Migration Guide
+
+- See [Migration Guide: v0.0.1-rc.2 to v1.0.0](./docs/migrations/v0.0.1-rc.2-to-1.0.0.md) for upgrade instructions and before/after code examples.
+
+## Pre-Release v0.0.1-rc.2
+
+### Features
+
+- Track visible live sections in real time so position preservation during asynchronous data updates or resizing targets the current reading position.
+- Keep the currently read section active in the scroll-spy until the next section begins, prioritizing fully contained sections within the reading area.
+- Add `bottomOffset` and `activationThreshold` configuration options for granular control over active reading boundaries and trigger lines.
+- Add active zone overlay in demo application to visualize active boundaries and exclusion zones.
+
+### Bug Fixes & Behavioral Changes
+
+- Cancel pending initial scroll restoration on user interaction (wheel, touch, navigation keys) prior to data readiness, while ignoring inputs in editable elements.
+- Ensure programmatic `scrollTo()` continues to work as expected after user interruption.
+- Improve server-side rendering (SSR) resilience when `ResizeObserver` or `defaultView` is not available.
+
+### Deprecations
+
+- None.
+
+### Breaking Changes
+
+- None.
+
+### Migration Guide
+
+- See [Migration Guide: v0.0.1-rc.1 to v0.0.1-rc.2](./docs/migrations/v0.0.1-rc.1-to-0.0.1-rc.2.md) for upgrade instructions and before/after code examples.
+
+## Pre-Release v0.0.1-rc.1
+
+The first public release preview. The public API is under review.
+
+### Features
+
+- Anchor scrolling through `magicScroll`, with automatic scroll-container detection, configurable offsets and header measurement.
+- URL synchronization and initial scroll-position restoration.
+- Scroll-position preservation when data or container dimensions change.
+- Inheritable defaults through `provideMagicScroll`, with overrides per region or action and separate behavior for restoration and user interaction.
+- Support for signals, plain input data, Angular resources and provider-neutral data sources.
+- Optional anchor markers, explicit IDs through `scrollAnchor` and independent scoping for nested scroll regions.
+
+### Bug Fixes & Behavioral Changes
+
+- None.
+
+### Deprecations
+
+- None.
+
+### Breaking Changes
+
+- None.

package/README.md

@@ -121,7 +121,7 @@ Four routed examples demonstrate document synchronization, asynchronous navigati
 
 `pnpm test:ci` enforces 100% statements, branches, functions and lines per library implementation file. The existing 25 E2E scenarios remain unchanged after the migration to the facade and pass in Chromium, Firefox and WebKit (75 runs).
 
-[Documentation and API](https://devzwo.github.io/ngx-magic-scroll/) · [Source and issues](https://github.com/devZWO/ngx-magic-scroll)
+[Documentation and API](https://devzwo.github.io/ngx-magic-scroll/) · [AI Agent Guide](ai/usage.md) · [llms.txt Index](https://devzwo.github.io/ngx-magic-scroll/llms.txt) · [Changelog](CHANGELOG.md) · [Source and issues](https://github.com/devZWO/ngx-magic-scroll)
 
 MIT, copyright 2026 devZWO GmbH.
 

package/ai/usage.md

@@ -0,0 +1,97 @@
+---
+title: AI Agent Integration Guide
+description: Concise reference and integration rules for AI coding assistants using @devzwo/ngx-magic-scroll.
+---
+
+This guide provides compact, high-density reference instructions for AI agents and automated code generators integrating or upgrading `@devzwo/ngx-magic-scroll`.
+
+## Package Metadata & Prerequisites
+
+- **Package**: `@devzwo/ngx-magic-scroll`
+- **Framework Support**: Angular `^22.2.0`, RxJS `^7.8.0`
+- **Prerequisites**: Angular Router enabled (`provideRouter(...)` in `app.config.ts`) for fragment synchronization and history restoration.
+- **Conventions**: Angular standalone components (do not set `standalone: true` in `@Component`), signal inputs/outputs, and native control flow (`@if`, `@for`).
+
+## Minimal Integration Example
+
+<!-- recipe-check: ai-usage-minimal.ts -->
+
+```ts
+import { Component } from '@angular/core';
+import {
+  MagicScrollDirective,
+  ScrollAnchorDirective,
+  provideMagicScroll,
+} from '@devzwo/ngx-magic-scroll';
+
+@Component({
+  selector: 'app-agent-doc-sample',
+  imports: [MagicScrollDirective, ScrollAnchorDirective],
+  providers: [provideMagicScroll()],
+  template: `
+    <nav aria-label="Page Sections">
+      <button (click)="scroll.scrollTo('intro')">Intro</button>
+      <button (click)="scroll.scrollTo('details', { focus: true })">Details</button>
+    </nav>
+
+    <main magicScroll #scroll="magicScroll">
+      <section id="intro">
+        <h2>Introduction</h2>
+      </section>
+      <section id="details" scrollAnchor>
+        <h2>Details</h2>
+      </section>
+    </main>
+  `,
+})
+export class AgentDocSampleComponent {}
+```
+
+## Recipe Decision Guide
+
+Select the appropriate recipe and configuration based on application requirements:
+
+| Requirement / Scenario            | Recommended Recipe                                                                                    | Key Configuration / API                                                                                   |
+| :-------------------------------- | :---------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------- |
+| **Static Navigation & Spy**       | [Anchor Navigation](../docs/recipes/scroll-to-anchor.md)                                                   | `[magicScroll]`, `#scroll="magicScroll"`, `scroll.activeAnchor()`, `scroll.scrollTo(id, { focus: true })` |
+| **Async Data (Angular Resource)** | [rxResource Integration](../docs/recipes/rx-resource.md)                                                   | `[scrollSource]="resource"`, `[scrollAnchor]="item.id"`                                                   |
+| **Async Data (Signal State)**     | [NgRx Signal Store](../docs/recipes/ngrx-signal-store.md) / [TanStack Query](../docs/recipes/tanstack-query.md) | `[scrollSource]="store.items"` or `[scrollSource]="query.data"`                                           |
+| **Appended / Paginated Lists**    | [Paginated Lists](../docs/recipes/paginated-lists.md)                                                      | `[scrollSource]="items()"`, automatic top-anchor retention during append                                  |
+| **Cross-Route Return**            | [Return to List](../docs/recipes/return-to-list.md)                                                        | Browser history popstate auto-restoration                                                                 |
+| **Sticky Header / Layout Offset** | [Sticky Master-Detail](../docs/recipes/sticky-master-detail.md)                                            | `[headerOffset]="measuredHeight()"` or `[topOffset]="64"`                                                 |
+| **Drawer / Nested Container**     | [Material Drawer](../docs/recipes/material-drawer.md)                                                      | `[magicScroll]` directly on the scrolling overflow container                                              |
+| **Dynamic Reflow / Accordion**    | [Position Preservation](../docs/concepts/position-preservation.md)                                         | `provideMagicScroll({ preserveOnLayoutChange: true })`                                                    |
+
+## Core Integration Rules & Common Pitfalls
+
+### 1. `scrollSource` Reactivity
+
+- **Rule**: Pass live reactive signals or resource references to `[scrollSource]`, never evaluated static values in non-reactive contexts.
+- **Pitfall**: Passing `[scrollSource]="resource.value()"` creates a static snapshot if not evaluated inside a reactive signal context; pass `[scrollSource]="resource"` directly when using `ResourceRef` or `rxResource`.
+- **Readiness**: `undefined` indicates loading. Position restoration and fragment navigation wait until data resolves to a defined value (array, object, or `null`).
+
+### 2. Anchor Scoping & ID Uniqueness
+
+- **Containment**: Every anchor element belongs strictly to its closest parent `[magicScroll]` region. A parent scroll instance cannot scroll to anchors inside a nested scroll region.
+- **Stability**: Anchor `id` attributes must be globally unique across the document and remain stable between renders.
+- **Selective Anchors**: Use `[anchorPrefixes]="['section-']"` or `explicitOnly: true` with `[scrollAnchor]` to avoid treating arbitrary DOM IDs as scroll anchors.
+
+### 3. Accessible Focus Transfer
+
+- When triggering navigation from button clicks or shortcuts, pass `{ focus: true }` to `scrollTo(id, { focus: true })`.
+- Non-focusable elements automatically receive temporary `tabindex="-1"`, cleaned up on blur or directive destruction.
+- Smooth scrolling coordinates focus transfer on scroll completion (`scrollend`).
+
+### 4. Layout Preservation During Reflows
+
+- Enable `preserveOnLayoutChange: true` to prevent content jumps when accordions toggle, images load, or forms expand above the user's viewport.
+- The library tracks section-relative displacement to preserve the exact reading position without layout thrashing.
+
+## Upgrade & Migration Workflow
+
+When updating `@devzwo/ngx-magic-scroll` in an existing project:
+
+1. **Verify Installed Version**: Inspect `package.json` for `@devzwo/ngx-magic-scroll`.
+2. **Review Changelog**: Check [Changelog](../CHANGELOG.md) for breaking changes, new features, and deprecation notices.
+3. **Check Version Migration Guides**: Consult [Migration Guides](../docs/migrations/v1.0-to-v1.1.md) for step-by-step code transformations and before/after snippets.
+4. **Run Project Validation**: Verify template compilation and unit tests with `ng build` / `pnpm test`.

package/docs/concepts/anchors.md

@@ -0,0 +1,129 @@
+---
+title: Scroll regions and anchor identity
+description: Understand anchor selection, region ownership and the container that actually scrolls.
+sidebar:
+  order: 1
+---
+
+An anchor identifies a section of content independently of its pixel position. A scroll region defines which anchors `magicScroll` manages; the scroll container determines which viewport moves. Keeping these three roles separate helps you design layouts that remain navigable as content changes.
+
+## Stable IDs identify content
+
+The URL fragment `#project-12` refers to the element with ID `project-12`. On restoration, the library finds that element's current position. Inserting content above it can change its coordinates without changing what the link means.
+
+Use IDs derived from the identity of your content, such as a project ID. An array index is unsuitable when sorting, filtering or inserting items can make it refer to a different item. IDs must be unique across the entire document, including across separate regions.
+
+Restoration returns to an anchor's position with the configured top offset. It does not remember the exact pixel distance the user had scrolled into that section.
+
+## Configuring activation boundaries and scroll offsets
+
+`magicScroll` computes both scroll alignment and active section detection using layout and offset configuration:
+
+- **`headerOffset`**: Static spacing in pixels (e.g. `headerOffset: 24`), adding visual breathing room above section headings.
+- **`headerSelector`**: CSS selector for a fixed or sticky navigation bar (e.g. `headerSelector: '.app-header'`). Its dynamically measured height is automatically added to the boundary offset so obscured elements do not trigger activation or get covered during scroll restoration.
+- **`bottomOffset`**: Static bottom spacing in pixels (e.g. `bottomOffset: 40`), accounting for sticky footers, floating action bars, or aesthetic margins.
+- **`activationThreshold`**: Relative focal trigger threshold from `0.0` (top boundary) to `1.0` (bottom boundary), defining the trigger line (`topBoundary + (bottomBoundary - topBoundary) * activationThreshold`) where sections transition to active status.
+
+Active section detection evaluates elements within the visible reading area between the effective top boundary (`containerTop + headerHeight + headerOffset`) and bottom boundary (`(containerBottom | viewportHeight) - bottomOffset`), prioritizing fully visible sections before falling back to reading-position tracking for tall content relative to the configured `activationThreshold`.
+
+```mermaid
+flowchart TB
+    subgraph Viewport ["Scroll Viewport / Container"]
+        direction TB
+        TopZone["<b>Top Exclusion Area</b><br/><i>[0 .. topBoundary]</i><br/>Sticky Header (headerSelector) + headerOffset"]
+        ReadingZone["<b>Active Reading Band</b><br/><i>[topBoundary .. bottomBoundary]</i><br/>Full containment evaluation area"]
+        TriggerLine["<b>─── Dynamic Trigger Line ───</b><br/><i>topBoundary + (ReadingBand * activationThreshold)</i>"]
+        BottomZone["<b>Bottom Exclusion Area</b><br/><i>[bottomBoundary .. containerBottom]</i><br/>Sticky Footer / Padding (bottomOffset)"]
+
+        TopZone --- ReadingZone
+        ReadingZone --- TriggerLine
+        TriggerLine --- BottomZone
+    end
+```
+
+You can configure offsets globally in application providers or locally per scroll region:
+
+```ts
+// Global configuration
+provideMagicScroll({
+  headerSelector: '.app-header',
+  headerOffset: 24,
+  bottomOffset: 48,
+  activationThreshold: 0.3,
+});
+```
+
+```html
+<!-- Per-region override -->
+<div magicScroll [scrollOptions]="{ headerOffset: 16, bottomOffset: 32, activationThreshold: 0.5 }">
+  ...
+</div>
+```
+
+## A region selects its anchors
+
+By default (`anchorSelection: 'all'`), all descendant elements with non-empty IDs participate. This includes IDs on headings or form controls, so a region can contain more anchors than your section navigation exposes.
+
+Use `anchorPrefixes` to restrict automatic selection, and `scrollAnchor` to explicitly include an element even when its ID does not match the prefix:
+
+```html
+<div magicScroll [scrollOptions]="{ anchorPrefixes: ['project-', 'milestone-'] }">
+  <section id="overview" scrollAnchor>Overview...</section>
+  <section id="project-planning">
+    <h2 id="planning-heading">Planning</h2>
+  </section>
+  <section id="milestone-alpha">Alpha release...</section>
+  <section [scrollAnchor]="'project-delivery'">Delivery...</section>
+</div>
+```
+
+The anchors here are `overview`, `project-planning`, `milestone-alpha` and `project-delivery`. The heading's ID (`planning-heading`) is excluded because it matches neither prefix. The bound marker `[scrollAnchor]` also assigns the element's ID; import `ScrollAnchorDirective` when using either marker form.
+
+### Multiple prefixes and strict explicit selection
+
+`magicScroll` provides versatile selection strategies:
+
+- **`anchorPrefixes`**: Specify an array of prefixes (e.g. `['project-', 'milestone-']`). Any descendant element whose ID begins with any of these prefixes participates, along with explicit `scrollAnchor` elements. Passing an empty array `anchorPrefixes: []` disables all prefix matching, allowing only explicit `scrollAnchor` markers to participate.
+- **`anchorSelection: 'explicit'`**: Enables strict explicit-only mode. In this mode, **only** elements explicitly marked with `scrollAnchor` or `[scrollAnchor]` participate in scroll-spy, initial restoration and `scrollTo()`. All other IDs—including auto-generated IDs from component libraries such as Angular Material (`mat-input-*`, `cdk-describedby-*`) or nested form controls—are strictly ignored, even if they match configured prefixes.
+- **`anchorSelection: 'all'` (default)**: Descendant elements matching any configured `anchorPrefixes` (or all descendant IDs if no prefix is set) as well as explicit `scrollAnchor` markers participate.
+
+```ts
+// Example: Strict explicit selection across the application
+provideMagicScroll({
+  anchorSelection: 'explicit',
+});
+```
+
+```html
+<!-- Per-region override supporting multiple prefixes -->
+<div magicScroll [scrollOptions]="{ anchorPrefixes: ['doc-', 'appendix-'] }">...</div>
+```
+
+The same selection applies to scroll-spy tracking, initial restoration and `scrollTo()`. An element can exist in the DOM and still be unavailable to this region because it is excluded by the selection rules. Setting `anchorPrefixes: ['']` on a region clears an inherited prefix and includes all its descendant IDs again.
+
+## Each anchor belongs to its closest region
+
+With nested `magicScroll` regions, each anchor belongs to the closest region containing it. The outer region excludes anchors inside the inner region, even if their IDs match its prefix or have explicit markers.
+
+For example, an outer article can manage its section headings while an inner list manages its items. Calling the outer region's `scrollTo()` with an inner item ID returns `false`. Call the directive instance that owns the target instead.
+
+Region ownership separates target selection. It does not create independent URL state: a route has one fragment, and regions connected to that route share it. Plan which region should control shareable navigation when multiple regions are active.
+
+## The region and scroll container can be different elements
+
+`magicScroll` chooses the container from the layout:
+
+1. The region host itself, if its computed vertical overflow is `auto` or `scroll`.
+2. Otherwise, the closest ancestor with either overflow value.
+3. Otherwise, the document.
+
+CSS supplies the height constraints and overflow that make that container scroll. Adding `magicScroll` alone does not create a scrolling viewport.
+
+A detail region can therefore scroll with the document while a companion sidebar scrolls independently. If the sidebar sits outside the region, its IDs do not become detail anchors. Conversely, placing the region inside a constrained drawer makes the drawer content the scroll container.
+
+## Related documentation
+
+- [URL state and navigation](./url-state-and-navigation.md) explains how selected anchors become URL state.
+- [Anchor navigation](../recipes/scroll-to-anchor.md) implements prefix selection, markers and navigation highlighting.
+- [Angular Material Drawer](../recipes/material-drawer.md) shows a constrained scroll container.
+- [MagicScrollDirective](https://devzwo.github.io/ngx-magic-scroll/api/classes/magicscrolldirective/) and [ScrollAnchorDirective](https://devzwo.github.io/ngx-magic-scroll/api/classes/scrollanchordirective/) document the directive APIs.

package/docs/concepts/data-readiness-and-restoration.md

@@ -0,0 +1,102 @@
+---
+title: Data readiness and restoration
+description: Understand when initial restoration runs and what your application must render first.
+sidebar:
+  order: 3
+---
+
+Initial restoration needs both an anchor identifier and a rendered target. `scrollSource` coordinates restoration with your application's data state. It observes readiness; your application loads the data and renders the elements that the fragment identifies.
+
+## The initial restoration sequence
+
+A region follows this sequence:
+
+1. Capture the route fragment when the directive is created.
+2. Wait for its source to be ready, if a source is supplied.
+3. After rendering, attempt to scroll to the captured anchor.
+4. Finish initial restoration, whether or not the target was found.
+
+Without `scrollSource`, the first rendered DOM is considered ready. This suits static content and data already available from a router resolver.
+
+For asynchronous content, bind the signal or resource that governs the rendered anchors. Pass a signal itself to `scrollSource`, and read its value where you render the collection. This lets readiness track the same data that produces the targets.
+
+## Readiness is a data contract
+
+| Source state                                                 | Initial restoration            |
+| ------------------------------------------------------------ | ------------------------------ |
+| No `scrollSource` supplied                                   | Attempt after the first render |
+| Plain value or signal yielding `null` or `undefined`         | Wait                           |
+| Plain value or signal yielding `[]`, `0`, `false` or `''`    | Ready                          |
+| Resource or neutral source reporting `isLoading()` as `true` | Wait                           |
+| Non-loading resource with an available, non-null value       | Ready                          |
+| Non-loading neutral source with non-null `data()`            | Ready                          |
+
+Angular resources expose `isLoading()`, `hasValue()` and `value()`. A resource with no value, including an error state without a value, cannot trigger restoration. The application owns loading indicators, error presentation and retries.
+
+Readiness does not inspect whether the requested anchor exists. An empty collection is ready even though it contains no item anchors. Likewise, data can be ready while a separate conditional view still hides the target. Expose a source that reflects all prerequisites for rendering the intended content.
+
+For signal forms, use the field's value signal, such as `form().value`, rather than the field tree itself. Source-specific adapters and types are covered by the recipes and API below.
+
+## The first ready render is decisive
+
+Initial restoration is attempted once per directive instance. If the fragment is absent or its target is missing or ineligible at the first ready render, the attempt does not scroll or rewrite the URL. It is not automatically retried as initial restoration when that target appears later.
+
+### Intervening user interaction cancels restoration
+
+If the user interacts with the page or scroll container before data readiness arrives—such as scrolling via mouse wheel, touch gestures, or navigation keys (`ArrowUp`, `ArrowDown`, `PageUp`, `PageDown`, `Space`, `Home`, `End`)—the pending initial restoration is cancelled. This prevents delayed data loading from abruptly overriding the user's conscious navigation.
+
+Typing inside editable form controls (`input`, `textarea`, `select`, or `contenteditable` elements) is safely ignored and does not cancel restoration. Subsequent explicit navigation using `scrollTo()` continues to function normally without restriction.
+
+```mermaid
+graph TD
+    subgraph User & Browser Events
+        UserScroll[User Wheel / Touch / Keyboard]
+        BrowserScroll[Scroll Event]
+        DataUpdate[Data Ready / Resize Event]
+    end
+
+    subgraph MagicScrollDirective
+        IntentDetector{User Intent?}
+        LiveTracker[RAF Live Section Calculator]
+        DebounceTimer[Debounce Timer]
+        PreserveHandler[preserve Realignment]
+        InitialRestore[Initial Restoration]
+    end
+
+    subgraph State
+        LiveAnchor[liveAnchor Signal]
+        URLFragment[URL Route Fragment]
+    end
+
+    UserScroll -->|Intervention| IntentDetector
+    IntentDetector -->|Cancel pending| InitialRestore
+    BrowserScroll --> LiveTracker
+    LiveTracker --> LiveAnchor
+    LiveTracker --> DebounceTimer
+    DebounceTimer --> URLFragment
+    DataUpdate --> PreserveHandler
+    LiveAnchor -->|Source of Truth| PreserveHandler
+```
+
+Later ready source changes can still trigger position preservation using the current active section. That is a separate behavior, described in [Position preservation and layout changes](./position-preservation.md), and should not be used as a strategy for loading a missing initial target.
+
+An explicit `scrollTo()` call also requires an existing target. It does not wait for `scrollSource` to become ready.
+
+## Restore application state before declaring readiness
+
+Consider `/projects?count=16#project-12`:
+
+- The fragment identifies project 12.
+- The query parameter tells the application to load the first 16 items.
+- The source becomes ready after that required range is available.
+- The rendered region can then restore project 12.
+
+If only the first eight items are exposed as ready, the initial attempt cannot find project 12. The library does not fetch additional pages, restore filters or materialize virtualized items.
+
+Restore the relevant filters, ordering and data range in your application before readiness. If an item was deleted or filtered out, choose an application fallback rather than expecting automatic target discovery.
+
+## Related documentation
+
+- [Paginated lists](../recipes/paginated-lists.md) restores the loaded range before the anchor.
+- [Angular rxResource](../recipes/rx-resource.md), [NgRx Signal Store](../recipes/ngrx-signal-store.md) and [TanStack Query](../recipes/tanstack-query.md) connect different data owners.
+- [ScrollSource](https://devzwo.github.io/ngx-magic-scroll/api/type-aliases/scrollsource/), [ScrollResource](https://devzwo.github.io/ngx-magic-scroll/api/interfaces/scrollresource/) and [ScrollDataSource](https://devzwo.github.io/ngx-magic-scroll/api/interfaces/scrolldatasource/) define supported source contracts.

package/docs/concepts/position-preservation.md

@@ -0,0 +1,149 @@
+---
+title: Position preservation and layout changes
+description: Understand how later data updates, resizing and header changes preserve section-relative reading positions.
+sidebar:
+  order: 4
+---
+
+After initial restoration, content and layout can shift dynamically due to asynchronous data insertions, container resizing, or sticky header height changes. `ngx-magic-scroll` implements an **anchor-relative pixel displacement policy** that preserves the active section's pixel displacement, preventing disruptive jumps back to section headings during automatic reflows.
+
+## Different causes have different policies
+
+| Cause                                          | Target                       | Displacement policy                                      | Default behavior                                                |
+| ---------------------------------------------- | ---------------------------- | -------------------------------------------------------- | --------------------------------------------------------------- |
+| Initial ready render                           | Fragment from URL snapshot   | Aligned to heading (`displacement = 0`)                  | Restore once, instantly (unless user cancelled via interaction) |
+| Explicit `scrollTo()`                          | Requested anchor             | Aligned to heading (`displacement = 0`)                  | Scroll smoothly                                                 |
+| External router fragment change                | Route destination anchor     | Aligned to heading (`displacement = 0`)                  | Restore instantly                                               |
+| Later ready source change                      | Current live visible section | Preserves saved pixel displacement (`savedDisplacement`) | Correct instantly without resetting to section top              |
+| Window resize or measured header-height change | Current live visible section | Preserves saved pixel displacement (`savedDisplacement`) | Realign instantly to maintain section pixel offset              |
+| Region content reflow (layout expansion/image) | Current live visible section | Preserves saved pixel displacement (`savedDisplacement`) | Opt-in (`preserveOnLayoutChange: true`); coalesced via rAF      |
+
+The distinction between initial URL fragments, live visible sections, and intentional user navigation ensures seamless reading continuity. When reading halfway through a 1200px card, layout reflows preserve the section's relative pixel position rather than resetting to the card header.
+
+### Live section tracking vs URL debouncing
+
+While scrolling, the active visible section geometry and anchor-relative pixel displacement are captured in real time, whereas updates to the browser's URL router are debounced by `debounceTime` (default 500ms) to avoid cluttering browser history during continuous motion. When automatic realignment or data updates occur during this debounce interval, `ngx-magic-scroll` preserves the real-time visible section and displacement rather than falling back to a stale URL anchor.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User
+    participant Viewport as Scroll Container
+    participant Directive as MagicScrollDirective
+    participant Provider as NearestAnchorProvider
+    participant Service as ScrollService
+
+    Note over User,Directive: User scrolls into long section
+    User->>Viewport: Scroll to midpoint of long card
+    Viewport->>Directive: onScroll event
+    Directive->>Provider: calculateNearestAnchor()
+    Provider-->>Directive: liveAnchor ('card-1')
+    Directive->>Directive: Capture savedDisplacement = anchorRect.top - topBoundary
+
+    Note over Viewport,Directive: Automatic layout reflow occurs
+    alt Data prepended / Container resize / Header resize
+        Viewport->>Directive: Data update / ResizeObserver trigger
+        Directive->>Directive: preserve() called
+        Directive->>Directive: Compute delta = (currentAnchorRect.top - topBoundary) - savedDisplacement
+        Directive->>Service: Adjust scrollable.scrollTop by delta (clamped to bounds)
+        Service->>Viewport: scrollable.scrollTo(targetScrollTop, instant)
+        Note over User,Viewport: Section displacement preserved!
+    end
+```
+
+## Section-relative displacement mechanics
+
+### 1. Displacement capture during user scrolling
+
+As the user scrolls through the container, `onScroll` computes the reading boundary and measures the active section's top offset:
+
+```text
+topBoundary = containerTop + measuredHeaderHeight + headerOffset
+savedDisplacement = activeAnchorElement.getBoundingClientRect().top - topBoundary
+```
+
+For example, when reading 400px deep into a card, `savedDisplacement` is `-400px`.
+
+### 2. Delta calculation and native scroll anchoring compatibility
+
+When automatic reflow occurs (e.g. items prepended above the section, or sticky header expanded):
+
+```text
+currentDisplacement = currentAnchorElement.getBoundingClientRect().top - topBoundary
+delta = currentDisplacement - savedDisplacement
+targetScrollTop = clamp(currentScrollTop + delta, 0, maxScrollTop)
+```
+
+- **Without browser scroll anchoring:** If content is inserted above the section, `currentDisplacement` changes by the height of the prepended items. `delta` equals the shift and `scrollTop` is adjusted instantly, keeping the section visually locked under the reader's view.
+- **With native browser scroll anchoring (`overflow-anchor: auto`):** If the browser has already compensated `scrollTop` for inserted content, `currentDisplacement` remains equal to `savedDisplacement`. `delta` computes to `0`, inherently preventing double-compensation without browser-sniffing heuristics.
+- **Intra-section limitation:** Anchor-relative displacement preserves the active section anchor's pixel offset relative to the reading boundary (`savedDisplacement`). It does not track intra-section elements or percentage progress through a section. Consequently, when text wraps or content changes _inside_ the active section itself, the exact paragraph or sentence being read may still move; retaining a specific paragraph across internal changes requires finer-grained child anchors.
+
+### 3. Reset policy for deliberate navigation
+
+Explicit programmatic calls (`scrollTo('card-2')`) and external router fragment navigations reset `savedDisplacement` to `0`. Intentional navigation always aligns the destination section's heading cleanly to the configured top offset.
+
+### 4. Deterministic element removal handling
+
+If the active section element is removed from the DOM during a data change or layout update, `preserve()` gracefully skips realignment and maintains the current viewport position without arbitrary jumps.
+
+## Region content reflow with preserveOnLayoutChange
+
+In dynamic web applications, presentation-level elements within a scroll region frequently change dimensions without any updates to the fetched data source (`scrollSource`). Common examples include:
+
+- Expanding an accordion or detail disclosure panel above the reader's active section.
+- Asynchronous image loads settling to their natural height without pre-set aspect ratios.
+- Conditional validation messages or interactive preview cards appearing dynamically.
+
+When `preserveOnLayoutChange: true` is enabled, `MagicScrollDirective` attaches a region-scoped `ResizeObserver` to the host element. Layout shifts are coalesced per animation frame (`requestAnimationFrame`) to eliminate layout thrashing and feedback loops.
+
+```mermaid
+graph TD
+    A[Region Content Reflow / Image Loaded / Accordion Expanded] -->|ResizeObserver Callback| B{preserveOnLayoutChange Enabled?}
+    B -->|No| C[Ignore Reflow]
+    B -->|Yes| D{Initialized & Not Interrupted?}
+    D -->|No / User Scrolling| E[Suppress Realignment]
+    D -->|Yes| F{rAF Already Queued?}
+    F -->|Yes| G[Coalesce into Existing Frame]
+    F -->|No| H[Queue requestAnimationFrame]
+    H --> I[Execute preserve()]
+    I --> J[Calculate Delta against liveAnchor & savedDisplacement]
+    J --> K{Delta === 0 or Anchored by Browser?}
+    K -->|Yes| L[No-op: Native overflow-anchor already compensated]
+    K -->|No| M[Scrollable.scrollTo: Adjust scrollTop instantly]
+```
+
+### Supported scenarios vs unsupported modifications
+
+- **Supported (Dimension Changes)**: Any internal DOM expansion or contraction that changes box dimensions (such as toggling accordions, inserting child cards, or loading images) alters the region's layout and triggers instant, seamless realignment.
+- **Unsupported (Position-Only Shifts)**: Pure CSS coordinate changes (such as `transform: translateY(...)` or CSS `top` transitions) that do not alter the box geometry or layout dimensions of elements in the DOM cannot be observed by `ResizeObserver`.
+- **User Gesture Priority**: If the reader is actively scrolling via touch gestures, wheel events, or navigation keys, automated layout realignments yield immediately to user navigation.
+
+## Header measurement defines the top offset
+
+The effective top offset boundary is:
+
+```text
+measured header height + headerOffset
+```
+
+With no configured or matching header, the measured height is zero and `headerOffset` supplies the entire offset. With a header, it adds a gap below that header. Use a `headerSelector` that uniquely identifies the intended element; its height is measured and observed automatically via `ResizeObserver`.
+
+`offset()` exposes the sum, and `headerHeight()` exposes the measurement alone. A sticky companion panel can use the same sum for its CSS `top` so navigation and scroll alignment share one boundary.
+
+A per-call `topOffset` replaces the entire effective offset for that action. It is not an additional gap. Viewport boundary clamping ensures scroll targets are bounded within `[0, scrollHeight - clientHeight]`.
+
+## Choose a policy for your layout
+
+Use `restoreOnDataChange: false` when data updates should let the viewport move naturally without anchor preservation. Use `preserveOnResize: false` when automatic realignment during resizing or header changes is unwanted. Disabling layout corrections still leaves the measured header height and effective offset available.
+
+Initial restoration and explicit interactions have separate behavior defaults: `behavior.restoration` is `instant`, and `behavior.interaction` is `smooth`. Automatic data and layout corrections remain instant.
+
+Provider defaults are inherited through Angular's injector hierarchy. Region `scrollOptions` override those defaults, and supported per-call options override the region for one `scrollTo()` action.
+
+## Related documentation
+
+- [Data readiness and restoration](./data-readiness-and-restoration.md) explains initial restoration, user cancellation, and the event lifecycle diagram.
+- [Sticky master–detail](../recipes/sticky-master-detail.md) shares the measured offset with a sticky sidebar.
+- [Paginated lists](../recipes/paginated-lists.md) shows data updates and optional correction disabling.
+- [MagicScrollOptions](https://devzwo.github.io/ngx-magic-scroll/api/interfaces/magicscrolloptions/) documents configuration defaults and visibility rules.
+- [MagicScrollToOptions](https://devzwo.github.io/ngx-magic-scroll/api/type-aliases/magicscrolltooptions/) documents per-action overrides.