@devzwo/ngx-magic-scroll 1.1.0 → 1.1.2

package/docs/concepts/url-state-and-navigation.md

@@ -0,0 +1,152 @@
+---
+title: URL state and navigation
+description: Understand how scrolling, explicit navigation and restoration use the route fragment.
+sidebar:
+  order: 2
+---
+
+The route fragment is the shared anchor identifier used by scroll tracking, explicit navigation and restoration. These operations use it at different times: scrolling records an anchor, `scrollTo()` requests movement, and a newly created region captures the fragment for initial restoration.
+
+## Scrolling records an anchor
+
+After scrolling settles, the region determines which section the user is currently reading based on an evaluated visible reading area and a hybrid evaluation model:
+
+- **Top boundary (`topBoundary`)**: `containerTop + headerHeight + headerOffset`
+  - For document scrolling, `containerTop` is `0`.
+  - For nested scrollable containers (`overflow: auto | scroll`), `containerTop` is the container's top edge (`getBoundingClientRect().top`).
+  - With `headerSelector`, sticky header height is measured and added dynamically.
+  - With `headerOffset`, custom pixel padding or trigger line offsets are included.
+- **Bottom boundary (`bottomBoundary`)**: `(isDocument ? window.innerHeight : containerBottom) - bottomOffset`
+  - With `bottomOffset`, bottom margins or space occupied by sticky footers and bottom floating bars are excluded from the active evaluation window.
+- **Trigger line (`triggerLine`)**: `topBoundary + (bottomBoundary - topBoundary) * activationThreshold`
+  - With `activationThreshold` (`0.0` to `1.0`, default `0.0`), developers can position the active trigger focal line anywhere across the visible reading band (e.g. `0.3` for upper-third reading focus, `0.5` for center trigger).
+
+### Evaluation Priority
+
+1. **Fully Contained Sections (Full Containment Elevation)**: If an upcoming section is 100% visible within the reading area (`top >= topBoundary - 1` and `bottom <= bottomBoundary + 1`), it becomes active immediately—even if a small tail of the previous section is still visible at the top. If multiple sections are fully visible, the topmost fully contained section is selected.
+2. **Tall Section Reading Retention (Reading Line Fallback)**: For sections that are taller than the viewport (or long multi-paragraph articles), the section remains active while scrolling through its body (`top <= triggerLine + 1`) until a subsequent section crosses the trigger line or becomes fully visible.
+3. **Top of Page Fallback**: When scrolled above all anchors, the first anchor is selected.
+
+```mermaid
+flowchart TD
+    ScrollEvent[User scrolls in viewport/container] --> Debounce[Wait for debounceTime ms<br/><i>default: 500ms</i>]
+    Debounce --> ReadLayout[Measure Layout & Active Configuration]
+
+    subgraph BoundaryCalculation [Boundary & Trigger Line Calculation]
+        ReadLayout --> TopB["topBoundary = containerTop<br/>+ headerHeight(headerSelector)<br/>+ headerOffset"]
+        ReadLayout --> BotB["bottomBoundary = containerBottom<br/>- bottomOffset"]
+        TopB & BotB --> TrigLine["triggerLine = topBoundary +<br/>(bottomBoundary - topBoundary) * activationThreshold"]
+    end
+
+    TrigLine --> CheckContainment{"Any section fully contained in reading band?<br/><i>top >= topBoundary - 1 && bottom <= bottomBoundary + 1</i>"}
+
+    CheckContainment -- Yes --> SelectContained[Select topmost fully contained section]
+    CheckContainment -- No --> CheckTrigger{"Any section top <= triggerLine + 1?"}
+
+    CheckTrigger -- Yes --> SelectTriggered[Select most recently crossed section<br/><i>max top <= triggerLine</i>]
+    CheckTrigger -- No --> SelectFirst[Select first anchor in document]
+
+    SelectContained --> StateUpdate[Active Section Selected]
+    SelectTriggered --> StateUpdate
+    SelectFirst --> StateUpdate
+
+    StateUpdate --> ChangedCheck{"Selected anchor == activeAnchor()?"}
+    ChangedCheck -- No --> SyncFragment["Update activeAnchor() signal<br/>& update URL fragment (replaceUrl)"]
+    ChangedCheck -- Yes --> Noop[Preserve current URL fragment]
+```
+
+Scroll-spy updates are debounced by 500 ms by default (`debounceTime`). During continuous movement, the fragment can therefore lag behind the viewport until scrolling pauses. If there are no eligible candidates, the existing fragment remains unchanged.
+
+`activeAnchor()` exposes the current fragment as a signal and reacts to route-fragment changes. Use it to highlight active navigation links and scroll-spy indicators.
+
+## Explicit navigation requests movement
+
+For a user action within an existing region, call `scrollTo()` on that region:
+
+```html
+<button (click)="scroll.scrollTo('project-12')">Show project 12</button>
+<div magicScroll #scroll="magicScroll">
+  <section id="project-12">Project 12...</section>
+</div>
+```
+
+The target must already be rendered and selected by the region. By default, the call initiates smooth scrolling and updates the fragment. Its boolean return value reports whether scrolling was initiated, not whether the animation has finished.
+
+Optionally, passing `{ focus: true }` transfers DOM focus safely to the target anchor without secondary scroll jumps, managing temporary `tabindex="-1"` for non-focusable landmark containers with automatic cleanup on blur or directive destruction.
+
+A call returns `false` when the target is missing, excluded, owned by another region or skipped by the configured visibility rule. A skipped call does not itself update the fragment. Data readiness does not queue explicit calls for later execution.
+
+## Initial restoration reads the entry fragment
+
+When a region is created, it captures the route's current fragment. Once its content is ready and rendered, it attempts to restore that anchor once. This supports opening a section link, reloading it or returning to a routed list whose region is recreated.
+
+See [Data readiness and restoration](./data-readiness-and-restoration.md) for the timing and missing-target behavior.
+
+## Subsequent router fragment navigation
+
+When external router navigation changes the URL fragment subsequently (e.g. via `[routerLink]`, programmatic `router.navigate()`, or browser history Back/Forward navigation), `MagicScrollDirective` automatically restores the scroll position to the target anchor using `behavior.restoration`.
+
+To prevent feedback loops between user-driven router navigations and the automatic scroll-spy, the library uses internal origin discrimination:
+
+```mermaid
+graph TD
+    RouterLink[RouterLink / History / router.navigate] -->|External Navigation| Router[Angular Router]
+    Router -->|Route Fragment Signal| Directive[MagicScrollDirective]
+    ScrollEvent[Scroll Event] -->|Debounced Scroll Spy| linkedRoute[linkedRouteFragment]
+    linkedRoute -->|Internal Navigation with Origin Tag| Router
+    Directive -->|Filter out Internal Origin| DestinationQueue[Pending Destination Handler]
+    DestinationQueue -->|Wait for Source Ready & DOM| ScrollExec[ScrollService.scroll]
+```
+
+## URL updates yield to in-flight navigations
+
+A scroll-spy update or `scrollTo()` can become due while the Router is still resolving a user navigation. The fragment writer does not start a competing navigation in that case: it retains the latest requested fragment and lets the user's navigation finish without `SupersededByNewNavigation`.
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Router
+    participant Guard as Async guard / resolver / lazy loader
+    participant Writer as linkedRouteFragment
+    participant View as Scroll region
+
+    User->>Router: Navigate to another URL
+    Router->>Guard: Start pending route work
+    Guard-->>Router: Wait for decision or loading
+    View->>Writer: Write the latest visible anchor
+    Writer->>Writer: Defer fragment and remember route path
+    Note over Writer,Router: No competing navigateByUrl is started
+    alt Navigation is canceled, errors or is skipped
+        Router-->>Writer: NavigationCancel / Error / Skipped
+        Writer->>Router: Publish latest fragment with replaceUrl
+    else Navigation ends on the same path without a new fragment
+        Router-->>Writer: NavigationEnd (query may differ)
+        Writer->>Router: Publish latest fragment with replaceUrl
+    else Different path, new fragment or destroyed region
+        Router-->>Writer: NavigationEnd or region destruction
+        Writer->>Writer: Discard deferred fragment
+    end
+```
+
+On `NavigationCancel`, `NavigationError` or `NavigationSkipped`, the last deferred value is published once if it still differs from the URL fragment. After `NavigationEnd`, it is published only when the path (compared without query parameters and fragment) is unchanged; a route change discards it. A fragment explicitly set by the user navigation wins, and a destroyed region never publishes later. The queued write still uses `replaceUrl`, and `scrollTo()` performs its scroll immediately while only its URL update is deferred. Deferred local writes are not treated as external fragment changes by phase-3 restoration.
+
+If a test Router mock omits `currentNavigation()` or `events`, the library keeps its previous immediate-write behavior and emits one `console.warn` per `linkedRouteFragment` instance to make the missing in-flight protection visible.
+
+## URL updates preserve the current history entry
+
+Library fragment updates preserve query parameters and use Angular Router's `replaceUrl`. Scrolling through sections therefore updates the current history entry instead of creating a new entry for every anchor.
+
+For a list-to-detail round trip, these roles are complementary:
+
+1. The list's fragment records the item to return to.
+2. Navigation to the detail page creates the next history entry.
+3. Browser Back returns to the list URL, and the recreated region restores its fragment.
+
+If clicking an item should define the return target, record that item's fragment before leaving and await the URL update. The debounced scroll spy may still name another item at click time. Query parameters can separately preserve filters or the loaded data range; the fragment identifies the section within that restored state.
+
+## Related documentation
+
+- [Return to a list](../recipes/return-to-list.md) implements the history sequence and an explicit return link.
+- [Anchor navigation](../recipes/scroll-to-anchor.md) builds navigation highlighting and per-action overrides.
+- [Scroll regions and anchor identity](./anchors.md) explains eligible targets and shared fragment state.
+- [MagicScrollDirective](https://devzwo.github.io/ngx-magic-scroll/api/classes/magicscrolldirective/) documents `activeAnchor()` and `scrollTo()`.

package/docs/getting-started.md

@@ -0,0 +1,144 @@
+---
+title: Getting started
+description: Install and use ngx-magic-scroll in your Angular application.
+---
+
+This guide shows how to install `@devzwo/ngx-magic-scroll` and add anchor scrolling, URL fragment synchronization and scroll restoration to your Angular application.
+
+## Prerequisites
+
+`ngx-magic-scroll` requires Angular 22.2 and RxJS 7.8 within the supported major versions. Your application must provide Angular Router.
+
+## Installation
+
+Install the library in your Angular project:
+
+```bash
+npm install @devzwo/ngx-magic-scroll
+```
+
+```bash
+pnpm add @devzwo/ngx-magic-scroll
+```
+
+## Configure Angular Router
+
+If your application already provides Angular Router, keep your existing configuration. Otherwise, register it in `app.config.ts`:
+
+```ts
+import { ApplicationConfig } from '@angular/core';
+import { provideRouter } from '@angular/router';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideRouter([])],
+};
+```
+
+Use your application's routes in place of the empty array when adding routed pages.
+
+## Your first scroll region
+
+Import `MagicScrollDirective` in your component and add `magicScroll` to the element containing your sections. Give each section a stable, unique ID:
+
+```ts
+import { Component } from '@angular/core';
+import { MagicScrollDirective } from '@devzwo/ngx-magic-scroll';
+
+@Component({
+  selector: 'app-projects',
+  imports: [MagicScrollDirective],
+  template: `
+    <div magicScroll>
+      <section id="project-1">
+        <h2>Project 1</h2>
+        <p>Project details...</p>
+      </section>
+      <section id="project-2">
+        <h2>Project 2</h2>
+        <p>Project details...</p>
+      </section>
+    </div>
+  `,
+})
+export class ProjectsComponent {}
+```
+
+All descendant IDs participate by default. The directive automatically finds the scroll container, updates the URL fragment while scrolling and restores an initial fragment after rendering. For example, opening the page with `#project-2` scrolls to the second section.
+
+No additional configuration is needed for static content or data already loaded by a router resolver. The page needs enough content to scroll for the movement to be visible.
+
+## Scroll to a section
+
+Export the directive as a template reference and call `scrollTo()` from a button:
+
+```html
+<button (click)="scroll.scrollTo('project-2')">Show project 2</button>
+
+<div magicScroll #scroll="magicScroll">
+  <section id="project-1">Project 1...</section>
+  <section id="project-2">Project 2...</section>
+</div>
+```
+
+The target must already be rendered. User interactions scroll smoothly by default.
+
+## Asynchronous content
+
+When your content loads asynchronously, bind its signal or Angular resource to `scrollSource`. This lets the library wait for the data before restoring the initial fragment.
+
+For example, a signal can start with `undefined` and receive the loaded projects later:
+
+```ts
+import { signal } from '@angular/core';
+
+interface Project {
+  id: number;
+  name: string;
+}
+
+// Inside your component; set this signal when your data has loaded.
+readonly projects = signal<Project[] | undefined>(undefined);
+```
+
+```html
+<div magicScroll [scrollSource]="projects">
+  @for (project of projects(); track project.id) {
+  <section [id]="'project-' + project.id">
+    <h2>{{ project.name }}</h2>
+  </section>
+  }
+</div>
+```
+
+Pass the signal itself as `scrollSource`; call it in the template to render its value. You can also pass an Angular `resource` or `rxResource` directly. Your application remains responsible for fetching data and displaying loading and error states.
+
+## Configure defaults
+
+Optionally register `provideMagicScroll()` alongside your existing providers in `app.config.ts`:
+
+```ts
+import { provideMagicScroll } from '@devzwo/ngx-magic-scroll';
+
+// Add to appConfig.providers:
+provideMagicScroll({
+  anchorPrefixes: ['project-'],
+  headerSelector: '.app-header',
+  headerOffset: 16,
+});
+```
+
+This limits automatic anchors to IDs starting with `project-` and leaves a 16-pixel gap below your header. The library measures the header's height automatically. Use a selector matching your application's header.
+
+Override defaults for an individual scroll region with `scrollOptions`:
+
+```html
+<div magicScroll [scrollOptions]="{ headerOffset: 24 }">
+  <section id="project-1">Project 1...</section>
+</div>
+```
+
+## Next steps
+
+- [Concepts](./concepts/anchors.md): understand anchor ownership and scroll containers, then explore URL state, restoration and layout changes.
+- [Anchor navigation](./recipes/scroll-to-anchor.md): explicit anchors, navigation highlighting and per-action options.
+- [API reference](https://devzwo.github.io/ngx-magic-scroll/api/readme/): directives, configuration and supported data source types.

package/docs/migrations/v0.0.1-rc.1-to-0.0.1-rc.2.md

@@ -0,0 +1,177 @@
+---
+title: 'Migration Guide: v0.0.1-rc.1 to v0.0.1-rc.2'
+description: 'Upgrade instructions and code transformations for updating @devzwo/ngx-magic-scroll from v0.0.1-rc.1 to v0.0.1-rc.2.'
+---
+
+This guide details the new configuration options, behavioral improvements, and SSR enhancements when upgrading `@devzwo/ngx-magic-scroll` from `v0.0.1-rc.1` to `v0.0.1-rc.2`.
+
+## Overview of Changes
+
+Release `v0.0.1-rc.2` introduces key improvements to scroll-spy precision, restoration lifecycle handling, and server-side rendering resilience:
+
+- **Active Reading Area & Trigger Lines**: Configurable `bottomOffset` and `activationThreshold` options to fine-tune section detection and exclusion zones.
+- **User Interaction Cancellation**: User input (wheel, touch, keyboard scroll keys) prior to data readiness gracefully cancels pending initial scroll restoration without breaking programmatic navigation.
+- **Server-Side Rendering (SSR) Resilience**: Improved guards for environments where `ResizeObserver` or `defaultView` is unavailable.
+
+---
+
+## 1. Configuring Active Reading Boundaries and Trigger Lines
+
+### Previous Behavior (v0.0.1-rc.1)
+
+In `v0.0.1-rc.1`, scroll-spy calculations used a fixed top reference line (factoring in `headerOffset` and `headerSelector`). When scrolling through long pages with floating action bars, footers, or tall cards, active section detection could activate too late or trigger outside the reader's primary viewing zone.
+
+### Updated Configuration (v0.0.1-rc.2)
+
+`v0.0.1-rc.2` adds two options to `MagicScrollOptions`:
+
+- `bottomOffset`: Defines a bottom exclusion boundary in pixels (e.g. for sticky bottom bars or mobile navigation).
+- `activationThreshold`: A relative factor between `0.0` (top) and `1.0` (bottom) defining where within the effective reading area the active anchor trigger line sits.
+
+#### Before (v0.0.1-rc.1)
+
+<!-- recipe-check: migration-rc1-rc2-before.ts -->
+
+```ts
+import { Component } from '@angular/core';
+import {
+  MagicScrollDirective,
+  ScrollAnchorDirective,
+  provideMagicScroll,
+} from '@devzwo/ngx-magic-scroll';
+
+@Component({
+  selector: 'app-migration-rc1-sample-before',
+  imports: [MagicScrollDirective, ScrollAnchorDirective],
+  providers: [
+    provideMagicScroll({
+      headerOffset: 64,
+    }),
+  ],
+  template: `
+    <div magicScroll>
+      <section id="intro" scrollAnchor>
+        <h2>Introduction</h2>
+      </section>
+      <section id="specs" scrollAnchor>
+        <h2>Specifications</h2>
+      </section>
+    </div>
+  `,
+})
+export class MigrationRc1SampleBeforeComponent {}
+```
+
+#### After (v0.0.1-rc.2)
+
+<!-- recipe-check: migration-rc1-rc2-after.ts -->
+
+```ts
+import { Component } from '@angular/core';
+import {
+  MagicScrollDirective,
+  ScrollAnchorDirective,
+  provideMagicScroll,
+} from '@devzwo/ngx-magic-scroll';
+
+@Component({
+  selector: 'app-migration-rc1-sample-after',
+  imports: [MagicScrollDirective, ScrollAnchorDirective],
+  providers: [
+    provideMagicScroll({
+      headerOffset: 64,
+      bottomOffset: 48,
+      activationThreshold: 0.25,
+    }),
+  ],
+  template: `
+    <div
+      magicScroll
+      [scrollOptions]="{
+        headerOffset: 64,
+        bottomOffset: 48,
+        activationThreshold: 0.25,
+      }"
+    >
+      <section id="intro" scrollAnchor>
+        <h2>Introduction</h2>
+      </section>
+      <section id="specs" scrollAnchor>
+        <h2>Specifications</h2>
+      </section>
+    </div>
+  `,
+})
+export class MigrationRc1SampleAfterComponent {}
+```
+
+---
+
+## 2. Interaction-Aware Scroll Restoration Lifecycle
+
+### Behavioral Improvement
+
+In `v0.0.1-rc.1`, when a page loaded with a pending URL fragment and asynchronous data source (`scrollSource`), initial position restoration waited for data readiness. If the user scrolled manually before data arrived, the subsequent delayed restoration could jump the page unexpectedly.
+
+In `v0.0.1-rc.2`:
+
+- User interactions (mouse wheel, touch drag, keyboard navigation keys like `PageDown`, `ArrowDown`, `Space`) cancel pending initial restoration.
+- Focus or keystrokes inside editable fields (`<input>`, `<textarea>`, `contenteditable`) do not cancel restoration.
+- Programmatic calls to `scrollTo()` remain fully functional and are never blocked by prior user cancellation.
+
+<!-- recipe-check: migration-rc1-rc2-thresholds.ts -->
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  MagicScrollDirective,
+  ScrollAnchorDirective,
+  provideMagicScroll,
+} from '@devzwo/ngx-magic-scroll';
+
+interface Item {
+  readonly id: string;
+  readonly title: string;
+}
+
+@Component({
+  selector: 'app-migration-rc1-async-sample',
+  imports: [MagicScrollDirective, ScrollAnchorDirective],
+  providers: [provideMagicScroll()],
+  template: `
+    <div magicScroll [scrollSource]="items()">
+      @for (item of items(); track item.id) {
+        <article [id]="item.id" scrollAnchor>
+          <h3>{{ item.title }}</h3>
+        </article>
+      }
+    </div>
+  `,
+})
+export class MigrationRc1AsyncSampleComponent {
+  // undefined simulates loading; user scrolling during this phase cancels initial jump safely
+  readonly items = signal<Item[] | undefined>(undefined);
+
+  constructor() {
+    setTimeout(() => {
+      this.items.set([
+        { id: 'item-1', title: 'First Item' },
+        { id: 'item-2', title: 'Second Item' },
+      ]);
+    }, 150);
+  }
+}
+```
+
+---
+
+## 3. Server-Side Rendering (SSR) Resilience
+
+`v0.0.1-rc.2` enhances SSR compatibility by guarding observer instantiation (`ResizeObserver`, `MutationObserver`) and window references (`defaultView`). No code changes are required in your templates or providers; the directive safely skips DOM-only observers in SSR environments.
+
+---
+
+## 4. Deprecations and Breaking Changes
+
+- **Breaking Changes**: None. Default parameters preserve compatibility with `v0.0.1-rc.1`.
+- **Deprecations**: None.

package/docs/migrations/v0.0.1-rc.2-to-1.0.0.md

@@ -0,0 +1,176 @@
+---
+title: 'Migration Guide: v0.0.1-rc.2 to v1.0.0'
+description: 'Upgrade instructions and code transformations for updating @devzwo/ngx-magic-scroll from v0.0.1-rc.2 to v1.0.0.'
+---
+
+This guide details the major features, navigation automation, anchor selection modes, and recommended upgrade steps when moving `@devzwo/ngx-magic-scroll` from `v0.0.1-rc.2` to `v1.0.0`.
+
+## Overview of Changes
+
+Release `v1.0.0` marks the first stable production release of `@devzwo/ngx-magic-scroll`. Key enhancements include:
+
+- **Automatic Subsequent Router Fragment Navigation**: Subsequent Angular router navigation with URL fragments is handled automatically without manual router event subscriptions.
+- **Asynchronous Mutation Retry Queue**: Pending scroll targets are queued and retried automatically via `MutationObserver` until matching DOM elements appear.
+- **Multi-Prefix Anchor Matching**: `anchorPrefixes` accepts an array of string prefixes to match multiple naming schemes across complex views.
+- **Strict Explicit Anchor Mode**: `anchorSelection: 'explicit'` mode restricts anchor discovery exclusively to elements marked with `[scrollAnchor]`.
+- **Browser Popstate & History Restoration**: Full coordination with browser back and forward navigation for restoring prior scroll positions.
+
+---
+
+## 1. Automatic Router Fragment Navigation & Retry Queues
+
+### Previous Behavior (v0.0.1-rc.2)
+
+In `v0.0.1-rc.2`, the directive focused on initial URL fragment restoration on page load. Navigating between fragments on the same route often required manual event listening or custom imperative calls to `scrollTo()`. Furthermore, if an anchor was rendered asynchronously after a route transition, navigation could fail if the element wasn't immediately present.
+
+### Updated Behavior (v1.0.0)
+
+In `v1.0.0`, `MagicScrollDirective` automatically subscribes to Angular Router fragment changes throughout the component lifecycle. If the target element is not in the DOM immediately (e.g. while data is fetching or templates are rendering), the directive queues the navigation request and retries automatically via `MutationObserver` until the element is mounted.
+
+<!-- recipe-check: migration-rc2-v1-navigation.ts -->
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import {
+  MagicScrollDirective,
+  ScrollAnchorDirective,
+  provideMagicScroll,
+} from '@devzwo/ngx-magic-scroll';
+
+@Component({
+  selector: 'app-migration-rc2-router-nav',
+  imports: [RouterLink, MagicScrollDirective, ScrollAnchorDirective],
+  providers: [provideMagicScroll()],
+  template: `
+    <nav>
+      <!-- Subsequent fragment clicks automatically scroll and update active anchor in v1.0.0 -->
+      <a routerLink="." fragment="overview">Overview</a>
+      <a routerLink="." fragment="pricing">Pricing</a>
+      <a routerLink="." fragment="faq">FAQ</a>
+    </nav>
+
+    <div magicScroll>
+      <section id="overview" scrollAnchor>
+        <h2>Overview</h2>
+      </section>
+      <section id="pricing" scrollAnchor>
+        <h2>Pricing</h2>
+      </section>
+      <section id="faq" scrollAnchor>
+        <h2>FAQ</h2>
+      </section>
+    </div>
+  `,
+})
+export class MigrationRc2RouterNavComponent {}
+```
+
+---
+
+## 2. Multi-Prefix Anchor Matching
+
+### Previous Configuration (v0.0.1-rc.2)
+
+In `v0.0.1-rc.2`, anchor discovery matched either all DOM IDs or elements starting with a single configured prefix.
+
+### Updated Configuration (v1.0.0)
+
+`v1.0.0` supports `anchorPrefixes` as an array of prefixes (`string[]`). Elements matching any of the prefixes are registered automatically as anchors.
+
+<!-- recipe-check: migration-rc2-v1-prefixes.ts -->
+
+```ts
+import { Component } from '@angular/core';
+import { MagicScrollDirective, provideMagicScroll } from '@devzwo/ngx-magic-scroll';
+
+@Component({
+  selector: 'app-migration-rc2-prefixes-sample',
+  imports: [MagicScrollDirective],
+  providers: [
+    provideMagicScroll({
+      // Match anchors with either prefix across the application
+      anchorPrefixes: ['section-', 'module-'],
+    }),
+  ],
+  template: `
+    <div magicScroll>
+      <!-- Automatically registered via 'section-' prefix -->
+      <section id="section-header">
+        <h2>Header Section</h2>
+      </section>
+
+      <!-- Automatically registered via 'module-' prefix -->
+      <section id="module-analytics">
+        <h2>Analytics Module</h2>
+      </section>
+
+      <!-- Ignored by scroll-spy because prefix does not match -->
+      <div id="unrelated-dom-id">
+        <p>Regular container</p>
+      </div>
+    </div>
+  `,
+})
+export class MigrationRc2PrefixesSampleComponent {}
+```
+
+---
+
+## 3. Strict Explicit Anchor Selection Mode
+
+### Previous Configuration (v0.0.1-rc.2)
+
+In `v0.0.1-rc.2`, all child elements with an `id` attribute were candidates for anchor navigation unless filtered by prefixes.
+
+### Updated Configuration (v1.0.0)
+
+`v1.0.0` introduces `anchorSelection: 'explicit'`. When enabled, only elements with the `[scrollAnchor]` or `scrollAnchor` directive are recognized, ignoring standard DOM IDs entirely:
+
+<!-- recipe-check: migration-rc2-v1-explicit.ts -->
+
+```ts
+import { Component } from '@angular/core';
+import {
+  MagicScrollDirective,
+  ScrollAnchorDirective,
+  provideMagicScroll,
+} from '@devzwo/ngx-magic-scroll';
+
+@Component({
+  selector: 'app-migration-rc2-explicit-sample',
+  imports: [MagicScrollDirective, ScrollAnchorDirective],
+  providers: [
+    provideMagicScroll({
+      // Only recognize elements explicitly tagged with scrollAnchor
+      anchorSelection: 'explicit',
+    }),
+  ],
+  template: `
+    <div magicScroll>
+      <!-- Explicit anchor directive included -->
+      <section id="features" scrollAnchor>
+        <h2>Features</h2>
+      </section>
+
+      <!-- Explicit anchor with dynamic input ID binding -->
+      <section [scrollAnchor]="'reviews'">
+        <h2>Reviews</h2>
+      </section>
+
+      <!-- Excluded from anchor tracking even though it has an ID -->
+      <div id="internal-widget">
+        <p>Widget content</p>
+      </div>
+    </div>
+  `,
+})
+export class MigrationRc2ExplicitSampleComponent {}
+```
+
+---
+
+## 4. Deprecations and Breaking Changes
+
+- **Breaking Changes**: None. Upgrading to `v1.0.0` preserves backwards compatibility with existing `v0.0.1-rc.2` options.
+- **Deprecations**: None.