@wcstack/intersection 1.12.0

package/README.ja.md

@@ -0,0 +1,193 @@
+# @wcstack/intersection
+
+`@wcstack/intersection` は wcstack エコシステム向けのヘッドレスな IntersectionObserver コンポーネントです。
+
+これは視覚的な UI ウィジェットではありません。
+`@wcstack/fetch` がネットワークリクエストをリアクティブな状態に変え、`@wcstack/geolocation` がデバイスの位置情報をリアクティブな状態に変えるのと同じように、**要素の*可視性*をリアクティブな状態に変える非同期プリミティブノード**です。
+
+`@wcstack/state` と組み合わせると、`<wcs-intersect>` はパス契約を通じて直接バインドできます。
+
+- **入力 / コマンド面**: `target`, `root`, `root-margin`, `threshold`, `once`, `manual`, `trigger`
+- **出力状態面**: `entry`, `intersecting`, `ratio`, `visible`, `observing`
+
+つまり、可視性を意識した処理 — 遅延読み込み、無限スクロール、スクロールスパイ — を HTML 上で宣言的に表現でき、UI 層に `new IntersectionObserver()` / `observe()` / `disconnect()`、後始末のグルーコードを書く必要がありません。
+
+`@wcstack/intersection` は [CSBC](https://github.com/csbc-dev/arch/blob/main/README.md)（Core / Shell / Binding Contract）アーキテクチャに従います。
+
+- **Core**（`IntersectionCore`）が observer、entry の正規化、`visible` ラッチ、観測のライフサイクルを所有
+- **Shell**（`<wcs-intersect>`）が*何を*観測するかを DOM から解決し、display・ライフサイクル・宣言的コマンドを管理
+- **Binding Contract**（`static wcBindable`）が観測可能な `properties`・書き込み可能な `inputs`・呼び出し可能な `commands` を宣言
+
+## なぜ存在するのか
+
+IntersectionObserver は他のすべての @wcstack センサと異なります。観測対象がヘッドレスなリソースではなく、**DOM 要素**だからです。命令的に配線するには、observer を作成し、ターゲットノードを解決し、entry コールバックを処理し、切断時にすべてを解体する必要があります。
+
+`@wcstack/intersection` はそのロジックを再利用可能なコンポーネントに押し込み、結果をバインド可能な状態として公開します。要素がビューにスクロールインすることが命令的なコールバック配線ではなく、**状態遷移**になります。これは読み取り専用のプロデューサです。element/layout は state のために値を生み出すだけで（`element/layout → state`）、逆向きの経路はありません。
+
+## `target` 属性がすべてを決める
+
+`target` は*何を*観測するかを選ぶ唯一のツマミであり、それに伴って `<wcs-intersect>` がどうレンダリングされるかも決めます。明示的に要求しない限り、layout box を決して注入しません。
+
+| `target`          | 観測対象              | `display`   | ユースケース         |
+|-------------------|-----------------------|-------------|----------------------|
+| *省略*            | 最初の要素の子        | `contents`  | 遅延読み込みラッパー |
+| `"#hero"` / sel.  | マッチした要素        | `none`      | スクロールスパイ（単一） |
+| `"self"`          | 要素自身              | `block`     | 無限スクロールの端   |
+
+`display:contents` は、子をラップしても自身の box を注入しないことを意味します — そのため `<wcs-intersect><img></wcs-intersect>` は flex/grid の親を乱しません。明示的な `target="self"` センチネルだけが box を取ります。
+
+> **最初の要素の子。** `target` が省略されると、*最初の要素の子*が観測されます。ターゲットは毎回の `observe()`（接続時と各 observed-attribute 変更時に実行）で再解決されるため、接続後に最初の子を追加・削除すると、次回の再観測で観測要素が切り替わります。解決時点で要素の子が無い場合は、自身を観測することにフォールバックします（`display:block`）。複数のターゲットを同時に観測することは意図的に対象外です — 各ターゲットをそれぞれ独自の `<wcs-intersect>` でラップしてください。
+
+## インストール
+
+```bash
+npm install @wcstack/intersection
+```
+
+## クイックスタート
+
+### 1. 画像を遅延読み込み（`visible` ラッチ）
+
+`visible` はターゲットが初めて交差したときに `true` に切り替わり、その後 `true` の**ままになります**。画像の `src` をこれにバインドすると、画像はビューにスクロールインしたときに一度だけ読み込まれます。
+
+```html
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+<script type="module" src="https://esm.run/@wcstack/intersection/auto"></script>
+
+<wcs-state>
+  <script type="module">
+    export default {
+      shown: false,
+      get src() {
+        return this.shown ? "/photo.jpg" : "";
+      }
+    };
+  </script>
+</wcs-state>
+
+<wcs-intersect once data-wcs="visible: shown">
+  <img data-wcs="src: src" alt="lazy">
+</wcs-intersect>
+```
+
+`once` は最初の交差後に observer を切断します — 一度きりの遅延読み込みに最適です。
+
+### 2. 無限スクロール（センチネル）
+
+リストの末尾に空の `target="self"` マーカーを置き、`intersecting` を「さらに読み込む」をトリガする state フラグにバインドします。
+
+```html
+<ul data-wcs="for: items">
+  <li data-wcs="textContent: items.*.name"></li>
+</ul>
+
+<wcs-intersect target="self" data-wcs="intersecting: atEnd"></wcs-intersect>
+```
+
+```js
+export default {
+  items: [],
+  atEnd: false,
+  get _loadMore() {
+    // atEnd が true になることに反応する computed/effect
+    return this.atEnd ? fetchNextPage() : null;
+  }
+};
+```
+
+### 3. スクロールスパイ（単一セクション）
+
+ドキュメント内の別の場所にあるセクションに `target` を向け、`intersecting` をバインドして対応するナビ項目をハイライトします。
+
+```html
+<nav>
+  <a href="#features" data-wcs="class.active: featuresVisible">Features</a>
+</nav>
+
+<section id="features">…</section>
+
+<wcs-intersect target="#features" threshold="0.5"
+  data-wcs="intersecting: featuresVisible"></wcs-intersect>
+```
+
+## 属性
+
+| 属性           | 型      | 既定値     | 説明 |
+|----------------|---------|------------|-------------|
+| `target`       | string  | *(省略)*   | 何を観測するか: 省略 → 最初の子、セレクタ → その要素、`self` → この要素。 |
+| `root`         | string  | *(viewport)* | スクロールルートのセレクタ。 |
+| `root-margin`  | string  | `0px`      | ルート周りのマージン（CSS の margin 構文）。 |
+| `threshold`    | string  | `0`        | 単一の比率（`0.5`）またはカンマ区切りリスト（`0,0.5,1`）の `0..1` の閾値。不正 / 範囲外の値は捨てられる。 |
+| `once`         | boolean | `false`    | 最初の交差した観測の後に切断する。 |
+| `manual`       | boolean | `false`    | 接続時に自動観測しない。代わりにコマンドで駆動する。 |
+
+> **`trigger`** には*属性がありません* — `@wcstack/state` の配線専用の瞬間的なコマンドプロパティです。`false → true` への書き込みは `observe()` を再実行し、プロパティは自動的に `false` にリセットされます（一度きりの確認応答。実際の結果は `observing` を読んでください）。状態駆動の観測には、この boolean より command-token プロトコル（`command.observe: …`）を優先してください。
+
+## 出力状態
+
+| プロパティ     | 型                         | 説明 |
+|----------------|----------------------------|-------------|
+| `entry`        | `WcsIntersectEntry \| null`| 直近の `IntersectionObserverEntry` のプレーンなスナップショット（rect はプレーンな数値に正規化）に、ライブの `target` ノードを加えたもの。 |
+| `intersecting` | `boolean`                  | ターゲットが現在ルートと交差しているか。 |
+| `ratio`        | `number`                   | 直近の `intersectionRatio`。 |
+| `visible`      | `boolean`                  | ラッチ: ターゲットが一度交差すると `true`。`reset()` でのみクリアされる。 |
+| `observing`    | `boolean`                  | 現在観測がアクティブか。 |
+
+## コマンド
+
+| コマンド       | 説明 |
+|---------------|-------------|
+| `observe()`   | DOM から `target` / `root` を再解決し、観測を（再）開始する。 |
+| `unobserve()` | 現在のターゲットの観測を停止する。 |
+| `disconnect()`| すべての観測を停止する。 |
+| `reset()`     | `visible` ラッチをクリアし、後の交差が再びそれを設定できるようにする。 |
+
+## Binding Contract（`wcBindable`）
+
+Core と Shell の両方が [wc-bindable](https://github.com/csbc-dev) プロトコルを宣言します。
+
+```js
+// IntersectionCore (headless)
+IntersectionCore.wcBindable = {
+  protocol: "wc-bindable",
+  version: 1,
+  properties: [
+    { name: "entry", event: "wcs-intersect:change" },
+    { name: "intersecting", event: "wcs-intersect:change", getter: (e) => e.detail.isIntersecting },
+    { name: "ratio", event: "wcs-intersect:change", getter: (e) => e.detail.intersectionRatio },
+    { name: "visible", event: "wcs-intersect:visible-changed" },
+    { name: "observing", event: "wcs-intersect:observing-changed" },
+  ],
+  commands: [
+    { name: "observe" }, { name: "unobserve" }, { name: "disconnect" }, { name: "reset" },
+  ],
+};
+```
+
+Shell（`<wcs-intersect>`）は Core の `properties` / `commands` を継承し、瞬間的な `trigger` プロパティを追加し、DOM 駆動の `inputs`（`target`, `root`, `rootMargin`, `threshold`, `once`, `manual`, `trigger`）を宣言します。
+
+## Core を単体で使う
+
+`IntersectionCore` はフレームワーク非依存で、カスタム要素なしで使えます。観測する要素を渡します（Shell はこの解決をあなたの代わりに行います）。
+
+```js
+import { IntersectionCore } from "@wcstack/intersection";
+
+const core = new IntersectionCore();
+core.addEventListener("wcs-intersect:change", (e) => {
+  console.log(e.detail.isIntersecting, e.detail.intersectionRatio);
+});
+core.observe(document.querySelector("#hero"), { threshold: [0, 0.5, 1] });
+// 後で
+core.disconnect();
+```
+
+## 注意点と制約
+
+- **単一ターゲット。** 各 `<wcs-intersect>` はちょうど 1 つの要素を観測するので、状態は単一の値面にマップします。多数のターゲットには多数の要素を使ってください。
+- **決して throw しない。** 非対応環境（`IntersectionObserver` が無い）や不正なオプション（例: 不正な形式の `root-margin`）は無言の no-op です。throw せず `observing` が `false` のままになります。
+- **パーミッションゲート / セキュアコンテキスト要件は無い**（`@wcstack/geolocation` と異なります）。
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,193 @@
+# @wcstack/intersection
+
+`@wcstack/intersection` is a headless IntersectionObserver component for the wcstack ecosystem.
+
+It is not a visual UI widget.
+It is an **async primitive node** that turns an element's *visibility* into reactive state — the same way `@wcstack/fetch` turns a network request into reactive state and `@wcstack/geolocation` turns the device's location into reactive state.
+
+With `@wcstack/state`, `<wcs-intersect>` can be bound directly through path contracts:
+
+- **input / command surface**: `target`, `root`, `root-margin`, `threshold`, `once`, `manual`, `trigger`
+- **output state surface**: `entry`, `intersecting`, `ratio`, `visible`, `observing`
+
+This means visibility-aware work — lazy-loading, infinite scroll, scroll-spying — can be expressed declaratively in HTML, without writing `new IntersectionObserver()`, `observe()`, `disconnect()`, or teardown glue in your UI layer.
+
+`@wcstack/intersection` follows the [CSBC](https://github.com/csbc-dev/arch/blob/main/README.md) (Core / Shell / Binding Contract) architecture:
+
+- **Core** (`IntersectionCore`) owns the observer, entry normalization, the `visible` latch, and observation lifecycle
+- **Shell** (`<wcs-intersect>`) resolves *what* to observe from the DOM, manages display, lifecycle, and declarative commands
+- **Binding Contract** (`static wcBindable`) declares observable `properties`, writable `inputs`, and callable `commands`
+
+## Why this exists
+
+IntersectionObserver is different from every other @wcstack sensor: the thing it observes is **a DOM element**, not a headless resource. Imperatively, wiring it up means creating an observer, resolving a target node, handling the entry callback, and tearing it all down on disconnect.
+
+`@wcstack/intersection` moves that logic into a reusable component and exposes the result as bindable state. An element scrolling into view becomes a **state transition**, not imperative callback wiring. It is a read-only producer: the element/layout only produces values for the state (`element/layout → state`), with no path back.
+
+## The `target` attribute decides everything
+
+`target` is the single knob that selects *what* is observed — and, with it, how `<wcs-intersect>` renders. It never injects a layout box unless you explicitly ask for one:
+
+| `target`          | observes              | `display`   | use case             |
+|-------------------|-----------------------|-------------|----------------------|
+| *omitted*         | first element child   | `contents`  | lazy-load wrapper    |
+| `"#hero"` / sel.  | the matched element   | `none`      | scrollspy (single)   |
+| `"self"`          | the element itself    | `block`     | infinite-scroll edge |
+
+`display:contents` means wrapping a child injects no box of its own — so `<wcs-intersect><img></wcs-intersect>` does not disturb a flex/grid parent. Only the explicit `target="self"` sentinel takes a box.
+
+> **First element child.** When `target` is omitted, the *first element child* is observed. The target is re-resolved on every `observe()` (which runs on connect and on each observed-attribute change), so adding or removing the first child after connect switches the observed element on the next re-observe. If there is no element child at resolution time, it falls back to observing itself (`display:block`). Observing multiple targets at once is intentionally out of scope — wrap each target in its own `<wcs-intersect>`.
+
+## Install
+
+```bash
+npm install @wcstack/intersection
+```
+
+## Quick Start
+
+### 1. Lazy-load an image (`visible` latch)
+
+`visible` flips to `true` the first time the target intersects and **stays** `true`. Bind the image `src` to it and the image only loads once it scrolls into view.
+
+```html
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+<script type="module" src="https://esm.run/@wcstack/intersection/auto"></script>
+
+<wcs-state>
+  <script type="module">
+    export default {
+      shown: false,
+      get src() {
+        return this.shown ? "/photo.jpg" : "";
+      }
+    };
+  </script>
+</wcs-state>
+
+<wcs-intersect once data-wcs="visible: shown">
+  <img data-wcs="src: src" alt="lazy">
+</wcs-intersect>
+```
+
+`once` disconnects the observer after the first intersection — ideal for one-shot lazy loads.
+
+### 2. Infinite scroll (sentinel)
+
+Place an empty `target="self"` marker at the bottom of a list; bind `intersecting` to a state flag that triggers loading more.
+
+```html
+<ul data-wcs="for: items">
+  <li data-wcs="textContent: items.*.name"></li>
+</ul>
+
+<wcs-intersect target="self" data-wcs="intersecting: atEnd"></wcs-intersect>
+```
+
+```js
+export default {
+  items: [],
+  atEnd: false,
+  get _loadMore() {
+    // a computed/effect that reacts to atEnd becoming true
+    return this.atEnd ? fetchNextPage() : null;
+  }
+};
+```
+
+### 3. Scrollspy (single section)
+
+Point `target` at a section elsewhere in the document; bind `intersecting` to highlight the matching nav item.
+
+```html
+<nav>
+  <a href="#features" data-wcs="class.active: featuresVisible">Features</a>
+</nav>
+
+<section id="features">…</section>
+
+<wcs-intersect target="#features" threshold="0.5"
+  data-wcs="intersecting: featuresVisible"></wcs-intersect>
+```
+
+## Attributes
+
+| Attribute      | Type    | Default    | Description |
+|----------------|---------|------------|-------------|
+| `target`       | string  | *(omitted)*| What to observe: omitted → first child, a selector → that element, `self` → this element. |
+| `root`         | string  | *(viewport)* | Selector for the scroll root. |
+| `root-margin`  | string  | `0px`      | Margin around the root (CSS-margin syntax). |
+| `threshold`    | string  | `0`        | A single ratio (`0.5`) or comma list (`0,0.5,1`) of `0..1` thresholds. Invalid / out-of-range values are dropped. |
+| `once`         | boolean | `false`    | Disconnect after the first intersecting observation. |
+| `manual`       | boolean | `false`    | Do not auto-observe on connect; drive it via commands instead. |
+
+> **`trigger`** has *no attribute* — it is a momentary command-property meant for `@wcstack/state` wiring only. A `false → true` write re-runs `observe()` and the property auto-resets to `false` (a one-shot acknowledgement; read `observing` for the actual outcome). Prefer the command-token protocol (`command.observe: …`) over this boolean for state-driven observation.
+
+## Output state
+
+| Property       | Type                       | Description |
+|----------------|----------------------------|-------------|
+| `entry`        | `WcsIntersectEntry \| null`| Plain snapshot of the latest `IntersectionObserverEntry` (rects normalized to plain numbers), plus the live `target` node. |
+| `intersecting` | `boolean`                  | Whether the target currently intersects the root. |
+| `ratio`        | `number`                   | The latest `intersectionRatio`. |
+| `visible`      | `boolean`                  | Latch: `true` once the target has intersected; cleared only by `reset()`. |
+| `observing`    | `boolean`                  | Whether an observation is currently active. |
+
+## Commands
+
+| Command       | Description |
+|---------------|-------------|
+| `observe()`   | Re-resolve `target` / `root` from the DOM and (re)start observing. |
+| `unobserve()` | Stop observing the current target. |
+| `disconnect()`| Stop all observation. |
+| `reset()`     | Clear the `visible` latch so a later intersection can set it again. |
+
+## Binding Contract (`wcBindable`)
+
+Both the Core and the Shell declare the [wc-bindable](https://github.com/csbc-dev) protocol.
+
+```js
+// IntersectionCore (headless)
+IntersectionCore.wcBindable = {
+  protocol: "wc-bindable",
+  version: 1,
+  properties: [
+    { name: "entry", event: "wcs-intersect:change" },
+    { name: "intersecting", event: "wcs-intersect:change", getter: (e) => e.detail.isIntersecting },
+    { name: "ratio", event: "wcs-intersect:change", getter: (e) => e.detail.intersectionRatio },
+    { name: "visible", event: "wcs-intersect:visible-changed" },
+    { name: "observing", event: "wcs-intersect:observing-changed" },
+  ],
+  commands: [
+    { name: "observe" }, { name: "unobserve" }, { name: "disconnect" }, { name: "reset" },
+  ],
+};
+```
+
+The Shell (`<wcs-intersect>`) inherits the Core's `properties` / `commands`, adds the momentary `trigger` property, and declares the DOM-driven `inputs` (`target`, `root`, `rootMargin`, `threshold`, `once`, `manual`, `trigger`).
+
+## Using the Core standalone
+
+`IntersectionCore` is framework-agnostic and can be used without the custom element. You hand it the element to observe (the Shell does this resolution for you):
+
+```js
+import { IntersectionCore } from "@wcstack/intersection";
+
+const core = new IntersectionCore();
+core.addEventListener("wcs-intersect:change", (e) => {
+  console.log(e.detail.isIntersecting, e.detail.intersectionRatio);
+});
+core.observe(document.querySelector("#hero"), { threshold: [0, 0.5, 1] });
+// later
+core.disconnect();
+```
+
+## Notes & limitations
+
+- **Single target.** Each `<wcs-intersect>` observes exactly one element so the state maps to a single value surface. For many targets, use many elements.
+- **Never throws.** Unsupported environments (no `IntersectionObserver`) and invalid options (e.g. a malformed `root-margin`) are silent no-ops: `observing` stays `false` rather than throwing.
+- **No permission gate / secure context requirement** (unlike `@wcstack/geolocation`).
+
+## License
+
+MIT

package/dist/auto.js

@@ -0,0 +1,3 @@
+import { bootstrapIntersection } from "./index.esm.js";
+
+bootstrapIntersection();

package/dist/auto.min.js

@@ -0,0 +1 @@
+import{bootstrapIntersection as o}from"./index.esm.min.js";o();

package/dist/index.d.ts

@@ -0,0 +1,275 @@
+interface ITagNames {
+    readonly intersect: string;
+}
+interface IWritableTagNames {
+    intersect?: string;
+}
+interface IConfig {
+    readonly tagNames: ITagNames;
+}
+interface IWritableConfig {
+    tagNames?: IWritableTagNames;
+}
+interface IWcBindableProperty {
+    readonly name: string;
+    readonly event: string;
+    readonly getter?: (event: Event) => any;
+}
+interface IWcBindableInput {
+    readonly name: string;
+    readonly attribute?: string;
+}
+interface IWcBindableCommand {
+    readonly name: string;
+    readonly async?: boolean;
+}
+interface IWcBindable {
+    readonly protocol: "wc-bindable";
+    readonly version: number;
+    readonly properties: IWcBindableProperty[];
+    readonly inputs?: IWcBindableInput[];
+    readonly commands?: IWcBindableCommand[];
+}
+/**
+ * Plain snapshot of a `DOMRectReadOnly` (e.g. `boundingClientRect`,
+ * `intersectionRect`, `rootBounds`). Unlike the live DOM rect, every field is a
+ * plain number so it can flow through data binding and be serialized.
+ */
+interface WcsIntersectRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ * Payload carried by the `wcs-intersect:change` event — a structured-clone-friendly
+ * snapshot of `IntersectionObserverEntry`, plus the live `target` Element for
+ * consumers that need the actual node.
+ *
+ * `boundingClientRect` / `intersectionRect` are always present; `rootBounds` is
+ * `null` when the root is a cross-origin document (mirroring the native API).
+ */
+interface WcsIntersectEntry {
+    isIntersecting: boolean;
+    intersectionRatio: number;
+    time: number;
+    boundingClientRect: WcsIntersectRect;
+    intersectionRect: WcsIntersectRect;
+    rootBounds: WcsIntersectRect | null;
+    /** The observed element. Not serializable — kept for consumers needing the node. */
+    target: Element;
+}
+/**
+ * Options accepted by `IntersectionCore.observe`, mirroring
+ * `IntersectionObserverInit`. `root` is an already-resolved Element (the Shell
+ * resolves a selector to a node before calling), or `null` for the viewport.
+ */
+interface IntersectOptions {
+    root?: Element | null;
+    rootMargin?: string;
+    threshold?: number | number[];
+}
+/**
+ * Value types for IntersectionCore (headless) — the observable state properties.
+ * Use with `bind()` from `@wc-bindable/core` for compile-time type checking.
+ *
+ * @example
+ * ```typescript
+ * const core = new IntersectionCore();
+ * bind(core, (name: keyof WcsIntersectCoreValues, value) => { ... });
+ * core.observe(document.querySelector("#hero")!);
+ * ```
+ */
+interface WcsIntersectCoreValues {
+    entry: WcsIntersectEntry | null;
+    intersecting: boolean;
+    ratio: number;
+    visible: boolean;
+    observing: boolean;
+}
+/**
+ * Value types for the Shell (`<wcs-intersect>`) — identical observable surface to
+ * the Core, plus the DOM-driven `trigger` command-property.
+ */
+interface WcsIntersectValues extends WcsIntersectCoreValues {
+    trigger: boolean;
+}
+interface WcsIntersectInputs {
+    /**
+     * What to observe. Omitted → the first element child (the element itself
+     * renders as `display:contents`). A selector (`"#hero"`, `".section"`) → the
+     * matched element (`display:none`). The literal `"self"` → the element itself
+     * as a zero-height marker (`display:block`).
+     */
+    target: string;
+    /** Selector for the scroll root. Omitted → the viewport. */
+    root: string;
+    rootMargin: string;
+    /** A single ratio or a comma list (`"0,0.5,1"`) of 0..1 thresholds. */
+    threshold: string;
+    /** Disconnect after the first time the target becomes intersecting. */
+    once: boolean;
+    /** Do not auto-observe on connect; observe is driven manually instead. */
+    manual: boolean;
+    /**
+     * Momentary command-property (no mirrored attribute): a `false`→`true` write
+     * re-runs `observe()`, then the flag immediately resets to `false`. Unlike the
+     * other inputs it does not reflect to an HTML attribute.
+     */
+    trigger: boolean;
+}
+interface WcsIntersectCoreCommands {
+    observe(element: Element, options?: IntersectOptions): void;
+    unobserve(element: Element): void;
+    disconnect(): void;
+    /** Clear the `visible` latch so it can be set again by a later intersection. */
+    reset(): void;
+}
+interface WcsIntersectCommands {
+    /** Re-resolve the target/root from the DOM and (re)start observing. */
+    observe(): void;
+    unobserve(): void;
+    disconnect(): void;
+    reset(): void;
+}
+
+declare function bootstrapIntersection(userConfig?: IWritableConfig): void;
+
+declare function getConfig(): IConfig;
+
+/**
+ * Headless visibility primitive. A thin, framework-agnostic wrapper around the
+ * IntersectionObserver API exposed through the wc-bindable protocol.
+ *
+ * Unlike the other @wcstack sensors (geolocation / timer / websocket), the thing
+ * being observed is a *DOM element* — so `observe()` takes the target node. The
+ * Core stays DOM-resolution-agnostic: it observes whatever element it is handed
+ * (the Shell resolves `target` / `root` selectors before calling). It is a
+ * read-only producer — element/layout → state only, with no element-bound path.
+ *
+ * Every observer callback is published via the single `wcs-intersect:change`
+ * event; `intersecting` / `ratio` are read from it through getters (mirroring how
+ * GeolocationCore exposes latitude/longitude from one `wcs-geo:position` event),
+ * so an observer that binds any of them is notified on every change.
+ *
+ * `visible` is a latch: it flips to `true` the first time the target intersects
+ * and stays `true` until `reset()` — ideal for one-way lazy-load bindings
+ * (`src@visible`). `observing` reflects whether an observation is currently
+ * active (like TimerCore's `running`).
+ *
+ * Single-target by design: the Shell observes exactly one element, so the state
+ * reflects that element. Multi-target observation is intentionally out of scope.
+ */
+declare class IntersectionCore extends EventTarget {
+    static wcBindable: IWcBindable;
+    private _target;
+    private _observer;
+    private _observed;
+    private _options;
+    private _entry;
+    private _visible;
+    private _observing;
+    constructor(target?: EventTarget);
+    get entry(): WcsIntersectEntry | null;
+    get intersecting(): boolean;
+    get ratio(): number;
+    get visible(): boolean;
+    get observing(): boolean;
+    private _setEntry;
+    private _setVisible;
+    private _setObserving;
+    /**
+     * Start observing `element`. Idempotent while already observing the same
+     * element with the same options. Changing the element or options tears down the
+     * current observer and builds a new one (IntersectionObserver options are fixed
+     * at construction, so reconfiguring requires a fresh observer).
+     *
+     * If IntersectionObserver is unavailable (SSR) or the options are invalid (e.g.
+     * a malformed `rootMargin`, which the constructor rejects), this is a silent
+     * no-op — `observing` stays false, consistent with the never-throw design of
+     * the other @wcstack sensors.
+     */
+    observe(element: Element, options?: IntersectOptions): void;
+    /**
+     * Stop observing `element`. A no-op if it is not the currently observed
+     * element. The observer instance is torn down (single-target Core), so a later
+     * observe() rebuilds it.
+     */
+    unobserve(element: Element): void;
+    /** Stop all observation and release the observer. */
+    disconnect(): void;
+    /** Clear the `visible` latch so a later intersection can set it again. */
+    reset(): void;
+    private _teardownObserver;
+    private _createObserver;
+    private _onIntersect;
+    private _normalizeEntry;
+    private _normalizeRect;
+    private _optionsEqual;
+    private _thresholdKey;
+}
+
+/**
+ * `<wcs-intersect>` — declarative IntersectionObserver.
+ *
+ * The `target` attribute is the single knob that decides both *what* is observed
+ * and how the element renders (it never injects a layout box unless asked):
+ *
+ * | `target`        | observes              | display     | use case          |
+ * |-----------------|-----------------------|-------------|-------------------|
+ * | omitted         | first element child   | `contents`  | lazy-load wrapper |
+ * | `"#hero"` / sel | the matched element   | `none`      | scrollspy (single)|
+ * | `"self"`        | the element itself    | `block`     | infinite-scroll   |
+ *
+ * `display:contents` means wrapping a child injects no box of its own (so a
+ * `<wcs-intersect><img></wcs-intersect>` does not disturb a flex/grid parent);
+ * only the explicit `target="self"` sentinel takes a box.
+ */
+declare class WcsIntersect extends HTMLElement {
+    static hasConnectedCallbackPromise: boolean;
+    static observedAttributes: string[];
+    static wcBindable: IWcBindable;
+    private _core;
+    private _trigger;
+    constructor();
+    get target(): string;
+    set target(value: string);
+    get root(): string;
+    set root(value: string);
+    get rootMargin(): string;
+    set rootMargin(value: string);
+    get threshold(): string;
+    set threshold(value: string);
+    get once(): boolean;
+    set once(value: boolean);
+    get manual(): boolean;
+    set manual(value: boolean);
+    get entry(): WcsIntersectEntry | null;
+    get intersecting(): boolean;
+    get ratio(): number;
+    get visible(): boolean;
+    get observing(): boolean;
+    get trigger(): boolean;
+    set trigger(value: boolean);
+    /** Re-resolve the target/root from the DOM and (re)start observing. */
+    observe(): void;
+    unobserve(): void;
+    disconnect(): void;
+    reset(): void;
+    private _resolveTarget;
+    private _resolveRoot;
+    private _safeQuery;
+    private _parseThreshold;
+    private _options;
+    private _onChange;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void;
+}
+
+export { IntersectionCore, WcsIntersect, bootstrapIntersection, getConfig };
+export type { IWritableConfig, IWritableTagNames, IntersectOptions, WcsIntersectCommands, WcsIntersectCoreCommands, WcsIntersectCoreValues, WcsIntersectEntry, WcsIntersectInputs, WcsIntersectRect, WcsIntersectValues };