@isdk/web-fetcher 0.3.0 → 0.3.1

package/README.action.extract.md

@@ -0,0 +1,263 @@
+# 🔍 Extract Action Deep Dive (The Data Surgeon's Manual)
+
+[简体中文](./README.action.extract.cn.md) | English
+
+`extract` is the heart of `@isdk/web-fetcher`. It's not just a "scraper"; it's an **intelligent converter** that transforms chaotic HTML into polished, ready-to-use JSON.
+
+---
+
+## ⚡ 1. Quick Start: Shorthand Magic
+
+**Scenario**: Standard webpages with simple structures. Get results fast without long JSON configurations.
+
+```json
+{
+  "action": "extract",
+  "params": {
+    "title": "h1",               // Grab h1 text into 'title'
+    "link": { "selector": "a.main", "attribute": "href" }, // Precision attribute extraction
+    "tags": { "type": "array", "selector": ".tag-item" }   // Grab a group of tags at once
+  }
+}
+```
+
+---
+
+## 📄 2. Basic Value Extraction: The Tweezers
+
+**Scenario**: Processing single data points like prices, titles, or IDs.
+
+### Value Properties Analysis
+
+* **`selector`**: CSS selector—tells the tweezers where to grab.
+* **`type`**: Automatic casting. Supports `string`, `number` (auto-removes currency/units), `boolean`, `html`.
+* **`mode`**: Extraction mode.
+  * `innerText`: **(Highly Recommended)** Sees like a human, capturing only visible text and handling line breaks/noise.
+  * `text`: Raw `textContent` from the source, including hidden characters.
+  * `outerHTML`: Captures the full HTML, including the element's tags.
+* **`attribute`**: If you need an attribute (e.g., `href`, `src`) instead of text, specify it here.
+* **`depth`**: Bubble up. Once matched, move up N parent levels before extracting (useful for grabbing IDs from parent containers).
+
+**Example**:
+
+```json
+{
+  "selector": ".price-tag",
+  "type": "number",       // Transforms "￥99.00" to 99
+  "mode": "innerText",    // Ensures clean text
+  "attribute": "data-v",  // Grabs the data-v attribute
+  "depth": 1              // Grabs from the parent element
+}
+```
+
+---
+
+## 📦 3. Object Extraction: The Bento Box
+
+**Scenario**: Pack related fields (e.g., name, avatar, bio) into a structured JSON object.
+
+### Object Properties Analysis
+
+* **`type: "object"`**: Declares the object structure.
+* **`selector`**: **The root container**. This is crucial! All internal property selectors are searched relative to this container.
+* **`properties`**: **Core Config**. Define your JSON keys and their respective extraction rules.
+* **`required`**: If a field is essential, set this to `true`. If extraction fails, the entire object returns `null`.
+* **`depth`**: Depth used to trigger "bubble-up" logic (see advanced chapter).
+
+**Example: Packing User Info**
+
+```json
+{
+  "type": "object",
+  "selector": ".user-card",
+  "properties": {
+    "name": { "selector": ".username", "required": true },
+    "bio": ".user-description",
+    "avatar": { "selector": "img.avatar", "attribute": "src" }
+  }
+}
+```
+
+> **💡 Transparent Box (Implicit Object)**: If you omit `type: "object"` and don't provide a `selector`, the box becomes "transparent." If all internal fields fail to extract, the entire box disappears. This is magical for filtering ads or empty items in a list.
+
+---
+
+## 📑 4. Array Extraction: The Sorting Machines
+
+**Scenario**: Handle repeating data like search results, news feeds, or tag clouds.
+
+### Array Properties Analysis
+
+* **`type: "array"`**: Declares a list extraction.
+* **`selector`**: **Scanning scope**. In default mode, it matches the "wrapper" of each item; in flat modes, it matches the entire list container.
+* **`items`**: **The Blueprint**. Defines what each row looks like. (Note: arrays use `items`, not `properties`).
+* **`mode`**: Choose the sorting strategy:
+  * `"nested"`: (Default) Every item has its own "slot" (container).
+  * `"columnar"`: Data is laid out in columns without row containers (like Excel).
+  * `"segmented"`: Data is completely flat, sliced into segments using "anchors."
+* **`limit`**: Restricts the maximum number of items to prevent data bloat.
+* **`inference`**: Heuristic inference. Enable this to let the engine automatically correct misalignments in messy lists.
+
+### 4.1 Nested (The Egg Carton): The Stable Standard
+
+**Scenario**: Items are wrapped in `<li>` or `.item` containers. This is the most stable and performant choice.
+
+```json
+{
+  "type": "array",
+  "selector": ".product-list .item", // Matches the shell of each product
+  "items": {
+    "name": "h3",
+    "price": ".price"
+  }
+}
+```
+
+### 4.2 Columnar: Flat Alignment
+
+**Scenario**: Data laid out like a spreadsheet. One column for titles, one for prices, but no shared parent for the row.
+**Broadcasting**: If a field is constant across all items (e.g., category), extract it once from the main container, and it will "broadcast" to every row.
+
+```json
+{
+  "type": "array",
+  "selector": "#table-container",
+  "mode": "columnar",
+  "items": {
+    "name": ".title-cols",
+    "date": "" // Empty selector broadcasts date info from the main container
+  }
+}
+```
+
+### 4.3 Segmented: Slicing the Unordered
+
+**Scenario**: Terrible page structure where everything is siblings. You must rely on a marker (like an `h2` header) to define segments.
+
+```json
+{
+  "type": "array",
+  "selector": ".content-body",
+  "mode": { "type": "segmented", "anchor": "h2" }, // Slice whenever an h2 is found
+  "items": {
+    "section_title": "h2",
+    "text": "p"
+  }
+}
+```
+
+---
+
+## 🛡️ 5. Quality Control: Filters & Sieves
+
+**Scenario**: Filtering out ads, out-of-stock notices, or unwanted junk items.
+
+* **`has`**: **The Essence Filter**. Only extract if it contains specific sub-elements. Example: `"has": ".promo-tag"` only keeps items with discount tags.
+* **`exclude`**: **The Junk Remover**. Exclude matching elements. Example: `"exclude": ".is-advertisement"`.
+* **`strict`**: **OCD Mode**. If a required field is missing, throw an error immediately instead of silently returning `null`.
+
+---
+
+## 🧠 6. Advanced Mastery: Scope & Boundary Control
+
+Surgical solutions for messy, class-less, and flat-structured HTML.
+
+### 6.1 Sequential Slicing: Solving "The Twin Tag" Problem
+
+* **Pain Point**: A row of identical `<span>` or `p` tags. A simple selector only grabs the first one repeatedly.
+* **Solution**: `relativeTo: "previous"`.
+* **Mechanism**: The engine remembers where it left off. After extracting the first field, it leaves a "Bookmark." The next search starts **after that Bookmark**.
+* **Key Point**: Since this is sequential, we recommend explicitly setting `order: ["name", "job"]` to ensure the bookmarks don't get mixed up due to JSON key ordering.
+* **Example Scenario**:
+
+    ```html
+    <p>Name</p> <span>Alice</span>
+    <p>Job</p> <span>Manager</span>
+    ```
+
+* **Example Config**:
+
+    ```json
+    {
+      "relativeTo": "previous",
+      "order": ["k1", "v1", "k2", "v2"], // Force order to prevent bookmark displacement
+      "properties": {
+        "k1": "p",    // Grabs 1st p (Name)
+        "v1": "span", // Grabs Alice after k1
+        "k2": "p",    // Grabs 2nd p (Job) after v1
+        "v2": "span"  // Grabs Manager after k2
+      }
+    }
+    ```
+
+### 6.2 Segmented Isolation & LCA: Building "Fences" for Neighbors
+
+* **Pain Point**: In flat structures, Item 1's search might bleed into Item 2's content without a boundary.
+* **Solution**: Use `mode: "segmented"` with `anchor`.
+* **Mechanism**: The engine calculates the "Lowest Common Ancestor (LCA)" between anchors and builds a logical fence, locking searches strictly within the item's territory.
+* **Example Scenario**:
+
+    ```html
+    <h2 class="title">Article 1</h2>
+    <p class="summary">Summary 1</p>
+    <h2 class="title">Article 2</h2>
+    <p class="summary">Summary 2</p>
+    ```
+
+* **Example Config**:
+
+    ```json
+    {
+      "type": "array",
+      "mode": { "type": "segmented", "anchor": "h2.title" }, // h2 as the fence
+      "items": {
+        "title": "h2",
+        "desc": "p"
+      }
+    }
+    ```
+
+### 6.3 Bubble-up: The "Retry" Safety Net
+
+* **Pain Point**: Data is just outside the locked scope (e.g., an ID on a parent container).
+* **Solution**: Set `depth` and use `required`.
+* **Mechanism**:
+    1. The engine looks for a mandatory field in the current scope—fails.
+    2. It automatically steps back (`depth: 1`) to the parent node.
+    3. It rescans in the wider view to find missing data that was "just out of sight."
+* **Example Scenario**:
+
+    ```html
+    <div class="wrapper" data-id="ID_001">
+      <div class="content-box">
+        <h3 class="title">Product Name</h3>
+      </div>
+    </div>
+    ```
+
+* **Example Config**:
+
+    ```json
+    {
+      "selector": ".content-box",
+      "depth": 1,
+      "properties": {
+        "product_id": {
+          "selector": "..",        // ".." means look at parent
+          "attribute": "data-id",
+          "required": true         // Fails to trigger bubble-up
+        },
+        "name": "h3"
+      }
+    }
+    ```
+
+---
+
+## 💡 7. Best Practice Tips
+
+1. **Containers First**: If the HTML has `.item` wrappers, always prefer `Nested` mode—it's the stablest and fastest.
+2. **innerText as Default**: In 90% of cases, it's better than `text` because it yields cleaner results and handles line breaks automatically.
+3. **Flat Siblings? Use Anchors**: When you see siblings without a container shell, immediately think `segmented` + `anchor`.
+4. **Leverage required for Filtering**: If some items in a list are empty (placeholders), mark core fields as `required: true`. They will automatically become `null`, making them easy to filter in your code.
+5. **Debug Tip: Check the Scope**: If data is missing, check if your `selector` is too restrictive or try increasing the `depth`.

package/README.action.md

@@ -247,6 +247,52 @@ Retrieves the full content of the current page state.
 * **`params`**: (none)
 * **`returns`**: `response`
 
+#### `mouseMove`
+
+Moves the mouse cursor to a specific coordinate or element. In `browser` mode, it uses a **Bézier curve** to simulate a human-like non-linear trajectory with slight jitter for realism.
+
+* **`id`**: `mouseMove`
+* **`params`**:
+  * `x` (number, optional): The absolute X coordinate.
+  * `y` (number, optional): The absolute Y coordinate.
+  * `selector` (string, optional): A CSS selector. If provided, the mouse moves to the center of the element.
+  * `steps` (number, optional): The number of intermediate steps for the trajectory (default: `-1`). Set to `-1` to calculate steps automatically based on distance (simulating natural speed).
+* **`returns`**: `none`
+
+#### `mouseClick`
+
+Triggers a mouse click at the current position or specified coordinates. If a `selector` is provided, the cursor will first move smoothly to the target element (using dynamic steps) before clicking.
+
+* **`id`**: `mouseClick`
+* **`params`**:
+  * `x` (number, optional): The absolute X coordinate to click.
+  * `y` (number, optional): The absolute Y coordinate to click.
+  * `selector` (string, optional): A CSS selector. If provided, moves the mouse to the element first.
+  * `button` (string, optional): The mouse button to use (`left`, `right`, or `middle`). Default is `left`.
+  * `clickCount` (number, optional): The number of clicks (e.g., 2 for double-click). Default is 1.
+  * `delay` (number, optional): Delay between mousedown and mouseup in milliseconds.
+* **`returns`**: `none`
+
+#### `keyboardType`
+
+Simulates a person typing text into the currently focused element.
+
+* **`id`**: `keyboardType`
+* **`params`**:
+  * `text` (string): The text to type.
+  * `delay` (number, optional): The delay between key presses in milliseconds (default: 100).
+* **`returns`**: `none`
+
+#### `keyboardPress`
+
+Simulates pressing a single key or a key combination (e.g., `Enter`, `Control+A`).
+
+* **`id`**: `keyboardPress`
+* **`params`**:
+  * `key` (string): The name of the key to press (e.g., `Enter`, `Tab`, `Backspace`, `ArrowUp`).
+  * `delay` (number, optional): The delay after the key press in milliseconds.
+* **`returns`**: `none`
+
 #### `evaluate`
 
 Executes custom JavaScript code or an expression within the page context.
@@ -306,321 +352,17 @@ $`).
 
 #### `extract`
 
-Extracts structured data from the page using a powerful and declarative Schema. This is the core Action for data collection.
+Extracts structured data from the page using a powerful and declarative Schema.
 
 * **`id`**: `extract`
-* **`params`**: An `ExtractSchema` object that defines the extraction rules.
-* **`returns`**: `any` (the extracted data)
-
-##### Detailed Explanation of Extraction Schema
-
-The `params` object itself is a Schema that describes the data structure you want to extract.
-
-###### 1. Extracting a Single Value
-
-The most basic extraction. You can specify a `selector` (CSS selector), an `attribute` (the name of the attribute to extract), a `type` (string, number, boolean, html), and a `mode` (text, innerText).
-
-* **`depth`** (number, optional): After matching the element with `selector`, it bubbles up the DOM tree by the specified number of levels. The resulting ancestor element becomes the actual target for value extraction (e.g., to extract an attribute from a parent wrapper).
-
-```json
-{
-  "id": "extract",
-  "params": {
-    "selector": "h1.main-title",
-    "type": "string",
-    "mode": "innerText"
-  }
-}
-```
-
-> **Extraction Modes:**
->
-> * **`text`** (default): Extracts the `textContent` of the element.
-> * **`innerText`**: Extracts the rendered text, respecting CSS styling and line breaks.
-> * **`html`**: Returns the `innerHTML` of the element.
-> * **`outerHTML`**: Returns the HTML including the tag itself. Useful for preserving the full element structure.
-> The example above will extract the text content of the `<h1>` tag with the class `main-title` using the `innerText` mode.
-
-###### 2. Extracting an Object
-
-Define a structured object using `type: 'object'` and the `properties` field.
-
-```json
-{
-  "id": "extract",
-  "params": {
-    "type": "object",
-    "selector": ".author-bio",
-    "properties": {
-      "name": { "selector": ".author-name" },
-      "email": { "selector": "a.email", "attribute": "href" }
-    }
-  }
-}
-```
-
-* **`depth`** (number, optional): Enables "Try-And-Bubble" strategy. If a `required` field is missing in the matched element, the engine attempts to bubble up the DOM tree (up to `depth` levels) to find an ancestor where the required field exists. This is useful when the selector matches a descendant (e.g., an inner `span`) but the data resides on a parent container.
-
-**Advanced Object Features:**
-
-* **Anchor Jumping (`anchor`)**: Specifies a starting reference point for a field.
-  * **Field Reference**: Use the DOM element of a previously extracted field.
-  * **CSS Selector**: Query an anchor element on the fly within the object's scope.
-  * **`depth`** (number, optional): When using an anchor, defines how many parent levels to traverse upwards to collect following siblings.
-    * **Note**: If omitted, the engine defaults to maximum depth (up to the object's root) for backward compatibility. To strictly limit the search to the anchor's own siblings, set `depth: 0`.
-  * **Effect**: Once an anchor is set, the search scope for that field becomes the siblings **following** the anchor (and its ancestors, depending on `depth`). This allows for non-linear "jumping" extraction in flat structures.
-* **Sequential Consumption (`relativeTo: "previous"`)**:
-  * Combined with the `order` property, this ensures each field's search scope starts *after* the previous field's match.
-  * Essential for extracting from lists composed of identical tags (e.g., consecutive `<p>` tags with different meanings).
-
-###### 3. Extracting an Array (Convenient Usage)
-
-Extract a list using `type: 'array'`. To make the most common operations simpler, we provide some convenient usages.
-
-* **Extracting an Array of Texts (Default Behavior)**: When you want to extract a list of text, just provide the selector and omit `items`. This is the most common usage.
-
-    ```json
-    {
-      "id": "extract",
-      "params": {
-        "type": "array",
-        "selector": ".tags li"
-      }
-    }
-    ```
-
-    > The example above will return an array of the text from all `<li>` tags, e.g., `["tech", "news"]`.
-
-* **Extracting an Array of Attributes (Shortcut)**: When you only want to extract a list of attributes (e.g., all `href`s from links), there's no need to nest `items` either. Just declare `attribute` directly in the `array` definition.
-
-    ```json
-    {
-      "id": "extract",
-      "params": {
-        "type": "array",
-        "selector": ".gallery img",
-        "attribute": "src"
-      }
-    }
-    ```
-
-    > The example above will return an array of the `src` attributes from all `<img>` tags.
-
-* **Array Extraction Modes**: When extracting an array, the engine supports different modes to handle various DOM structures.
-
-  * **`nested`** (Default): The `selector` matches individual item wrappers.
-  * **`columnar`** (formerly Zip): The `selector` matches a **container**, and fields in `items` are parallel columns stitched together by index.
-  * **`segmented`**: The `selector` matches a **container**, and items are segmented by an "anchor" field.
-
-###### 4. Columnar Mode (formerly Zip Strategy)
-
-This mode is used when the `selector` points to a **container** (like a results list) and item data is scattered as separate columns. It is highly optimized for performance, especially in browser mode, by minimizing the number of DOM queries and RPC calls.
-
-> **💡 Broadcasting & Performance**: If a property matches the container element itself (e.g. by omitting a selector or matching the container's own attributes), its value is **broadcasted** to every row. This is not only a feature but also a major performance optimization: the value is extracted **once** and reused across all rows, avoiding thousands of redundant engine calls.
-
-```json
-{
-  "id": "extract",
-  "params": {
-    "type": "array",
-    "selector": "#search-results",
-    "mode": "columnar",
-    "items": {
-      "title": { "selector": ".item-title" },
-      "link": { "selector": "a.item-link", "attribute": "href" }
-    }
-  }
-}
-```
-
-> **Heuristic Detection:** If `mode` is omitted and the `selector` matches exactly one element while `items` contains nested selectors, the engine automatically uses **columnar** mode.
+* **`params`**: An `ExtractSchema` object.
+* **`returns`**: The extracted structured data.
 
-**Example: Columnar Broadcasting**
-
-When you have a list where the category is on the container, but items are inside.
-
-```json
-{
-  "id": "extract",
-  "params": {
-    "type": "array",
-    "selector": "#book-category",
-    "mode": "columnar",
-    "items": {
-      "category": { "attribute": "data-category" },
-      "title": { "selector": ".book-title" }
-    }
-  }
-}
-```
-
-> If `#book-category` has `data-category="Sci-Fi"` and contains 3 books, the result will be 3 items, each having `"category": "Sci-Fi"`.
-
-**Columnar Configuration:**
-
-* **`strict`** (boolean, default: `true`): If `true`, throws an error if fields have different match counts.
-* **`inference`** (boolean, default: `false`): If `true`, tries to automatically find the "item wrapper" elements to fix misaligned lists. It uses an **optimized ancestor search** that is significantly faster in browser mode than manual traversal.
-* **Performance Note**: The engine automatically detects shared structures and pre-calculates alignment to ensure O(N) performance even in complex DOM trees. In browser mode, it minimizes IPC round-trips by pre-calculating "broadcast" flags.
-
-###### 5. Segmented Mode (Anchor-based Scanning)
-
-Ideal for "flat" structures where there are no item wrappers. It uses a specified `anchor` to segment the container's content.
-
-**Core Feature: Automatic Container Detection (Bubble Up)**
-
-To handle structures that appear flat but have subtle containers, the engine uses a bubble-up strategy:
-
-- **Smart Bubble Up**: When an anchor is nested deep (e.g., `div.card > h3.title`), the engine automatically crawls up the DOM to find the largest "safe container" (e.g., `div.card`) that doesn't overlap with neighbors.
-- **Logical Isolation**: If a container is found, it becomes the scope for that segment. This allows you to extract any content within that container using simple relative selectors, even if it's "above" or deep alongside the anchor.
-- **Flat Fallback**: If no container isolation is possible, it automatically falls back to classic sibling scanning.
-
-```json
-{
-  "id": "extract",
-  "params": {
-    "type": "array",
-    "selector": "#flat-container",
-    "mode": { "type": "segmented", "anchor": "h3.item-title" },
-    "items": {
-      "title": { "selector": "h3" },
-      "desc": { "selector": "p" }
-    }
-  }
-}
-```
-
-**Segmented Configuration:**
-
-* **`anchor`** (string):
-  * Can be a **field name** defined in `items` (e.g., `"title"`).
-  * Can be a **direct CSS selector** (e.g., `"h3.item-title"`).
-  * Defaults to the selector of the first field in `items`.
-* **`depth`** (number, optional): The maximum number of levels to bubble up from the anchor to find a segment container. If omitted, it bubbles up as high as possible without conflicting with neighboring segments.
-* **`strict`** (boolean, default: `false`): If `true`, throws an error if no anchor elements are found or if any item violates its own `required` constraints.
-
-###### 5.1 Advanced: Handling Repeating Tags (`relativeTo`)
-
-When a segment contains multiple identical tags (e.g., several `<p>` tags in a row) representing different fields, use `relativeTo: "previous"` to "consume" them one by one.
-
-```json
-{
-  "id": "extract",
-  "params": {
-    "type": "array",
-    "selector": "#container",
-    "mode": {
-      "type": "segmented",
-      "anchor": ".item-start",
-      "relativeTo": "previous"
-    },
-    "items": {
-      "type": "object",
-      "order": ["id", "desc", "extra"],
-      "properties": {
-        "id": "h1",
-        "desc": "p",
-        "extra": "p"
-      }
-    }
-  }
-}
-```
-
-* **`relativeTo: "previous"`**: After finding `id` (h1), the search for `desc` starts *after* that h1. After finding `desc` (the first p), the search for `extra` starts *after* that p, successfully picking up the second `<p>`.
-* **`order`**: Defines the sequence of consumption. Highly recommended with `relativeTo: "previous"`.
-
-###### 6. Quality Control: `required` and `strict`
-
-- **`required`**: Marks a field as mandatory.
-  - **In Objects**: If any required field is `null`, the entire object returns `null`.
-  - **In Arrays**: Items missing a required field are automatically skipped.
-  - **Null Propagation**: For implicit objects without a `selector`, if ALL sub-properties are `null`, the object itself becomes `null`, triggering parent-level required or skip logic.
-- **`strict`**:
-  - `false` (Default): Silently skip or ignore incomplete data.
-  - `true`: Throw an error on any missing required field or alignment mismatch.
-  - **Inheritance**: Setting `strict: true` at the array level automatically propagates to all nested children.
-
-**Example: Ignoring items with missing mandatory fields**
-
-```json
-{
-  "id": "extract",
-  "params": {
-    "type": "array",
-    "selector": ".product-list",
-    "mode": "columnar",
-    "items": {
-      "name": { "selector": ".title", "required": true },
-      "price": { "selector": ".price", "required": true },
-      "discount": ".promo"
-    }
-  }
-}
-```
-
-> In this example, if a product lacks either a `name` or a `price`, it will be completely omitted from the result array. The optional `discount` field doesn't affect the item's inclusion.
-
-###### 7. Implicit Object Extraction (Simplest Syntax)
-
-For simpler object extraction, you can omit `type: 'object'` and `properties`. If the schema object contains keys that are not context-defining keywords (like `selector`, `has`, `exclude`, `required`, `strict`, `depth`), it is treated as an object schema where keys are property names.
-
-> **Keyword Collision Handling:** You can safely extract a data field named `type` as long as its value is not a reserved schema type (like `"string"`, `"object"`, `"array"`, etc.).
-
-```json
-{
-  "id": "extract",
-  "params": {
-    "selector": ".author-bio",
-    "name": ".author-name",
-    "type": ".author-rank",
-    "items": { "type": "array", "selector": "li" }
-  }
-}
-```
-
-> **Key features of implicit objects:**
+> **📚 Detailed Manual**: Because `extract` is very rich in features (including array modes, scope control, anchor jumping, etc.), we have prepared a dedicated detailed manual:
 >
-> 1. **Keyword Handling**: Common configuration keywords like `items`, `attribute`, or `mode` **can be used as property names** within an implicit object. They are only treated as configuration when a `type` (like `array`) is explicitly present. Configuration keywords like `required`, `strict`, and `depth` are also handled as context defining keys.
-> 2. **String Shorthand**: You can use a simple string as a property value (e.g., `"email": "a.email"`), which is automatically expanded to `{ "selector": "a.email" }`.
-> 3. **Context Separation**: Only `selector`, `has`, `exclude`, `required`, `strict`, and `depth` are used to define the context and validation for the implicit object; all other keys are treated as data to be extracted.
-> 4. **Null Propagation**: If an implicit object has no `selector` and ALL of its sub-properties extract to `null`, the object itself returns `null`. This is crucial for `required` validation on the parent object or for skipping items in an array.
-
-###### 8. Advanced Filtering: `has` and `exclude`
-
-You can use the `has` and `exclude` fields in any schema that includes a `selector` to precisely control element selection.
-
-* `has`: A CSS selector to ensure the selected element **must contain** a descendant matching this selector.
-* `exclude`: A CSS selector to **exclude** elements matching this selector from the results.
-
-**Complete Example: Extracting links of articles that have an image and are not marked as "draft"**
-
-```json
-{
-  "actions": [
-    { "id": "goto", "params": { "url": "https://example.com/articles" } },
-    {
-      "id": "extract",
-      "params": {
-        "type": "array",
-        "selector": "div.article-card",
-        "has": "img.cover-image",
-        "exclude": ".draft",
-        "items": {
-          "selector": "a.title-link",
-          "attribute": "href"
-        }
-      }
-    }
-  ]
-}
-```
+> 👉 **[Click to View Extract Action Deep Dive](./README.action.extract.md)**
 
-> The `extract` action above will:
->
-> 1. Find all `div.article-card` elements.
-> 2. Filter them to only include those that contain an `<img class="cover-image">`.
-> 3. Further filter the results to exclude any that also have the `.draft` class.
-> 4. For each of the remaining `div.article-card` elements, find its descendant `a.title-link` and extract the `href` attribute.
+---
 
 ### Building High-Level Semantic Actions via "Composition"
 
@@ -800,7 +542,7 @@ In `@isdk/web-fetcher`, an Action's `static returnType` is more than a type hint
 * **Definition**: Any serializable data structure (Object, Array, string, etc.).
 * **Purpose**: Primary mechanism for business data extraction.
 * **Usage**: Use this when your action produces processed data that doesn't represent the whole page or system state.
-* **System Behavior**: If the action configuration includes `storeAs: "key"`, the framework automatically saves the `result` into `context.outputs["key"]`.
+* **System Behavior**: If the action configuration includes `storeAs: "key"`, the framework automatically saves the `result` into `context.outputs["key"]`. If the target key already contains an object and the new result is also an object, they will be merged (shallow merge) instead of overwritten. This allows multiple `extract` actions to accumulate data into the same output key.
 * **Typical Actions**: `extract`.
 * **Example**: