help-layer 1.1.0 → 1.3.0

package/README.ja.md

@@ -3,6 +3,7 @@
 [![npm](https://img.shields.io/npm/v/help-layer.svg)](https://www.npmjs.com/package/help-layer)
 [![license](https://img.shields.io/npm/l/help-layer.svg)](./LICENSE)
 [![repo](https://img.shields.io/badge/GitHub-Y1--Effy%2FHelpLayer-181717?logo=github)](https://github.com/Y1-Effy/HelpLayer)
+[![coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Y1-Effy/f1479376394b26b678f9e97095d88d95/raw/coverage.json)](https://github.com/Y1-Effy/HelpLayer/actions/workflows/ci.yml)
 
 [English](./README.md) | **日本語**
 
@@ -14,9 +15,9 @@
 ユーザーが「解説モード」を ON にしている間だけ、知りたい要素の「？」マーカーをクリックして説明を読めます。通常時の見た目は一切変わりません。
 仕組みは透明な遮断レイヤー — 対象要素の近くにマーカーを出しつつ、元アプリのイベントには一切触れずに操作を吸収します。
 
-- 依存は [`@floating-ui/dom`](https://floating-ui.com/) のみ・軽量（プリビルドの IIFE で約 33KB minified、`@floating-ui/dom` 同梱）
+- 実行時依存ゼロ・軽量（プリビルドの IIFE で約 20KB minified）
 - Shadow DOM 貫通・SPA の動的要素・マーカー同士の重なり回避・画面端でのポップアップ自動調整に対応
-- キーボード操作・スクリーンリーダーに配慮（ポップアップは `role="dialog"`、開くとフォーカスを移し閉じるとマーカーへ復帰。モード中はフォーカスを UI 内に封じ込め、`Esc` で閉じる）
+- キーボード操作・スクリーンリーダーに配慮（ポップアップは `role="dialog"`、開くとフォーカスを移し閉じるとマーカーへ復帰。モード中はフォーカスを UI 内に封じ込め、`Esc` で説明を閉じる（開いている説明が無ければ解説モード自体を終了））
 - ON→OFF で追加した DOM・イベント・スタイルを**完全後始末**
 - モダンブラウザ（Chromium / Firefox / WebKit）で動作（e2e を 3 エンジンで検証）
 
@@ -28,8 +29,12 @@
 - [クイックスタート](#クイックスタート)
 - [自由配置（要素に紐づけない説明）](#自由配置要素に紐づけない説明)
 - [API](#api)
+- [API の上に作るレシピ（分析・ディープリンク・検索・フレームワーク連携）](./RECIPES.ja.md)
 - [テーマ（CSS カスタムプロパティ）](#テーマcss-カスタムプロパティ)
+- [対応環境（ブラウザ／ランタイム）](#対応環境ブラウザランタイム)
 - [既知の制約](#既知の制約)
+- [パフォーマンス（マーカー数の目安）](#パフォーマンスマーカー数の目安)
+- [アクセシビリティ](#アクセシビリティ)
 - [セキュリティ](#セキュリティ)
 - [開発](#開発)
 
@@ -44,7 +49,7 @@
 - **常設ツールチップとの違い** … 説明を常時表示してUIを煩雑にすることがありません。マーカーは
   **モードON中だけ**出るので、**通常時のデザインは一切変わりません**。
 - **DAP系SaaS（Digital Adoption Platform＝定着化支援 SaaS）との違い**
-  … 外部基盤・契約・トラッキングを必要とせず、**ランニングコスト0・依存1つ・約33KB の完全ローカル動作**。
+  … 外部基盤・契約・トラッキングを必要とせず、**ランニングコスト0・依存ゼロ・約20KB の完全ローカル動作**。
   CSP / Trusted Types にも対応するため、持ち込み制約の厳しい環境にも入ります。
 
 そのうえで共通の核として、**既存コードを書き換えずに後付け**でき、**フレームワーク非依存**で、
@@ -55,16 +60,19 @@
 | 提示形式 | 線形ステップになりがち | 常時表示になりがち | サービス依存 | **モードON中だけ・任意箇所を探索** |
 | 通常時のUI | 実装次第 | 煩雑になりがち | 実装次第 | **一切変えない** |
 | 導入方法 | 多くは要組み込み | CSS/JS を追記 | スニペット＋外部基盤＋契約 | **後付け・既存コード非改変** |
-| コスト／運用 | 実装次第 | ローカル | 月額＋トラッキング運用 | **ランニング0・依存1つ** |
+| コスト／運用 | 実装次第 | ローカル | 月額＋トラッキング運用 | **ランニング0・依存ゼロ** |
 
 > ※ HelpLayer は DAP の **フル代替ではありません**。アナリティクスやセグメント別配信、複雑なフロー誘導・
 > オンボーディング自動化といった高機能は対象外で、**「画面内に説明を出す」というコア機能だけを最小コストで満たす**ことに
 > 振り切っています。逆に、強い導線を引きたい・利用状況を計測したいといった目的が主なら、DAP やツアーの方が向きます。
+>
+> とはいえ、これらのいくつか（分析・ディープリンク・検索パネル・フレームワーク連携）は、公開 API の
+> *上に* 数行で作れます。レシピは **[RECIPES.ja.md](./RECIPES.ja.md)** を参照してください。
 
 ## こんなときに（導入が刺さるケース）
 
 - **DAP／ガイド系 SaaS のコストが見合わず、解約を検討している。でも解約すると画面内ヘルプがゼロに戻る。**
-  → 「画面内に説明を出す」というコア機能だけを、依存1つ・ランニングコスト0 で自前に残せます。乗り換え後の受け皿に。
+  → 「画面内に説明を出す」というコア機能だけを、依存ゼロ・ランニングコスト0 で自前に残せます。乗り換え後の受け皿に。
 - **SaaS を契約する予算感はないが、ヘルプは拡張したい。**
   → npm か `<script>` 1本で後付け。月額もアカウントも要りません。
 - **オフィスソフトで別途マニュアルを作る・更新するのが重い。しかも作っても読まれない。**
@@ -137,7 +145,7 @@ CDN から読む場合は、改ざん検知のため **バージョンを固定*
 
 ```html
 <script
-  src="https://unpkg.com/help-layer@1.0.1/dist/help-layer.iife.js"
+  src="https://unpkg.com/help-layer@1.3.0/dist/help-layer.iife.js"
   integrity="sha384-……（公開版のハッシュに差し替え）"
   crossorigin="anonymous"></script>
 <script>
@@ -149,7 +157,7 @@ CDN から読む場合は、改ざん検知のため **バージョンを固定*
 ```
 
 > `integrity` のハッシュは公開した実ファイルから生成します。例:
-> `curl -s https://unpkg.com/help-layer@1.0.1/dist/help-layer.iife.js | openssl dgst -sha384 -binary | openssl base64 -A`
+> `curl -s https://unpkg.com/help-layer@1.3.0/dist/help-layer.iife.js | openssl dgst -sha384 -binary | openssl base64 -A`
 > （バージョンを固定しないと SRI と不整合になり読み込みが拒否されます。）
 
 ## 自由配置（要素に紐づけない説明）
@@ -233,7 +241,7 @@ initHelpLayer({
 
 | 変数 | 既定 | 用途 |
 |------|------|------|
-| `--help-layer-marker-size` | `22px` | マーカー直径 |
+| `--help-layer-marker-size` | `24px` | マーカー直径（WCAG 2.5.8 の最小ターゲットサイズに合わせた既定） |
 | `--help-layer-marker-bg` | `#2563eb` | マーカー背景色 |
 | `--help-layer-marker-color` | `#fff` | マーカー文字色 |
 | `--help-layer-popup-bg` | `#fff` | ポップアップ背景色 |
@@ -244,19 +252,102 @@ initHelpLayer({
 | `--help-layer-overlay-bg` | `transparent` | 遮断レイヤー（スクリム）背景色。`rgba(0,0,0,0.15)` 等で操作不能状態を可視化 |
 | `--help-layer-overlay-cursor` | `default` | 遮断領域上のカーソル。`not-allowed` / `help` 等 |
 
+## 対応環境（ブラウザ／ランタイム）
+
+HelpLayer は **現代的な evergreen ブラウザ**（Chrome / Edge・Firefox・Safari）と近年の Electron の
+Chromium を対象とします。**IE11 は非対応であり、構造上対応できません** — ES2020 構文・ES Modules・
+Shadow DOM・`clip-path` に依存しており、IE はいずれも備えていないためです。これは
+パッケージ形式の調整では埋められません。本当に古いランタイムを対象とする必要がある場合、本ライブラリは
+適合しません。
+
+下限を決める要素（新しい2つの API は縮退するため、実質的なハード下限はおよそ **2020 年代の evergreen**）:
+
+| 機能 | 用途 | 下限の目安 | フォールバック |
+|---|---|---|---|
+| ES2020＋ES Modules | ライブラリ全体 | evergreen（〜2020） | なし（古い対象はトランスパイル／バンドルが必要） |
+| `requestAnimationFrame` | マーカー／ポップアップの自動配置（毎フレーム追従） | evergreen | なし |
+| open Shadow DOM 貫通 | shadow root 内の対象探索 | evergreen | closed は設計上非対応 |
+| `clip-path: polygon()` | 遮断レイヤーのトグル「穴」 | evergreen（極端に古い Safari は `-webkit-` 必要） | なし |
+| `inert` | ホストを a11y ツリーから除外 | Chrome102 / FF112 / Safari15.5（2023） | 視覚＋キーボード遮断のみに縮退 |
+| `Element.checkVisibility()` | 対象が隠れた時にマーカーも隠す | Chrome105 / FF125 / Safari17.4（2024） | 0×0 rect 判定に縮退（`display:none` のみ検出） |
+
+### モジュール形式
+
+- **ESM（既定）**: `import { initHelpLayer } from 'help-layer'` はビルド済み・テスト済みの
+  `dist/help-layer.esm.js` を解決します（自己完結・解決すべき実行時依存なし）。
+- **バンドラ無し／`<script>`／CDN／厳格環境**: グローバル `HelpLayer` を公開する
+  自己完結の IIFE ビルドを使用 — [`<script>` だけで使う](#script-だけで使うバンドラなし) 参照。
+- **CommonJS（`require`）**: `require` 入口は提供しません。ブラウザ DOM 専用のため Node の CJS 文脈では
+  意味を持ちません。非 ESM のツールチェーンではバンドラ経由で ESM を取り込むか、上記 IIFE を読み込んでください。
+
 ## 既知の制約
 
 - closed な Shadow DOM は JS から到達できないため非対応（open のみ貫通）。
-- マーカーを隅へ重ねるオフセットは既定マーカーサイズ（22px）前提。`--help-layer-marker-size` を大きく変えると
+- マーカーを隅へ重ねるオフセットは既定マーカーサイズ（24px）前提。`--help-layer-marker-size` を大きく変えると
   わずかにズレることがあります。
+- **対象要素の「状態」変化は監視しません**（監視するのは「レイアウト」と「DOM 上の有無」のみ）。ON 中、
+  マーカーは対象の位置・サイズ変化に追従し、DOM への追加／削除に応じて mount／unmount され、対象自体が
+  隠れる／現れる（`display:none` 等）とマーカーも隠れる／戻ります。一方で、対象の**属性・内容の変化**は
+  検知しません — 既存要素への `data-help-id` の後付け／除去、`data-help-title` `data-help-text` の書き換え、
+  `disabled` 等の状態切り替えはマーカーに反映されません。これは意図的な制約です。文書全体に属性監視
+  （`MutationObserver` の `attributes: true, subtree: true`）を張ると、あらゆるクラス／スタイル変更で発火し、
+  ドロップイン型ライブラリとしては性能上のアンチパターンになるためです。これらの状態を変えた場合は、
+  `update(config)` で作り直す、モードを OFF→ON する、または対象要素を一度 DOM から外して入れ直してください
+  （入れ直しは `childList` 監視に乗ります）。
+
+## パフォーマンス（マーカー数の目安）
+
+コストは **同時に表示しているマーカー数** に比例します（登録した `config` の総数ではありません）。
+表示中の全マーカーは **1 本の共有 `requestAnimationFrame` ループ** でまとめて配置します（マーカーごとの
+監視や外部の配置ライブラリは使いません）。そのためスクロール中・アニメーション中も、1 フレームにつき
+表示中マーカーをまとめた read → compute → write の 1 パスだけが走ります。
+マーカーは **モード ON 中、かつ DOM 上に存在して表示されている対象にのみ** 出ます。`display:none`
+などで隠れた対象（`checkVisibility` が「隠れている」と判定した対象）のマーカーは、再配置・レイアウト
+計測・重なり回避のいずれからも除外されます。つまり効いてくるのは「いま画面に出ている数」です。
+
+マーカー同士の重なり回避は 1 パスあたり `O(n²)` ですが、反復回数に上限があり定数も小さく、かつ実際に
+動いたフレームだけ実行されます。1 パスで読む矩形は表示中の参照要素ぶん各 1 回のみ（read と write を
+フェーズ分離するのでレイアウトスラッシングは起きません）。規模で最初に効いてくるのは、表示中マーカー数
+に比例して増える毎フレームの追従コストのほうです。
+
+目安（**同時に表示する**マーカー数）:
+
+- **数百個まで** … 一般的な端末で快適。
+- **〜1000 個** … 実測でも滑らか（同梱のストレスページで自動スクロール中も 60fps を維持）。
+- **それを大きく超える** … スクロール／アニメ中の毎フレーム追従コストがいずれ目立ち始めます。
+
+とはいえこのモードは **探索型**（利用者が見たい箇所を選ぶ）なので、一画面に数十個もあれば十分なことが
+ほとんどです。大規模ページでは対象を絞る、ページ／タブ単位で出し分ける（`update(config)` でセットを
+差し替える、別の `attribute` を使う等）として、同時に出す数を抑えるとよいでしょう。これは
+[既知の制約](#既知の制約) で文書全体に属性監視を張らない選択をしたのと同じ理由 — どちらも「割に合わない
+毎フレーム処理」を避けるためです。
+
+## アクセシビリティ
+
+モード ON 中は、ホストアプリを視覚・ポインタ／キーボードだけでなく **支援技術（AT）に対しても意味的に
+無効化**します。ホストを [`inert`](https://developer.mozilla.org/ja/docs/Web/HTML/Global_attributes/inert)
+属性で a11y ツリーから除外するため、スクリーンリーダーの仮想カーソル（ブラウズモード）でも背景の読み上げ・
+操作ができません。到達できるのはヘルプマーカー・ポップアップ・トグルのみです。ポップアップは
+`aria-modal="true"` を持つ `role="dialog"` で、開くとフォーカスが移り、閉じるとマーカーへ戻ります。
+
+この隔離の限定事項:
+
+- `inert` は inert なサブツリーの子孫で打ち消せないため、隔離は document body の直下レベルで適用します
+  （トグルを透過させる clip-path の"穴"と同じ考え方）。トグルは操作可能である必要があるので、
+  **トグルを含む body 直下ブランチは到達可能なまま残します** — 漏れを最小化するにはトグルを body 直下
+  （または近い位置）に置いてください（直下の `<body>` 子要素なら漏れゼロ）。
+- `inert` は現行ブラウザで広くサポートされます。非対応環境でも視覚／キーボードの遮断は有効で、AT 除外だけが
+  グレースフルに縮退します（エラーにはなりません）。
 
 ## セキュリティ
 
+脆弱性の報告方法・サポート方針・セキュリティリリース方針は [SECURITY.ja.md](./SECURITY.ja.md) を参照してください。報告は公開 issue ではなく GitHub の非公開脆弱性報告をご利用ください。
+
 - 設計上、`title` / `text` の描画は `textContent` のみで、`innerHTML` / `eval` / `new Function` は**一切使いません**。
 - 外部通信（`fetch` 等）・`localStorage` / `cookie` などのストレージ利用も**ありません**（完全ローカル動作）。
 - 唯一、未信頼データを HTML／DOM ノードとして挿入しうる経路は `render` オプションです。戻り値はサニタイズされないため、
   ユーザー入力を含む場合は呼び出し側で無害化してください（上記「本文に改行を入れる / リンクを置く」参照）。
-- ランタイム依存は `@floating-ui/dom` のみ。CDN 利用時は前述のとおりバージョン固定＋SRI を推奨します。
+- 実行時依存はありません。CDN 利用時は前述のとおりバージョン固定＋SRI を推奨します。
 
 ### Content Security Policy（CSP）
 

package/README.md

@@ -3,6 +3,7 @@
 [![npm](https://img.shields.io/npm/v/help-layer.svg)](https://www.npmjs.com/package/help-layer)
 [![license](https://img.shields.io/npm/l/help-layer.svg)](./LICENSE)
 [![repo](https://img.shields.io/badge/GitHub-Y1--Effy%2FHelpLayer-181717?logo=github)](https://github.com/Y1-Effy/HelpLayer)
+[![coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Y1-Effy/f1479376394b26b678f9e97095d88d95/raw/coverage.json)](https://github.com/Y1-Effy/HelpLayer/actions/workflows/ci.yml)
 
 **English** | [日本語](./README.ja.md)
 
@@ -14,9 +15,9 @@ A **framework-agnostic "help mode" library you can drop into any existing web ap
 While the mode is ON, it shows a "?" marker next to each target element; clicking it opens a description popup. The normal appearance is completely unchanged.
 It never touches the host app's own event listeners — a transparent blocking layer absorbs interaction instead — so you can adopt it without rewriting existing code.
 
-- Only one dependency, [`@floating-ui/dom`](https://floating-ui.com/); lightweight (the prebuilt IIFE is ~33KB minified, with `@floating-ui/dom` bundled in)
+- Zero runtime dependencies; lightweight (the prebuilt IIFE is ~20KB minified)
 - Pierces Shadow DOM, keeps up with dynamically added/removed elements in SPAs, avoids marker-to-marker overlap, and auto-adjusts the popup at screen edges
-- Mindful of keyboard use and screen readers (the popup is `role="dialog"`; opening moves focus and closing returns it to the marker; while the mode is on, focus is trapped within the UI, and `Esc` closes it)
+- Mindful of keyboard use and screen readers (the popup is `role="dialog"`; opening moves focus and closing returns it to the marker; while the mode is on, focus is trapped within the UI, and `Esc` closes the popup — or exits the mode when no popup is open)
 - Fully cleans up the DOM, listeners, and styles it added when you turn it OFF
 - Works in modern browsers (Chromium / Firefox / WebKit; e2e is verified across all three engines)
 
@@ -28,8 +29,12 @@ It never touches the host app's own event listeners — a transparent blocking l
 - [Quick start](#quick-start)
 - [Free placement (descriptions not bound to an element)](#free-placement-descriptions-not-bound-to-an-element)
 - [API](#api)
+- [Recipes on top of the API (analytics, deep-linking, search, frameworks)](./RECIPES.md)
 - [Theming (CSS custom properties)](#theming-css-custom-properties)
+- [Browser & runtime support](#browser--runtime-support)
 - [Known limitations](#known-limitations)
+- [Performance (how many markers)](#performance-how-many-markers)
+- [Accessibility](#accessibility)
 - [Security](#security)
 - [Development](#development)
 
@@ -45,7 +50,7 @@ them on the spot,"** aiming to sacrifice neither the normal look nor your existi
 - **vs. always-on tooltips** … It never clutters the UI by showing explanations all the time. Markers
   appear **only while the mode is ON**, so **the normal design is completely unchanged**.
 - **vs. DAP SaaS (Digital Adoption Platform)** … No external platform, contract, or tracking required —
-  **zero running cost, one dependency, ~33KB, fully local**. It also supports CSP / Trusted Types, so it
+  **zero running cost, zero dependencies, ~20KB, fully local**. It also supports CSP / Trusted Types, so it
   fits environments with strict constraints on what you can bring in.
 
 On top of that, they all share a common core: you can **drop it in without rewriting existing code**, it's
@@ -57,18 +62,21 @@ interaction), and it **fully cleans up on ON→OFF**.
 | Presentation | tends to be linear steps | tends to be always visible | service-dependent | **only while ON · explore any spot** |
 | Normal UI | depends on implementation | tends to get cluttered | depends on implementation | **left entirely unchanged** |
 | Adoption | usually needs integration | add CSS/JS | snippet + external platform + contract | **drop-in · no existing-code changes** |
-| Cost / ops | depends on implementation | local | monthly fee + tracking ops | **zero running cost · one dependency** |
+| Cost / ops | depends on implementation | local | monthly fee + tracking ops | **zero running cost · zero dependencies** |
 
 > Note: HelpLayer is **not a full replacement for a DAP**. Advanced features like analytics, segmented
 > delivery, complex flow guidance, and onboarding automation are out of scope — it commits to
 > **satisfying just the core "show explanations in-screen" function at minimal cost**. Conversely, if your
 > main goal is to drive strong funnels or measure usage, a DAP or a tour is the better fit.
+>
+> That said, several of these (analytics, deep-linking, a search palette, framework glue) are easy to
+> build *on top* of the public API in a few lines — see **[RECIPES.md](./RECIPES.md)** for recipes.
 
 ## When it fits (where adoption pays off)
 
 - **A DAP / guide SaaS isn't worth the cost and you're considering canceling — but canceling drops your
   in-screen help back to zero.**
-  → Keep just the core "show explanations in-screen" function in-house, with one dependency and zero
+  → Keep just the core "show explanations in-screen" function in-house, with zero dependencies and zero
   running cost. It gives you a place to land after switching away.
 - **You don't have the budget to contract a SaaS, but you want to expand your help.**
   → Drop it in with npm or a single `<script>`. No monthly fee, no account.
@@ -143,7 +151,7 @@ When loading from a CDN, we recommend **pinning the version** and adding **SRI (
 
 ```html
 <script
-  src="https://unpkg.com/help-layer@1.0.1/dist/help-layer.iife.js"
+  src="https://unpkg.com/help-layer@1.3.0/dist/help-layer.iife.js"
   integrity="sha384-……(replace with the published file's hash)"
   crossorigin="anonymous"></script>
 <script>
@@ -155,7 +163,7 @@ When loading from a CDN, we recommend **pinning the version** and adding **SRI (
 ```
 
 > Generate the `integrity` hash from the actually published file, e.g.:
-> `curl -s https://unpkg.com/help-layer@1.0.1/dist/help-layer.iife.js | openssl dgst -sha384 -binary | openssl base64 -A`
+> `curl -s https://unpkg.com/help-layer@1.3.0/dist/help-layer.iife.js | openssl dgst -sha384 -binary | openssl base64 -A`
 > (If you don't pin the version, the SRI will mismatch and the browser will refuse to load it.)
 
 ## Free placement (descriptions not bound to an element)
@@ -239,7 +247,7 @@ You can change the look just by overriding the following variables in your host
 
 | Variable | Default | Purpose |
 |------|------|------|
-| `--help-layer-marker-size` | `22px` | marker diameter |
+| `--help-layer-marker-size` | `24px` | marker diameter (default meets WCAG 2.5.8 minimum target size) |
 | `--help-layer-marker-bg` | `#2563eb` | marker background color |
 | `--help-layer-marker-color` | `#fff` | marker text color |
 | `--help-layer-popup-bg` | `#fff` | popup background color |
@@ -250,19 +258,107 @@ You can change the look just by overriding the following variables in your host
 | `--help-layer-overlay-bg` | `transparent` | blocking-layer (scrim) background; e.g. `rgba(0,0,0,0.15)` to signal the host is inactive |
 | `--help-layer-overlay-cursor` | `default` | cursor over the blocked area; e.g. `not-allowed` / `help` |
 
+## Browser & runtime support
+
+HelpLayer targets **modern evergreen browsers** (Chrome / Edge, Firefox, Safari) and the Chromium in
+recent Electron. **Internet Explorer 11 is not supported and cannot be** — the library relies on ES2020
+syntax, ES modules, Shadow DOM, and `clip-path`, none of which IE provides. Packaging
+changes can't bridge this; if you must support genuinely old runtimes, this library is not the right fit.
+
+What sets the minimum (the two newest APIs degrade gracefully, so the practical hard floor is roughly
+**2020-era evergreen**):
+
+| Feature | Used for | Minimum | Fallback |
+|---|---|---|---|
+| ES2020 + ES modules | the whole library | evergreen (~2020) | none — transpile/bundle for older targets |
+| `requestAnimationFrame` | marker/popup auto-positioning (per-frame tracking) | evergreen | none |
+| Open Shadow DOM piercing | finding targets inside shadow roots | evergreen | closed shadow roots are unsupported by design |
+| `clip-path: polygon()` | the blocking layer's toggle "hole" | evergreen (very old Safari needs `-webkit-`) | none |
+| `inert` | removing the host from the a11y tree | Chrome 102 / FF 112 / Safari 15.5 (2023) | degrades to visual + keyboard blocking only |
+| `Element.checkVisibility()` | hiding a marker when its target is hidden | Chrome 105 / FF 125 / Safari 17.4 (2024) | falls back to a 0×0-rect check (detects `display:none` only) |
+
+### Module formats
+
+- **ESM (default).** `import { initHelpLayer } from 'help-layer'` resolves to the prebuilt, tested
+  `dist/help-layer.esm.js` (self-contained — no runtime dependencies to resolve).
+- **No bundler / `<script>` / CDN / strict environments.** Use the self-contained IIFE build, which
+  exposes a global `HelpLayer` — see [Use it with just a `<script>`](#use-it-with-just-a-script-no-bundler).
+- **CommonJS (`require`).** No `require` entry is provided: this is a browser-only DOM library, so a Node
+  CJS context can't use it meaningfully. In non-ESM toolchains, consume the ESM build via your bundler,
+  or load the IIFE build above.
+
 ## Known limitations
 
 - Closed Shadow DOM is unreachable from JS, so it is unsupported (only open shadow roots are pierced).
-- The offset that overlaps the marker onto a corner assumes the default marker size (22px). Changing
+- The offset that overlaps the marker onto a corner assumes the default marker size (24px). Changing
   `--help-layer-marker-size` significantly may cause a slight drift.
+- **Target *state* changes are not watched** (only *layout* and *presence* are). While ON, a marker
+  follows its target's position/size changes and is added/removed as the target enters/leaves the DOM,
+  and it hides/reshows when the target itself is hidden/shown (e.g. `display:none`). However, changes
+  to a target's **attributes or content** are *not* detected: adding/removing the `data-help-id`
+  attribute on an existing element, rewriting `data-help-title` / `data-help-text`, or toggling state
+  like `disabled` won't update the markers. This is intentional — watching every attribute mutation
+  across the whole document (`MutationObserver` with `attributes: true, subtree: true`) fires on every
+  class/style change and is a performance footgun for a drop-in library. If you change such state,
+  rebuild via `update(config)`, toggle the mode OFF→ON, or re-insert the target element into the DOM
+  (re-insertion is picked up by the `childList` observation).
+
+## Performance (how many markers)
+
+The cost scales with the number of **markers visible at once**, not with the size of your `config`.
+All visible markers are positioned together in **one shared `requestAnimationFrame` loop** (no
+per-marker watchers, no positioning library), so while the page scrolls or animates each frame does a
+single batched read → compute → write pass over the visible markers.
+Markers only exist **while the mode is ON and only for targets currently present and shown** — a target
+hidden via `display:none` (or otherwise reported hidden by `checkVisibility`) has its marker excluded
+from positioning, layout measurement, and overlap avoidance. So what matters is "how many are on the
+page right now," not how many keys you registered.
+
+Marker-to-marker overlap avoidance is `O(n²)` per pass, but it's capped at a few iterations with a small
+constant and runs only when something actually moved; each pass reads every visible reference rect just
+once (reads and writes are phase-separated, so there's no per-marker layout thrashing). What you'd feel
+first at scale is the per-frame tracking, which grows linearly with the number of visible markers.
+
+Rough guidance (markers shown **at the same time**):
+
+- **Up to a few hundred** — comfortable on typical hardware.
+- **~1000** — still smooth in our measurements (a locked 60fps under continuous auto-scroll on the
+  bundled stress page).
+- **Well beyond that** — the per-frame tracking during scroll/animation eventually shows.
+
+Even so, the mode is **exploratory** — users pick the spot they want, so a screen rarely needs more than
+a few dozen markers. On large pages, scope your targets, or split them per page/tab (e.g. swap sets with
+`update(config)`, or use a different `attribute`) to keep the number shown at once down. This mirrors the
+deliberate choice in [Known limitations](#known-limitations) not to watch every attribute mutation across
+the document — both avoid per-frame work that doesn't pay for itself.
+
+## Accessibility
+
+While the mode is ON, the host app is blocked not only visually and for pointer/keyboard input, but
+also **semantically for assistive technology**: the host is removed from the accessibility tree with
+the [`inert`](https://developer.mozilla.org/docs/Web/HTML/Global_attributes/inert) attribute, so a
+screen reader's virtual cursor (browse mode) can't read or activate background content. Only the help
+markers, the popup, and your toggle stay reachable. The popup is a `role="dialog"` with
+`aria-modal="true"`, and focus moves into it on open and returns to the marker on close.
+
+Bounded limitations of this isolation:
+
+- `inert` can't be cancelled on a descendant of an inert subtree, so isolation is applied at the
+  document-body top level (like the clip-path "hole" that lets the toggle show through). The toggle
+  must stay operable, so **the top-level branch containing your toggle is left reachable** — keep the
+  toggle at/near the body level to minimize what leaks (none if it's a direct `<body>` child).
+- `inert` is broadly supported in current browsers; on engines without it, the visual/keyboard
+  blocking still applies, but AT exclusion degrades gracefully (no error).
 
 ## Security
 
+To report a vulnerability and for the support / security-release policy, see [SECURITY.md](./SECURITY.md). Please use GitHub's private vulnerability reporting rather than a public issue.
+
 - By design, `title` / `text` are rendered with `textContent` only; `innerHTML` / `eval` / `new Function` are **never used**.
 - There is **no external communication** (`fetch`, etc.) and **no storage use** (`localStorage` / `cookie`) — it runs fully locally.
 - The only path through which untrusted data is inserted into the DOM as HTML / DOM nodes is the `render` option. Its return value is not sanitized, so
   neutralize it on the caller side if it contains user input (see "Line breaks & links in the body" above).
-- The only runtime dependency is `@floating-ui/dom`. When using a CDN, pin the version and add SRI as noted above.
+- The library has no runtime dependencies. When using a CDN, pin the version and add SRI as noted above.
 
 ### Content Security Policy (CSP)
 

package/dist/help-layer.esm.js

@@ -1,7 +1,7 @@
-var F="help-layer-popup-title";function z(){let e=document.createElement("div");return e.className="help-layer-blocking-layer",e}function B(e,t="?"){let o=document.createElement("button");return o.type="button",o.className="help-layer-marker",o.textContent=t,o.setAttribute("aria-label",`Help: ${e}`),o}function H(){let e=document.createElement("div");e.className="help-layer-popup",e.setAttribute("role","dialog"),e.setAttribute("aria-labelledby",F),e.tabIndex=-1;let t=document.createElement("div");t.className="help-layer-popup__title",t.id=F;let o=document.createElement("div");o.className="help-layer-popup__text";let r=document.createElement("button");return r.type="button",r.className="help-layer-popup__close",r.textContent="\xD7",r.setAttribute("aria-label","Close"),e.append(t,o,r),{root:e,titleEl:t,textEl:o,closeEl:r}}import{autoUpdate as O,computePosition as q,flip as be,offset as Z,shift as ve}from"@floating-ui/dom";function K(e,t){let o=e.width||0,r=e.height||0,n=e.left-t.x,i=e.top-t.y;return{x:n,y:i,left:n,top:i,right:n+o,bottom:i+r,width:o,height:r}}function G(e){return{contextElement:document.body,getBoundingClientRect(){return K(e(),{x:window.scrollX,y:window.scrollY})}}}function V(e,t,o){e.style.left=`${t}px`,e.style.top=`${o}px`}function U(e){if(!(e instanceof Element))return!1;let t=e;for(;t;){if(getComputedStyle(t).position==="fixed")return!0;let o=t.parentElement;if(o)t=o;else{let r=t.getRootNode();t=r instanceof ShadowRoot?r.host:null}}return!1}var R=11;function ke(e){let t=e.endsWith("-start");return{mainAxis:-R,crossAxis:t?R:-R}}function W(e,t,o,r="top-end"){let n=U(e)?"fixed":"absolute";return n==="fixed"&&t.style.setProperty("position","fixed","important"),O(e,t,()=>{q(e,t,{placement:r,strategy:n,middleware:[Z(ke(r))]}).then(({x:p,y:d})=>{V(t,p,d),o&&o()}).catch(()=>{})},{animationFrame:!0})}function Y(e,t,o="bottom-start"){let r=U(e)?"fixed":"absolute";t.style.setProperty("position",r,"important");let n=()=>{q(e,t,{placement:o,strategy:r,middleware:[Z(8),be({padding:8}),ve({padding:8})]}).then(({x:p,y:d})=>{V(t,p,d)}).catch(()=>{})},i=O(e,t,n,{animationFrame:!0});return{update:n,cleanup:i}}function X(e,t,o){return O(e,t,o)}function we(e){let t=e.left,o=e.top,r=e.right,n=e.bottom;return`polygon(
+function W(e,{toggleEl:t,isLibraryNode:o}){let r=new Set;function n(i){if(i.nodeType!==1)return;let a=i;o(a)||t&&(a===t||a.contains(t))||a.hasAttribute("inert")||(a.toggleAttribute("inert",!0),r.add(a))}for(let i of[...document.body.children])n(i);let l=new MutationObserver(i=>{for(let a of i)a.addedNodes.forEach(n)});l.observe(document.body,{childList:!0}),e.track(()=>{l.disconnect(),r.forEach(i=>i.removeAttribute("inert")),r.clear()})}var we=0;function G(){let e=document.createElement("div");return e.className="help-layer-blocking-layer",e}function U(e,t="?"){let o=document.createElement("button");return o.type="button",o.className="help-layer-marker",o.textContent=t,o.setAttribute("aria-label",`Help: ${e}`),o}function Y(){let e=we++,t=`help-layer-popup-title-${e}`,o=`help-layer-popup-text-${e}`,r=document.createElement("div");r.className="help-layer-popup",r.setAttribute("role","dialog"),r.setAttribute("aria-modal","true"),r.setAttribute("aria-labelledby",t),r.setAttribute("aria-describedby",o),r.tabIndex=-1;let n=document.createElement("div");n.className="help-layer-popup__title",n.id=t;let l=document.createElement("div");l.className="help-layer-popup__text",l.id=o;let i=document.createElement("button");return i.type="button",i.className="help-layer-popup__close",i.textContent="\xD7",i.setAttribute("aria-label","Close"),r.append(n,l,i),{root:r,titleEl:n,textEl:l,closeEl:i}}function J(e,t){let o=e.width||0,r=e.height||0,n=e.left-t.x,l=e.top-t.y;return{x:n,y:l,left:n,top:l,right:n+o,bottom:l+r,width:o,height:r}}var _=12;function Q(e,t,o="top-end"){let[r,n]=o.split("-"),i=n==="start"?_:-_,a,c;return r==="top"||r==="bottom"?(c=r==="top"?e.top-t+_:e.top+e.height-_,n==="start"?a=e.left:n==="end"?a=e.left+e.width-t:a=e.left+e.width/2-t/2,a+=i):(a=r==="left"?e.left-t+_:e.left+e.width-_,n==="start"?c=e.top:n==="end"?c=e.top+e.height-t:c=e.top+e.height/2-t/2,c+=i),{left:a,top:c}}function D(e,t,o,r,n){return{left:e-o.left-r,top:t-o.top-n}}var X=(e,t,o)=>Math.min(Math.max(e,t),Math.max(t,o));function ee(e,t,o,r={}){let n=r.placement??"bottom-start",l=r.offset??8,i=r.padding??8,[a,c]=n.split("-"),m=a==="top"||a==="bottom",h=s=>s==="bottom"?e.top+e.height+l:s==="top"?e.top-t.height-l:s==="right"?e.left+e.width+l:e.left-t.width-l,u=s=>s==="bottom"?o.height-i-(e.top+e.height+l):s==="top"?e.top-l-i:s==="right"?o.width-i-(e.left+e.width+l):e.left-l-i,v={top:"bottom",bottom:"top",left:"right",right:"left"}[a],w=m?t.height:t.width,E=u(a)>=w||u(a)>=u(v)?a:v,b=(s,g,y)=>c==="start"?y:c==="end"?y+s-g:y+s/2-g/2,f,p;return m?(p=h(E),f=b(e.width,t.width,e.left),f=X(f,i,o.width-t.width-i)):(f=h(E),p=b(e.height,t.height,e.top),p=X(p,i,o.height-t.height-i)),{left:f,top:p,placement:c?`${E}-${c}`:E}}function H(e){return{contextElement:document.body,getBoundingClientRect(){return J(e(),{x:window.scrollX,y:window.scrollY})}}}function I(e){if(!(e instanceof Element))return!1;let t=e;for(;t;){if(getComputedStyle(t).position==="fixed")return!0;let o=t.parentElement;if(o)t=o;else{let r=t.getRootNode();t=r instanceof ShadowRoot?r.host:null}}return!1}function j(e){if(!(e instanceof Element))return!1;if(typeof e.checkVisibility=="function")return!e.checkVisibility({visibilityProperty:!0,contentVisibilityAuto:!0});let t=e.getBoundingClientRect();return t.width===0&&t.height===0}function te(e,t,o){e.style.left=`${t}px`,e.style.top=`${o}px`}function Ee(e,t){return e.top===t.top&&e.left===t.left&&e.width===t.width&&e.height===t.height}function oe(e,t){t();let o=e.getBoundingClientRect(),r=!1,n=requestAnimationFrame(function i(){if(r)return;let a=e.getBoundingClientRect();Ee(a,o)||t(),o=a,n=requestAnimationFrame(i)}),l=()=>t();return window.addEventListener("resize",l),()=>{r=!0,cancelAnimationFrame(n),window.removeEventListener("resize",l)}}function ne(e,t,o="bottom-start"){let r=I(e)?"fixed":"absolute";t.style.setProperty("position",r,"important");let n=()=>{let i=e.getBoundingClientRect(),a={width:t.offsetWidth,height:t.offsetHeight},c={width:window.innerWidth,height:window.innerHeight},{left:m,top:h}=ee(i,a,c,{placement:o});if(r==="fixed")te(t,m,h);else{let u=document.body,v=D(m,h,u.getBoundingClientRect(),u.clientLeft,u.clientTop);te(t,v.left,v.top)}},l=oe(e,n);return{update:n,cleanup:l}}function re(e,t,o){return oe(e,o)}function Le(e){let t=e.left,o=e.top,r=e.right,n=e.bottom;return`polygon(
     0px 0px, 100% 0px, 100% 100%, 0px 100%, 0px 0px,
     ${t}px ${o}px, ${t}px ${n}px, ${r}px ${n}px, ${r}px ${o}px, ${t}px ${o}px
-  )`}function J(e,{toggleEl:t,onBackgroundClick:o,isLibraryElement:r,onEscape:n}){let i=z();if(document.body.appendChild(i),e.track(()=>i.remove()),t){let b=X(t,i,()=>{i.style.clipPath=we(t.getBoundingClientRect())});e.track(b)}o&&(i.addEventListener("click",o),e.track(()=>i.removeEventListener("click",o)));let p=document.activeElement;p instanceof HTMLElement&&p!==document.body&&p!==t&&p.blur();let d=u=>{r(u.target)||(u.stopPropagation(),t?t.focus({preventScroll:!0}):u.target instanceof HTMLElement&&u.target.blur())};document.addEventListener("focusin",d,!0),e.track(()=>document.removeEventListener("focusin",d,!0));let f=u=>{r(u.target)||(u.stopPropagation(),u.preventDefault())},y=u=>{if(u.key==="Escape"){u.stopPropagation(),u.preventDefault();return}f(u)},h=u=>{if(u.key==="Escape"){u.stopPropagation(),u.preventDefault(),n&&n();return}f(u)};return document.addEventListener("keydown",h,!0),document.addEventListener("keyup",y,!0),document.addEventListener("keypress",y,!0),e.track(()=>{document.removeEventListener("keydown",h,!0),document.removeEventListener("keyup",y,!0),document.removeEventListener("keypress",y,!0)}),i}function P(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}function Q(e){return P(e)&&Number.isFinite(e.top)&&Number.isFinite(e.left)}function M(e){if(!P(e))throw new Error("helpConfig must be a plain object");for(let[t,o]of Object.entries(e)){if(!P(o))throw new Error(`helpConfig["${t}"] must be an object`);if(typeof o.title!="string"||o.title==="")throw new Error(`helpConfig["${t}"].title must be a non-empty string`);if(typeof o.text!="string"||o.text==="")throw new Error(`helpConfig["${t}"].text must be a non-empty string`);if(o.position!==void 0&&!Q(o.position))throw new Error(`helpConfig["${t}"].position must be { top: finite number, left: finite number }`)}}function ee(e){return Object.entries(e).map(([t,o])=>Q(o.position)?{key:t,title:o.title,text:o.text,kind:"free",target:null,position:{top:o.position.top,left:o.position.left}}:{key:t,title:o.title,text:o.text,kind:"element",target:null,position:null})}function te(e,t={}){let o=t.minDistance??26,r=t.iterations??6,n=e.map(i=>({x:i.x,y:i.y}));for(let i=0;i<r;i++){let p=!1;for(let d=0;d<n.length;d++)for(let f=d+1;f<n.length;f++){let y=n[d],h=n[f],u=h.x-y.x,b=h.y-y.y,l=Math.hypot(u,b);if(l>=o)continue;l===0&&(u=1,b=0,l=1);let c=(o-l)/2,m=u/l,a=b/l;y.x-=m*c,y.y-=a*c,h.x+=m*c,h.y+=a*c,p=!0}if(!p)break}return n.map((i,p)=>({dx:i.x-e[p].x,dy:i.y-e[p].y}))}var oe="help-layer-target-highlight";function Ee(e){return e.kind==="free"?G(()=>({top:e.position.top,left:e.position.left,width:0,height:0})):e.target}function ne(e,{onMarkerClick:t,onOverlapResolved:o,markerLabel:r="?",markerPlacement:n="top-end"}){let i=new Map,p=null,d=!1;function f(){p=null;let l=[...i.values()];if(l.length<=1){let a=l.length===1?l[0].el:null;a&&a.style.transform&&(a.style.transform="",o&&o());return}l.forEach(a=>{a.el.style.transform=""});let c=l.map(a=>{let s=a.el.getBoundingClientRect();return{x:s.left+s.width/2,y:s.top+s.height/2}}),m=te(c);l.forEach((a,s)=>{let{dx:x,dy:v}=m[s];a.el.style.transform=x||v?`translate(${x}px, ${v}px)`:""}),o&&o()}function y(){p!==null||d||(p=requestAnimationFrame(f))}function h(l){if(i.has(l.id))return;let c=B(l.title,r);document.body.appendChild(c);let m=()=>t(l,c);c.addEventListener("click",m);let a=W(Ee(l),c,y,n),s=l.kind==="element"?l.target:null,x=()=>s&&s.classList.add(oe),v=()=>s&&s.classList.remove(oe);s&&(c.addEventListener("mouseenter",x),c.addEventListener("mouseleave",v),c.addEventListener("focus",x),c.addEventListener("blur",v));let C=!1,L=()=>{C||(C=!0,a(),c.removeEventListener("click",m),s&&(c.removeEventListener("mouseenter",x),c.removeEventListener("mouseleave",v),c.removeEventListener("focus",x),c.removeEventListener("blur",v),v()),c.remove(),i.delete(l.id),y())};i.set(l.id,{record:l,el:c,cleanup:L})}function u(l){let c=i.get(l);c&&c.cleanup()}function b(l){l.forEach(h)}return e.track(()=>{d=!0,p!==null&&(cancelAnimationFrame(p),p=null),[...i.values()].forEach(l=>l.cleanup())}),{mount:h,unmount:u,mountAll:b,has(l){return i.has(l)},findByKey(l){for(let c of i.values())if(c.record.key===l)return c;return null}}}function k(e,t,...o){if(t)try{return t(...o)}catch(r){console.error(`[help-layer] ${e} threw:`,r);return}}var Ce=1;function S(e,t,o,r){typeof e.querySelectorAll=="function"&&e.querySelectorAll("*").forEach(n=>{o&&n.matches(t)&&o(n),n.shadowRoot&&(r&&r(n.shadowRoot),S(n.shadowRoot,t,o,r))})}function ie(e,t){let o=[];return S(e,t,r=>o.push(r)),o}function Le(e){let t=[];return S(e,"*",null,o=>t.push(o)),t}function re(e,t){let o=[],r=[];if(e.nodeType!==Ce)return{matches:o,shadowRoots:r};let n=e;return typeof n.matches=="function"&&n.matches(t)&&o.push(n),n.shadowRoot&&(r.push(n.shadowRoot),S(n.shadowRoot,t,i=>o.push(i),i=>r.push(i))),S(n,t,i=>o.push(i),i=>r.push(i)),{matches:o,shadowRoots:r}}function ae({root:e=document,selector:t,onAdded:o,onRemoved:r}){let n=new Set,i=f=>{for(let y of f)y.addedNodes.forEach(h=>{let{matches:u,shadowRoots:b}=re(h,t);u.forEach(l=>k("observer onAdded",o,l)),b.forEach(d)}),y.removedNodes.forEach(h=>{re(h,t).matches.forEach(u=>k("observer onRemoved",r,u))})},p=new MutationObserver(i);function d(f){n.has(f)||(n.add(f),p.observe(f,{childList:!0,subtree:!0}))}return d(e),Le(e).forEach(d),{disconnect(){p.disconnect(),n.clear()}}}var T="data-help-title",I="data-help-text";function N(e="data-help-id"){return`[${e}], [${T}]`}function D(e){let t=new Map;for(let o of e)o.kind==="element"&&t.set(o.key,o);return t}function le(e){return e.filter(t=>t.kind==="free").map(t=>({id:t.key,kind:"free",key:t.key,title:t.title,text:t.text,position:t.position}))}function j(e,t,o="data-help-id"){let r=e.getAttribute(o),n=r!=null?t.get(r):void 0,i=n?n.title:e.getAttribute(T),p=n?n.text:e.getAttribute(I);return!i||!p?null:{id:e,kind:"element",key:r,title:i,text:p,target:e}}function se(e,t=document,{silent:o=!1,attribute:r="data-help-id"}={}){let n=D(e),i=[];return ie(t,N(r)).forEach(p=>{let d=j(p,n,r);if(!d){if(!o){let f=p.getAttribute(r);console.warn(f!=null?`[help-layer] element with ${r}="${f}" has no matching helpConfig entry or inline ${T}/${I}`:`[help-layer] element needs both ${T} and ${I} (or a ${r} matching helpConfig)`)}return}i.push(d)}),i}function pe(e,{onClose:t,render:o,popupPlacement:r="bottom-start"}={}){let{root:n,titleEl:i,textEl:p,closeEl:d}=H();n.style.setProperty("display","none","important"),document.body.appendChild(n),d.addEventListener("click",()=>m());let f=null,y=null,h=null;function u(){h&&(h.cleanup(),h=null)}function b(a,s){i.textContent=a.title;let x=k("render",o,a);p.textContent="",x?p.appendChild(x):p.textContent=a.text,n.style.setProperty("display","block","important"),f=a.id,y=s,u(),h=Y(s,n,r),n.focus({preventScroll:!0})}function l(){h&&h.update()}function c(){let a=f!==null;u(),f=null,y=null,n.style.setProperty("display","none","important"),a&&k("onClose",t)}function m(a){let s=a??y;c(),s&&s.isConnected&&typeof s.focus=="function"&&s.focus({preventScroll:!0})}return e.track(()=>{c(),n.remove()}),{root:n,isOpen(a){return f===a},getOpenId(){return f},open:b,close:m,reposition:l}}function ce(){let e=[];return{track(t){e.push(t)},teardownAll(){for(;e.length>0;){let t=e.pop();try{t()}catch(o){console.error("[help-layer] teardown step threw:",o)}}}}}var Ae="data-help-layer-style",Pe=`
+  )`}function ie(e,{toggleEl:t,onBackgroundClick:o,isLibraryElement:r,onEscape:n}){let l=G();if(document.body.appendChild(l),e.track(()=>l.remove()),t){let v=re(t,l,()=>{l.style.clipPath=Le(t.getBoundingClientRect())});e.track(v)}o&&(l.addEventListener("click",o),e.track(()=>l.removeEventListener("click",o)));let i=document.activeElement;i instanceof HTMLElement&&i!==document.body&&i!==t&&i.blur();let a=u=>{r(u.target)||(u.stopPropagation(),t?t.focus({preventScroll:!0}):u.target instanceof HTMLElement&&u.target.blur())};document.addEventListener("focusin",a,!0),e.track(()=>document.removeEventListener("focusin",a,!0));let c=u=>{r(u.target)||(u.stopPropagation(),u.preventDefault())},m=u=>{if(u.key==="Escape"){u.stopPropagation(),u.preventDefault();return}c(u)},h=u=>{if(u.key==="Escape"){u.stopPropagation(),u.preventDefault(),n&&n();return}c(u)};return document.addEventListener("keydown",h,!0),document.addEventListener("keyup",m,!0),document.addEventListener("keypress",m,!0),e.track(()=>{document.removeEventListener("keydown",h,!0),document.removeEventListener("keyup",m,!0),document.removeEventListener("keypress",m,!0)}),l}function N(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}function le(e){return N(e)&&Number.isFinite(e.top)&&Number.isFinite(e.left)}function q(e){if(!N(e))throw new Error("helpConfig must be a plain object");for(let[t,o]of Object.entries(e)){if(!N(o))throw new Error(`helpConfig["${t}"] must be an object`);if(typeof o.title!="string"||o.title==="")throw new Error(`helpConfig["${t}"].title must be a non-empty string`);if(typeof o.text!="string"||o.text==="")throw new Error(`helpConfig["${t}"].text must be a non-empty string`);if(o.position!==void 0&&!le(o.position))throw new Error(`helpConfig["${t}"].position must be { top: finite number, left: finite number }`)}}function se(e){return Object.entries(e).map(([t,o])=>le(o.position)?{key:t,title:o.title,text:o.text,kind:"free",target:null,position:{top:o.position.top,left:o.position.left}}:{key:t,title:o.title,text:o.text,kind:"element",target:null,position:null})}function ae(e,t={}){let o=t.minDistance??26,r=t.iterations??6,n=e.map(l=>({x:l.x,y:l.y}));for(let l=0;l<r;l++){let i=!1;for(let a=0;a<n.length;a++)for(let c=a+1;c<n.length;c++){let m=n[a],h=n[c],u=h.x-m.x,v=h.y-m.y,w=Math.hypot(u,v);if(w>=o)continue;w===0&&(u=1,v=0,w=1);let E=(o-w)/2,b=u/w,f=v/w;m.x-=b*E,m.y-=f*E,h.x+=b*E,h.y+=f*E,i=!0}if(!i)break}return n.map((l,i)=>({dx:l.x-e[i].x,dy:l.y-e[i].y}))}var pe="help-layer-target-highlight",Ce=24;function Ae(e){return e.kind==="free"?H(()=>({top:e.position.top,left:e.position.left,width:0,height:0})):e.target}function ce(e,{onMarkerClick:t,onOverlapResolved:o,onMarkerHidden:r,markerLabel:n="?",markerPlacement:l="top-end"}){let i=new Map,a=null,c=!1,m=0,h=-1;function u(){if(c||i.size===0)return;let p=document.body.getBoundingClientRect(),s=document.body.clientLeft,g=document.body.clientTop,y=[];for(let d of i.values()){if(j(d.reference)){d.hidden||(d.hidden=!0,d.lastBaseEl=null,d.el.style.setProperty("display","none","important"),r&&r(d.record));continue}d.hidden&&(d.hidden=!1,d.el.style.removeProperty("display")),d.refRect=d.reference.getBoundingClientRect(),y.push(d)}if(!m&&y.length){let d=y[0].el.offsetWidth;d>0&&(m=d)}let T=m||Ce,L=y.length!==h;h=y.length;let A=[],$=[];for(let d of y){let P=Q(d.refRect,T,d.placement);$.push({x:P.left+T/2,y:P.top+T/2});let k=d.strategy==="fixed"?{left:P.left,top:P.top}:D(P.left,P.top,p,s,g);A.push(k),(!d.lastBaseEl||d.lastBaseEl.left!==k.left||d.lastBaseEl.top!==k.top)&&(L=!0),d.lastBaseEl=k}if(L&&y.length){let d=ae($),P=!1;for(let k=0;k<y.length;k++){let C=y[k],O=A[k].left+d[k].dx,M=A[k].top+d[k].dy;(C.lastLeft!==O||C.lastTop!==M)&&(C.el.style.left=`${O}px`,C.el.style.top=`${M}px`,C.lastLeft=O,C.lastTop=M,P=!0)}P&&o&&o()}}function v(){a=null,!(c||i.size===0)&&(u(),a=requestAnimationFrame(v))}function w(){a!==null||c||i.size===0||(a=requestAnimationFrame(v))}function E(p){if(i.has(p.id))return;let s=U(p.title,n);document.body.appendChild(s);let g=()=>t(p,s);s.addEventListener("click",g);let y=Ae(p),T=I(y)?"fixed":"absolute";T==="fixed"&&s.style.setProperty("position","fixed","important");let L=p.kind==="element"?p.target:null,A=()=>L&&L.classList.add(pe),$=()=>L&&L.classList.remove(pe);L&&(s.addEventListener("mouseenter",A),s.addEventListener("mouseleave",$),s.addEventListener("focus",A),s.addEventListener("blur",$));let d=!1,P=()=>{d||(d=!0,s.removeEventListener("click",g),L&&(s.removeEventListener("mouseenter",A),s.removeEventListener("mouseleave",$),s.removeEventListener("focus",A),s.removeEventListener("blur",$),$()),s.remove(),i.delete(p.id),w())};i.set(p.id,{record:p,el:s,reference:y,strategy:T,placement:l,cleanup:P,hidden:!1,lastBaseEl:null,lastLeft:void 0,lastTop:void 0}),w()}function b(p){let s=i.get(p);s&&s.cleanup()}function f(p){p.forEach(E),u()}return e.track(()=>{c=!0,a!==null&&(cancelAnimationFrame(a),a=null),[...i.values()].forEach(p=>p.cleanup())}),{mount:E,unmount:b,mountAll:f,has(p){return i.has(p)},findByKey(p){for(let s of i.values())if(s.record.key===p)return s;return null}}}function S(e,t,...o){if(t)try{return t(...o)}catch(r){console.error(`[help-layer] ${e} threw:`,r);return}}var Te=1;function F(e,t,o,r){typeof e.querySelectorAll=="function"&&e.querySelectorAll("*").forEach(n=>{o&&n.matches(t)&&o(n),n.shadowRoot&&(r&&r(n.shadowRoot),F(n.shadowRoot,t,o,r))})}function fe(e,t){let o=[];return F(e,t,r=>o.push(r)),o}function Pe(e){let t=[];return F(e,"*",null,o=>t.push(o)),t}function ue(e,t){let o=[],r=[];if(e.nodeType!==Te)return{matches:o,shadowRoots:r};let n=e;return typeof n.matches=="function"&&n.matches(t)&&o.push(n),n.shadowRoot&&(r.push(n.shadowRoot),F(n.shadowRoot,t,l=>o.push(l),l=>r.push(l))),F(n,t,l=>o.push(l),l=>r.push(l)),{matches:o,shadowRoots:r}}function de({root:e=document,selector:t,onAdded:o,onRemoved:r}){let n=new Set,l=c=>{for(let m of c)m.addedNodes.forEach(h=>{let{matches:u,shadowRoots:v}=ue(h,t);u.forEach(w=>S("observer onAdded",o,w)),v.forEach(a)}),m.removedNodes.forEach(h=>{ue(h,t).matches.forEach(u=>S("observer onRemoved",r,u))})},i=new MutationObserver(l);function a(c){n.has(c)||(n.add(c),i.observe(c,{childList:!0,subtree:!0}))}return a(e),Pe(e).forEach(a),{disconnect(){i.disconnect(),n.clear()}}}var R="data-help-title",K="data-help-text";function V(e="data-help-id"){return`[${e}], [${R}]`}function z(e){let t=new Map;for(let o of e)o.kind==="element"&&t.set(o.key,o);return t}function he(e){return e.filter(t=>t.kind==="free").map(t=>({id:t.key,kind:"free",key:t.key,title:t.title,text:t.text,position:t.position}))}function Z(e,t,o="data-help-id"){let r=e.getAttribute(o),n=r!=null?t.get(r):void 0,l=n?n.title:e.getAttribute(R),i=n?n.text:e.getAttribute(K);return!l||!i?null:{id:e,kind:"element",key:r,title:l,text:i,target:e}}function me(e,t=document,{silent:o=!1,attribute:r="data-help-id"}={}){let n=z(e),l=[];return fe(t,V(r)).forEach(i=>{let a=Z(i,n,r);if(!a){if(!o){let c=i.getAttribute(r);console.warn(c!=null?`[help-layer] element with ${r}="${c}" has no matching helpConfig entry or inline ${R}/${K}`:`[help-layer] element needs both ${R} and ${K} (or a ${r} matching helpConfig)`)}return}l.push(a)}),l}function ye(e,{onClose:t,render:o,popupPlacement:r="bottom-start"}={}){let{root:n,titleEl:l,textEl:i,closeEl:a}=Y();n.style.setProperty("display","none","important"),document.body.appendChild(n),a.addEventListener("click",()=>p());let c=null,m=null,h=null;function u(){h&&(h.cleanup(),h=null)}let v='a[href],button,input,select,textarea,[tabindex]:not([tabindex="-1"])';function w(s){if(s.key!=="Tab")return;let g=[...n.querySelectorAll(v)].filter(A=>A instanceof HTMLElement);if(s.preventDefault(),g.length===0){n.focus({preventScroll:!0});return}let y=g.length,T=g.indexOf(document.activeElement instanceof HTMLElement?document.activeElement:null);(T===-1?s.shiftKey?g[y-1]:g[0]:g[(T+(s.shiftKey?-1:1)+y)%y]).focus({preventScroll:!0})}function E(s,g){l.textContent=s.title;let y=S("render",o,s);i.textContent="",y?i.appendChild(y):i.textContent=s.text,n.style.setProperty("display","block","important"),c=s.id,m=g,u(),h=ne(g,n,r),n.addEventListener("keydown",w,!0),n.focus({preventScroll:!0})}function b(){h&&h.update()}function f(){let s=c!==null;u(),n.removeEventListener("keydown",w,!0),c=null,m=null,n.style.setProperty("display","none","important"),s&&S("onClose",t)}function p(s){let g=s??m;f(),g&&g.isConnected&&typeof g.focus=="function"&&g.focus({preventScroll:!0})}return e.track(()=>{f(),n.remove()}),{root:n,isOpen(s){return c===s},getOpenId(){return c},open:E,close:p,reposition:b}}function ge(){let e=[];return{track(t){e.push(t)},teardownAll(){for(;e.length>0;){let t=e.pop();try{t()}catch(o){console.error("[help-layer] teardown step threw:",o)}}}}}var Se="data-help-layer-style",$e=`
 .help-layer-blocking-layer {
   /* Structural properties !important so a host can't accidentally un-fix or restack the layer and
      defeat the blocking guarantee. */
@@ -36,15 +36,15 @@ var F="help-layer-popup-title";function z(){let e=document.createElement("div");
   pointer-events: auto !important;
   top: 0;
   left: 0;
-  width: var(--help-layer-marker-size, 22px) !important;
-  height: var(--help-layer-marker-size, 22px) !important;
+  width: var(--help-layer-marker-size, 24px) !important;
+  height: var(--help-layer-marker-size, 24px) !important;
   border-radius: 50%;
   background: var(--help-layer-marker-bg, #2563eb);
   color: var(--help-layer-marker-color, #fff);
   font-family: sans-serif;
   font-size: 13px;
   font-weight: bold;
-  line-height: var(--help-layer-marker-size, 22px);
+  line-height: var(--help-layer-marker-size, 24px);
   text-align: center;
   cursor: pointer;
   user-select: none;
@@ -115,8 +115,8 @@ var F="help-layer-popup-title";function z(){let e=document.createElement("div");
   pointer-events: auto !important;
   top: 6px;
   right: 6px;
-  width: 22px;
-  height: 22px;
+  width: 24px;
+  height: 24px;
   padding: 0;
   border: none;
   border-radius: 4px;
@@ -156,5 +156,5 @@ var F="help-layer-popup-title";function z(){let e=document.createElement("div");
     box-shadow: 0 4px 16px rgba(0, 0, 0, 0.55);
   }
 }
-`;function ue(e){let t=document.createElement("style");return t.setAttribute(Ae,""),e&&t.setAttribute("nonce",e),t.textContent=Pe,document.head.appendChild(t),t}function fe(e){e.remove()}function Se(e){if(typeof e=="string"){let t=document.querySelector(e);if(!t)throw new Error(`help-layer: toggle element not found for selector "${e}"`);return t}if(e instanceof HTMLElement)return e;throw new Error("help-layer: toggle must be a CSS selector string or a DOM element")}function de(e){if(!P(e))throw new Error("help-layer: initHelpLayer requires an options object");let{config:t,toggle:o,onEnable:r,onDisable:n,onOpen:i,onClose:p,silent:d=!1,attribute:f="data-help-id",render:y,markerLabel:h="?",markerPlacement:u="top-end",popupPlacement:b="bottom-start",nonce:l}=e,c=t;M(c);let m=o!=null?Se(o):null,a=null,s=null,x=null;function v(){if(a)return;a=ce(),m&&a.track(()=>{m.isConnected&&typeof m.focus=="function"&&m.focus({preventScroll:!0})});let E=ue(l);a.track(()=>fe(E));let w=ee(c),xe=D(w);s=pe(a,{onClose:p,render:y,popupPlacement:b}),x=ne(a,{markerLabel:h,markerPlacement:u,onMarkerClick:(g,A)=>{if(s.isOpen(g.id)){s.close();return}s.open(g,A),k("onOpen",i,g)},onOverlapResolved:()=>s.reposition()}),x.mountAll(le(w)),x.mountAll(se(w,document,{silent:d,attribute:f}));let ge=ae({selector:N(f),onAdded:g=>{let A=j(g,xe,f);A&&!x.has(A.id)&&x.mount(A)},onRemoved:g=>{s.isOpen(g)&&s.close(m??void 0),x.unmount(g)}});a.track(()=>ge.disconnect()),J(a,{toggleEl:m,onBackgroundClick:()=>s.close(),isLibraryElement:g=>!!g&&((m?m.contains(g):!1)||s.root.contains(g)||typeof g.closest=="function"&&!!g.closest(".help-layer-marker")),onEscape:()=>{s.getOpenId()!==null?s.close():$()}})}function C(){a&&(a.teardownAll(),a=null,s=null,x=null)}function L(){a||(v(),k("onEnable",r))}function $(){a&&(C(),k("onDisable",n))}function _(){a?$():L()}function he(E){if(a||L(),!x||!s)return;let w=x.findByKey(E);if(!w){d||console.warn(`[help-layer] open(): no help marker for key "${E}"`);return}s.open(w.record,w.el),k("onOpen",i,w.record)}function me(){s&&s.close()}function ye(E){M(E),c=E,a&&(C(),v())}return m&&m.addEventListener("click",_),{enable:L,disable:$,toggle:_,isActive(){return a!==null},open:he,close:me,update:ye,destroy(){$(),m&&m.removeEventListener("click",_)}}}function ft(e){return de(e)}export{ft as initHelpLayer};
+`;function be(e){let t=document.createElement("style");return t.setAttribute(Se,""),e&&t.setAttribute("nonce",e),t.textContent=$e,document.head.appendChild(t),t}function xe(e){e.remove()}function _e(e){if(typeof e=="string"){let t=document.querySelector(e);if(!t)throw new Error(`help-layer: toggle element not found for selector "${e}"`);return t}if(e instanceof HTMLElement)return e;throw new Error("help-layer: toggle must be a CSS selector string or a DOM element")}function ve(e){if(!N(e))throw new Error("help-layer: initHelpLayer requires an options object");let{config:t,toggle:o,onEnable:r,onDisable:n,onOpen:l,onClose:i,silent:a=!1,attribute:c="data-help-id",render:m,markerLabel:h="?",markerPlacement:u="top-end",popupPlacement:v="bottom-start",nonce:w}=e,E=t;q(E);let b=o!=null?_e(o):null,f=null,p=null,s=null;function g(){if(f)return;f=ge(),b&&f.track(()=>{b.isConnected&&typeof b.focus=="function"&&b.focus({preventScroll:!0})});let k=be(w);f.track(()=>xe(k));let C=se(E),O=z(C);p=ye(f,{onClose:i,render:m,popupPlacement:v}),s=ce(f,{markerLabel:h,markerPlacement:u,onMarkerClick:(x,B)=>{if(p.isOpen(x.id)){p.close();return}p.open(x,B),S("onOpen",l,x)},onOverlapResolved:()=>p.reposition(),onMarkerHidden:x=>{p.isOpen(x.id)&&p.close(b??void 0)}}),s.mountAll(he(C)),s.mountAll(me(C,document,{silent:a,attribute:c}));let M=de({selector:V(c),onAdded:x=>{let B=Z(x,O,c);B&&!s.has(B.id)&&s.mount(B)},onRemoved:x=>{p.isOpen(x)&&p.close(b??void 0),s.unmount(x)}});f.track(()=>M.disconnect());let ke=ie(f,{toggleEl:b,onBackgroundClick:()=>p.close(),isLibraryElement:x=>!!x&&((b?b.contains(x):!1)||p.root.contains(x)||typeof x.closest=="function"&&!!x.closest(".help-layer-marker")),onEscape:()=>{p.getOpenId()!==null?p.close():L()}});W(f,{toggleEl:b,isLibraryNode:x=>x===ke||x===p.root||!!x.classList&&x.classList.contains("help-layer-marker")})}function y(){f&&(f.teardownAll(),f=null,p=null,s=null)}function T(){f||(g(),S("onEnable",r))}function L(){f&&(y(),S("onDisable",n))}function A(){f?L():T()}function $(k){if(f||T(),!s||!p)return;let C=s.findByKey(k);if(!C){a||console.warn(`[help-layer] open(): no help marker for key "${k}"`);return}p.open(C.record,C.el),S("onOpen",l,C.record)}function d(){p&&p.close()}function P(k){q(k),E=k,f&&(y(),g())}return b&&b.addEventListener("click",A),{enable:T,disable:L,toggle:A,isActive(){return f!==null},open:$,close:d,update:P,destroy(){L(),b&&b.removeEventListener("click",A)}}}function kt(e){return ve(e)}export{kt as initHelpLayer};
 //# sourceMappingURL=help-layer.esm.js.map