dsh-moli 1.1.15 → 1.1.17

package/README.md

@@ -209,7 +209,7 @@ An unresolvable bundle is **skipped silently** apart from one stderr line
 
 ## Usage
 
-`moli_fetch` parameters: `url` (required), `dump`, `writeTo`, `eval`, `scroll`, `wait`,
+`moli_fetch` parameters: `url` (required), `dump`, `writeTo`, `selector`, `eval`, `scroll`, `wait`,
 `waitSelector`, `waitScript`, `waitResponseUrl`, `waitResponseJson`, `delayMs`, `timeoutMs`,
 `maxChars`, `headers`, `userAgent`, `layout`, `scrollbars`, `noJs`, `noCss`, `resources`,
 `withFrames`, `insecureTls`, `failOnHttpError`, `profileDir`, `cookieFile`, `proxy`.
@@ -218,6 +218,7 @@ An unresolvable bundle is **skipped silently** apart from one stderr line
 moli_fetch url=https://example.com dump=markdown             # token-efficient text
 moli_fetch url=https://example.com dump=semantic_tree_text    # nodes with backend ids
 moli_fetch url=https://example.com eval="document.title"      # one computed value
+moli_fetch url=https://example.com selector=".video-card"     # one container, not the page
 moli_fetch url=https://example.com dump=screenshot writeTo=/abs/path/a.png
 moli_fetch url=https://example.com dump=pdf        writeTo=/abs/path/a.pdf
 moli_fetch url=https://example.com dump=markdown scroll=800   # trigger lazy loading first
@@ -225,6 +226,35 @@ moli_fetch url=https://example.com dump=markdown scroll=800   # trigger lazy loa
 
 Screenshot and PDF dumps need `writeTo`; the bytes are written verbatim rather than printed.
 
+### `selector` — read one container, not the page
+
+A listing page is mostly noise if you only want the items. `selector` returns the text
+of the elements a CSS selector matches, which on a node-dense feed measured **1,829
+characters against 95,605** for the same page as Markdown.
+
+```
+moli_fetch url=https://example.com/feed selector=".video-card"
+moli_fetch url=https://example.com/feed selector="h2" scroll=2000    # scroll first, then read
+```
+
+All matches are joined with newlines and the result reports how many there were:
+"matched 48 element(s)" is the difference between a complete read and a partial one,
+and it is the only signal you get that the selector was too broad or too narrow.
+
+Two cases are deliberately errors rather than empty answers, because the engine
+cannot tell an empty selection from a page with no text — an expression returning
+`""` exits 0 with a blank line:
+
+- **nothing matched** — `ok: false`, "no element matches". A selector that is not on
+  the page is almost always a spelling mistake or a page that has not loaded yet.
+- **matched, but no text** — `ok: false`, "match but none of them has any text", which
+  is what an icon or an image container gives you. Use `eval` if you need attributes.
+
+`selector` cannot be combined with `dump` or `eval`: a selector returns one
+container's text, a dump returns the whole page, and only one expression value can be
+returned — so one of them could only be silently ignored, which is the failure mode
+this plugin keeps having to fix.
+
 ### `scroll` — reach what only appears on a scroll
 
 The engine serializes the whole document, so a plain fetch already contains everything the DOM holds.
@@ -242,8 +272,29 @@ Measured on a page whose `scroll` handler fills a slot: without `scroll` the dum
 `STILL-EMPTY`, with `scroll=1000` it says `LAZY-CONTENT-1000`. It also moves the screenshot, so a
 scrolled `dump=screenshot` shows that part of the page.
 
-It runs as part of the engine's own pre-capture evaluation and therefore composes with `eval`: the
-scroll happens first, and the expression still returns its own value.
+`scroll` is a side effect, so it composes and stands alone:
+
+```
+moli_fetch url=... dump=markdown scroll=600      # scroll, then dump the page
+moli_fetch url=... eval="document.title" scroll=600   # scroll, then read a value
+moli_fetch url=... scroll=600                    # just scroll; you still get the page
+```
+
+The last form is worth spelling out because it was broken. The scroll runs in the engine's own
+pre-capture evaluation, and without `dump` the engine prints whatever that evaluation returns — so an
+earlier version that returned the scroll position made this call answer `600` instead of the document,
+while the identical call without `scroll` returned 1,989 characters of HTML. A scroll reports nothing
+now; it only happens.
+
+### `eval` with `dump` — the expression value is dropped
+
+The engine documents this and it is kept, because using an expression to change a page before
+capturing it is a real pattern. What is not acceptable is that it used to look like a clean answer:
+`eval='JSON.stringify({probe:1})'` with `dump=markdown` returned 900 characters of Markdown, reported
+`ok: true`, and said nothing. The result now carries `evalDiscarded: true` and a note, and the rendered
+output leads with the warning rather than burying it under the body.
+
+If you want the expression's value, pass `eval` without `dump`.
 
 ### `failOnHttpError` — stop reading an error page as content
 
@@ -468,10 +519,17 @@ Eight suites live in [`verify/`](verify/), and all are runnable against a workin
   `bottom`, nonsense rejected, the caller's `eval` value preserved) and then, when an engine is
   present, fetches a page whose `scroll` handler fills a slot and asserts the content appears with
   `scroll` and the placeholder appears without it — a property of the output, not of an internal call.
+- `selector-verify.mjs` covers the two silent-wrong-answer cases a container read invites: a selector
+  matching nothing is an error rather than empty content, and a selector matching several elements
+  reports the count and joins them. It also asserts that the selector is quoted as data rather than
+  spliced into the expression, that `selector` with `dump` or `eval` is refused instead of one of them
+  being ignored, and that it composes with `scroll`.
 - `http-verify.mjs` asserts the parameter-to-flag mapping directly, because a parameter that never
   reaches the engine is indistinguishable from a feature that does not work. It then fetches a 404 and
   checks that `failOnHttpError` reports it while keeping the body, that a healthy page is unaffected,
   and that a screenshot of an error page is still written as a valid PNG rather than decoded as text.
+  It also covers the two silent-answer cases: `eval` with `dump` is flagged `evalDiscarded` and the
+  warning renders first, and `scroll` alone returns the document rather than the scroll offset.
   The end-to-end half needs an HTTP error from a real server: loopback is unreachable from inside this
   sandbox — `curl.exe` times out on `127.0.0.1` while the Node host reaches it — so it uses a path
   under `example.com` and skips when the network is away.

package/README.zh.md

@@ -195,15 +195,16 @@ profile 插件需要两半都齐：依赖边（`dependencies`）+ `dsh.profile.b
 
 ## 用法
 
-`moli_fetch` 参数：`url`（必填）、`dump`、`writeTo`、`eval`、`scroll`、`wait`、`waitSelector`、
-`waitScript`、`waitResponseUrl`、`waitResponseJson`、`delayMs`、`timeoutMs`、`maxChars`、`headers`、
-`userAgent`、`layout`、`scrollbars`、`noJs`、`noCss`、`resources`、`withFrames`、`insecureTls`、
-`failOnHttpError`、`profileDir`、`cookieFile`、`proxy`。
+`moli_fetch` 参数：`url`（必填）、`dump`、`writeTo`、`selector`、`eval`、`scroll`、`wait`、
+`waitSelector`、`waitScript`、`waitResponseUrl`、`waitResponseJson`、`delayMs`、`timeoutMs`、
+`maxChars`、`headers`、`userAgent`、`layout`、`scrollbars`、`noJs`、`noCss`、`resources`、
+`withFrames`、`insecureTls`、`failOnHttpError`、`profileDir`、`cookieFile`、`proxy`。
 
 ```
 moli_fetch url=https://example.com dump=markdown            # 省 token 的正文
 moli_fetch url=https://example.com dump=semantic_tree_text   # 带节点 id 的结构
 moli_fetch url=https://example.com eval="document.title"     # 取一个值
+moli_fetch url=https://example.com selector=".video-card"    # 只取一个容器，不要整页
 moli_fetch url=https://example.com dump=screenshot writeTo=/绝对路径/a.png
 moli_fetch url=https://example.com dump=pdf        writeTo=/绝对路径/a.pdf
 moli_fetch url=https://example.com dump=markdown scroll=800  # 先触发懒加载再抓取
@@ -211,6 +212,29 @@ moli_fetch url=https://example.com dump=markdown scroll=800  # 先触发懒加
 
 截图与 PDF 必须给 `writeTo`；字节是原样落盘的，不会打印到输出里。
 
+### `selector` —— 只取一个容器，不要整页
+
+列表页里如果只要条目，正文大部分都是噪声。`selector` 返回 CSS 选择器匹配到的元素文本——在一个节点密集的
+信息流上实测**1,829 字符，而同一页面走 markdown 是 95,605**。
+
+```
+moli_fetch url=https://example.com/feed selector=".video-card"
+moli_fetch url=https://example.com/feed selector="h2" scroll=2000    # 先滚再取
+```
+
+所有匹配项以换行拼接，并且结果会报告匹配到多少个：**"matched 48 element(s)"** 是"读全了"和"只读到一部分"
+的区别，也是你判断选择器太宽或太窄的唯一信号。
+
+两种情况**刻意做成错误而不是空答案**，因为引擎分不清"没匹配到"和"页面没有文本"——表达式返回 `""` 时是
+exit 0 加一个空行：
+
+- **没有任何匹配** —— `ok: false`，"no element matches"。页面上不存在的选择器几乎总是拼写错误或页面还没加载。
+- **匹配到了但没有文本** —— `ok: false`，说明匹配到了但都没文本，这通常会发生在图标或图片容器上。需要属性就
+  用 `eval`。
+
+`selector` 不能与 `dump` 或 `eval` 同传：选择器返回一个容器的文本、dump 返回整页、而一次只能返回一个表达式
+值——所以其中一个只能被**静默忽略**，而这正是这个插件一路在修的那类失败。
+
 ### `scroll` —— 拿到"只有滚动后才出现"的内容
 
 引擎会序列化整个文档，所以普通抓取**已经包含 DOM 里的一切**。它拿不到的是**尚未存在的内容**：首次
@@ -227,8 +251,26 @@ moli_fetch url=https://example.com/feed dump=markdown scroll=-400    # 往回滚
 `scroll=1000` 时是 `LAZY-CONTENT-1000`。它同样会改变截图，所以带滚动的 `dump=screenshot` 拍到的是页面的
 那一段。
 
-它作为引擎自身"抓取前求值"的一部分执行，因此与 `eval` 可组合：**先滚动，表达式再读取页面，并且仍然返回
-它自己的值**。
+`scroll` 是副作用，因此既可组合也可单独使用：
+
+```
+moli_fetch url=... dump=markdown scroll=600            # 先滚动，再 dump 页面
+moli_fetch url=... eval="document.title" scroll=600    # 先滚动，再取一个值
+moli_fetch url=... scroll=600                          # 只滚动，你仍然拿到页面
+```
+
+**最后一种写法值得单独说明，因为它曾经是坏的。** 滚动在引擎自身的"抓取前求值"里执行，而在没有 `dump` 时，
+引擎打印的就是这个求值的返回值——所以早期版本返回滚动位置，导致这一调用回的是 `600` 而不是页面，而**同样的
+调用不加 `scroll` 会返回 1989 个字符的 HTML**。现在滚动不报告任何东西，它只是发生。
+
+### `eval` 与 `dump` 同用 —— 表达式值会被丢弃
+
+这是引擎写明并有意的行为，予以保留——**用表达式在抓取前改变页面**是真实用法。不能接受的是它**看起来像一个
+干净答案**：`eval='JSON.stringify({probe:1})'` 配 `dump=markdown` 会返回 900 个字符的 Markdown、报
+`ok: true`、什么都不说。现在结果会带 `evalDiscarded: true` 和说明，而且渲染输出**把警告放在最前面**，不会
+被正文埋掉。
+
+要拿表达式的值，就只传 `eval`、不要传 `dump`。
 
 ### `failOnHttpError` —— 别再把错误页当正文读
 
@@ -426,11 +468,15 @@ profile。无论生效的是哪个代理，loopback 地址一律绕过它。
 - `scroll-verify.mjs` 在无引擎时校验表达式构造（像素值、负数、`top`、`bottom`、无效输入被拒、调用方的 `eval`
   值被保留），有引擎时抓取一个"滚动处理器填充槽位"的页面，断言带 `scroll` 时内容出现、不带时只有占位符——
   断言的是**输出**的性质，而不是内部调用。
+- `selector-verify.mjs` 覆盖"按容器取值"最容易出现的两个静默错答案：选择器无匹配时报错而不是空内容、匹配多个
+  元素时报告数量并拼接。它还断言选择器是**作为数据被引号包裹**而不是拼进表达式、`selector` 与 `dump`/`eval`
+  同传会被拒绝（而不是静默忽略其中一个）、以及它能与 `scroll` 组合。
 - `http-verify.mjs` 直接断言"参数 → 引擎选项"的映射，因为**参数没送到引擎和功能不生效，从外面看是一样的**。
   随后抓一个 404，验证 `failOnHttpError` 会报告失败同时保留响应体、健康页面不受影响、以及错误页的截图仍然被
-  写为合法 PNG 而不是被当文本解码。端到端部分需要一个真实服务器的 HTTP 错误：**本沙箱内无法访问 loopback**
-  ——`curl.exe` 连 `127.0.0.1` 会超时，而 Node 宿主进程可以——所以它用 `example.com` 下的一个路径，网络不可用
-  时跳过。
+  写为合法 PNG 而不是被当文本解码。它还覆盖那两个"静默给错答案"的情形：`eval` 配 `dump` 会带
+  `evalDiscarded` 标记且警告渲染在最前，`scroll` 单独用返回的是文档而不是滚动偏移。端到端部分需要一个真实
+  服务器的 HTTP 错误：**本沙箱内无法访问 loopback**——`curl.exe` 连 `127.0.0.1` 会超时，而 Node 宿主进程
+  可以——所以它用 `example.com` 下的一个路径，网络不可用时跳过。
 
 ### 测试前置条件
 

package/index.js

@@ -94,12 +94,16 @@ const FETCH_PARAMETERS = {
     dump: {
       type: 'string',
       enum: ['html', 'markdown', 'json', 'semantic_tree', 'semantic_tree_text', 'screenshot', 'screenshot_full', 'pdf'],
-      description: 'Output format. Omit for rendered HTML. `markdown` and `semantic_tree_text` are the token-efficient choices for reading a page; `json` carries status and final_url; screenshot/pdf need writeTo.',
+      description: 'Output format. Omit for rendered HTML. `markdown` is the cheapest way to read a page. `semantic_tree_text` is for locating things by structure (role, name, backend id), not for saving tokens: its size follows the page\'s node density and it is often larger than markdown — measured at 1.8x on a node-dense page — so prefer it only when you need the structure. `json` carries status and final_url; screenshot/pdf need writeTo.',
     },
     writeTo: {
       type: 'string',
       description: 'Absolute path to save the output. Required for screenshot/pdf; optional for text dumps larger than maxChars.',
     },
+    selector: {
+      type: 'string',
+      description: 'Return the text of the elements this CSS selector matches instead of the whole page. This is the cheap way to read one container out of a noisy listing page: the cards on a feed measured 1,829 characters against 95,605 for the same page as markdown. All matches are joined with newlines and the result reports how many there were; matching nothing is an error, not empty content, because the engine cannot distinguish an empty selection from a page with no text. Not compatible with `dump` or `eval` — one of them could only be ignored.',
+    },
     eval: {
       type: 'string',
       description: 'JavaScript expression evaluated once the page is ready; its value is returned as text or JSON instead of the page. Combining it with `dump` does NOT return both: the engine discards the expression value and dumps the resulting page state instead (its own documented semantics). Use `eval` alone to read a value, or `dump` alone to read the page.',
@@ -174,6 +178,9 @@ const FETCH_OUTPUT_SCHEMA = {
     empty: { type: 'boolean' },
     omitted: { type: 'integer' },
     evalFailed: { type: 'boolean' },
+    evalDiscarded: { type: 'boolean' },
+    selector: { type: 'string' },
+    matched: { type: 'integer' },
     truncated: { type: 'boolean' },
     error: { type: 'string' },
     hint: { type: 'string' },
@@ -226,13 +233,18 @@ function renderFetch(_args, value) {
     if (value.unreachable === true) lines.push('Cause: the host did not answer; a local forward proxy is the usual fix on this network.');
     else if (value.possiblyUnreachable === true) lines.push('Cause: the host did not answer in time; it may be blocked, or the page may simply be slow.');
     if (typeof value.hint === 'string' && value.hint !== '') lines.push(`Next: ${value.hint}`);
-    // An HTTP error keeps its body under `failOnHttpError`. Reporting the failure
+     // An HTTP error keeps its body under `failOnHttpError`. Reporting the failure
     // without the body would throw away the error page, which is the part worth
-    // reading -- and for a binary dump the body is the file that was written.
-    if (value.kind === 'binary' && typeof value.path === 'string') {
+    // reading -- and for a binary dump the body is the file that was written. A
+    // selector failure is different: there is no server body to show, and the
+    // message already says what did not match.
+    if (value.httpError === true && value.kind === 'binary' && typeof value.path === 'string') {
       lines.push(`The error page was still written to ${value.path} (${String(value.bytes)} bytes).`);
-    } else if (typeof value.content === 'string' && value.content !== '') {
+    } else if (value.httpError === true && typeof value.content === 'string' && value.content !== '') {
       lines.push('', 'The server\'s response body:', '', value.content);
+    } else if (typeof value.selector === 'string') {
+      lines.push(`Selector: ${JSON.stringify(value.selector)}`
+        + (typeof value.matched === 'number' ? ` (matched ${String(value.matched)})` : ''));
     }
     return [{ type: 'text', text: lines.join('\n') }];
   }
@@ -243,6 +255,18 @@ function renderFetch(_args, value) {
     }];
   }
   const parts = [];
+  // A discarded `eval` value is the one case where the output looks like a clean
+  // answer to a question that was never answered, so the warning goes first rather
+  // than after the body, where a 900-character page would bury it.
+  if (value.evalDiscarded === true) {
+    parts.push('Note: the `eval` expression was dropped because `dump` was given too — the engine discards the expression value in that combination. What follows is the page, not the expression.');
+  }
+  // A selector answer is a list, so say how many elements produced it: "48 matched,
+  // 34 had text" is the difference between a complete read and a partial one, and it
+  // is the only signal the caller has that the selector was too broad or too narrow.
+  if (typeof value.selector === 'string' && typeof value.matched === 'number') {
+    parts.push(`Selector ${JSON.stringify(value.selector)} matched ${String(value.matched)} element(s).`);
+  }
   if (typeof value.note === 'string' && value.note !== '') parts.push(value.note);
   parts.push(String(value.content ?? ''));
   return [{ type: 'text', text: parts.join('\n\n') }];

package/lib/moli.js

@@ -44,6 +44,44 @@ const SCROLL_TOKENS = {
   bottom: 'document.documentElement.scrollHeight',
 };
 
+/**
+ * Build the expression that returns the text of the elements a CSS selector matches.
+ *
+ * This exists because reading one container should not cost the whole page: on a
+ * node-dense listing page the full markdown dump measured 95,605 characters while
+ * the same page's video cards came to 1,829. `--eval` can already do this, but it
+ * requires writing the JavaScript; a selector is the same idea with no syntax to get
+ * wrong, which is what a model that is not fluent in the DOM needs.
+ *
+ * It works within one navigation -- the value is returned by the engine's own
+ * evaluation, so the "page is gone by the time the result is assembled" limitation
+ * does not apply.
+ *
+ * The result is prefixed with a machine-readable count, because the engine prints an
+ * empty string for an expression that yields `""`, and an empty selection is
+ * otherwise indistinguishable from a page with no text. A selector that matches
+ * nothing is reported as a failure rather than as empty content: the caller picked a
+ * selector that is not on the page, and telling them so is the whole point.
+ *
+ * @param selector - a CSS selector.
+ * @returns a JavaScript expression, or undefined when no selector was given.
+ */
+export function selectorScript(selector) {
+  if (typeof selector !== 'string' || selector.trim() === '') return undefined;
+  // JSON.stringify quotes the selector safely for embedding; a selector is data, not
+  // code, and must never be spliced into the expression raw.
+  const quoted = JSON.stringify(selector);
+  return `(() => {
+    const nodes = [...document.querySelectorAll(${quoted})];
+    const texts = nodes.map(node => (node.innerText ?? node.textContent ?? '').trim()).filter(text => text !== '');
+    return '[dsh-moli:selector]' + JSON.stringify({
+      matched: nodes.length,
+      withText: texts.length,
+      joined: texts.join('\\n'),
+    });
+  })()`;
+}
+
 /**
  * Build the expression that scrolls the page, to be run by the engine's own
  * `--eval` before the dump.
@@ -56,6 +94,14 @@ const SCROLL_TOKENS = {
  * content that "below the fold" already contains; it is about triggering the
  * handler, the intersection observer, or the lazy image that only runs on a scroll.
  *
+ * **The expression must not return the scroll position.** Without `--dump` the
+ * engine prints whatever `--eval` evaluates to, so returning `String(window.scrollY)`
+ * here replaced the page with the number `600`: `moli_fetch url=... scroll=600`
+ * answered `600`, while the identical call without `scroll` returned the document's
+ * HTML. The scroll is a side effect; the value it wants to report is recorded on
+ * `window` instead, where a later read can pick it up without changing what the
+ * engine prints.
+ *
  * @param scroll - pixels down (negative scrolls up), or `top` / `bottom`.
  * @returns a JavaScript expression, or undefined when there is nothing to do.
  */
@@ -74,26 +120,69 @@ export function scrollScript(scroll) {
     return undefined;
   }
   // Dispatch a scroll event as well as moving: `window.scrollTo` updates the
-  // position, but a page listening for the event is the reason this exists.
-  return `(() => { window.scrollTo(0, ${target}); window.dispatchEvent(new Event('scroll')); return String(window.scrollY); })()`;
+  // position, but a page listening for the event is the reason this exists. The
+  // height is captured on both sides of the move so a caller can tell whether the
+  // page grew -- which is the one signal that says lazy loading actually happened.
+  return `(() => {
+    const before = document.body === null ? 0 : document.body.scrollHeight;
+    window.scrollTo(0, ${target});
+    window.dispatchEvent(new Event('scroll'));
+    window.__dshMoliScroll = {
+      requested: ${target},
+      y: window.scrollY,
+      heightBefore: before,
+      heightAfter: document.body === null ? 0 : document.body.scrollHeight,
+    };
+  })()`;
 }
 
 /**
- * Combine the caller's `eval` with a scroll, if one was asked for.
+ * Build the one expression the engine will run from `scroll`, `selector` and `eval`.
+ *
+ * The engine accepts a single `--eval`, so everything that has to happen before the
+ * page is captured is composed here, in the order the caller expects: scroll first,
+ * then read (a selector or the caller's expression).
  *
- * The two have to share one expression because the engine accepts a single
- * `--eval`. The scroll goes first so the page is in its final state before the
- * caller's expression reads it, and the caller's value still becomes the result.
+ * What gets returned depends on whether anything else will produce the output, and
+ * getting this wrong breaks the feature in one direction or the other:
  *
- * @returns the expression to pass, or undefined when neither was given.
+ * - **A `dump` was requested.** The dump produces the output, so the expression is
+ *   there only for its side effects and its value is discarded by the engine anyway.
+ *   It must still be passed, or the scroll never runs.
+ * - **No `dump`.** The expression's value *is* the output, whether it is a selector
+ *   or the caller's own expression.
+ * - **No `dump`, no selector, no caller expression, only `scroll`.** The engine
+ *   prints whatever `--eval` evaluates to, so passing the scroll expression here
+ *   would replace the page with the scroll's return value. `undefined` is returned
+ *   instead, leaving the engine's default output -- the serialized document --
+ *   intact. This is the case that shipped broken: `moli_fetch url=... scroll=600`
+ *   answered `600`.
+ *
+ * @param evalExpression - the caller's expression, if any.
+ * @param scroll - the caller's `scroll` value, if any.
+ * @param hasDump - whether the caller also asked for a dump.
+ * @param selector - the caller's CSS selector, if any.
+ * @returns the expression to pass, or undefined to let the engine decide.
  */
-export function combineEval(evalExpression, scroll) {
+export function combineEval(evalExpression, scroll, hasDump = false, selector = undefined) {
   const move = scrollScript(scroll);
-  if (move === undefined) return evalExpression;
-  if (evalExpression === undefined || evalExpression === '') return move;
-  // The caller's expression is kept last and wrapped so its value is the one the
-  // engine reports. Losing it would contradict the documented `eval` behaviour.
-  return `${move}; (() => (${evalExpression}))()`;
+  const read = selectorScript(selector);
+  const caller = evalExpression === undefined || evalExpression === '' ? undefined : evalExpression;
+
+  // A selector is a read, so it replaces the caller's expression rather than being
+  // chained with it; `buildArgs` rejects the two together, so only one is ever set.
+  // The selector script is already a call expression; a caller's expression has to be
+  // wrapped so its value is what the engine reports.
+  const body = read !== undefined ? { code: read, wrapped: true } : (caller === undefined ? undefined : { code: caller, wrapped: false });
+
+  if (move === undefined) return body === undefined ? undefined : body.code;
+  if (body === undefined) {
+    // No read at all: keep the scroll only when a dump will produce the output.
+    return hasDump ? move : undefined;
+  }
+  // The read goes last so its value is the one the engine reports; losing it would
+  // contradict the documented `eval` behaviour.
+  return `${move}; ${body.wrapped ? body.code : `(() => (${body.code}))()`}`;
 }
 
 /**
@@ -332,9 +421,10 @@ export function buildArgs(args) {
   // Screenshots and PDFs silently produce nothing without the layout renderer.
   if (needsLayout) argv.push('--layout');
   if (args.scrollbars === true) argv.push('--scrollbars');
-  // `scroll` rides along in the same expression: the engine takes a single `--eval`,
-  // and the scroll has to happen before the page is captured.
-  const evaluation = combineEval(args.eval, args.scroll);
+  // `scroll` and `selector` ride along in the same expression: the engine takes a
+  // single `--eval`. `hasDump` matters -- see combineEval -- because with a dump the
+  // expression exists only for its side effect, and without one it becomes the output.
+  const evaluation = combineEval(args.eval, args.scroll, args.dump !== undefined, args.selector);
   if (evaluation !== undefined) argv.push('--eval', evaluation);
   if (args.wait !== undefined && args.wait !== '') argv.push('--wait', args.wait);
   if (args.waitSelector !== undefined && args.waitSelector !== '') argv.push('--wait-selector', args.waitSelector);
@@ -378,6 +468,30 @@ export function runFetch(options) {
   const args = options.insecureTls === true && options.args.insecureTls === undefined
     ? { ...options.args, insecureTls: true }
     : options.args;
+  // `selector` replaces the whole-page output, so combining it with either reader is a
+  // call that cannot do what it says: one of the two would be silently ignored. That
+  // is the failure mode this plugin keeps having to fix, so it is refused up front and
+  // as a structured result, the same way a binary dump with no writeTo is.
+  if (typeof args.selector === 'string' && args.selector.trim() !== '') {
+    if (args.dump !== undefined) {
+      return {
+        ok: false,
+        url: args.url,
+        selector: args.selector,
+        error: '`selector` and `dump` cannot be combined: a selector returns one container\'s text and a dump returns the whole page, so one of them could only be ignored',
+        hint: 'Use `selector` to read part of the page, or `dump` to read all of it.',
+      };
+    }
+    if (args.eval !== undefined && args.eval !== '') {
+      return {
+        ok: false,
+        url: args.url,
+        selector: args.selector,
+        error: '`selector` and `eval` cannot be combined: only one expression value can be returned',
+        hint: 'Put the extra work in `eval` and drop `selector`, or keep `selector` and read the text it returns.',
+      };
+    }
+  }
   const argv = buildArgs(args);
   const timeoutMs = args.timeoutMs ?? 30000;
   const isBinary = BINARY_DUMPS.has(args.dump);
@@ -561,6 +675,64 @@ export function runFetch(options) {
   }
 
   const text = outcome.stdout.toString('utf8');
+  // A selector result comes back as our own sentinel, because an empty selection and
+  // a page with no text are both an empty string from the engine -- verified: an
+  // expression returning `""` exits 0 with an empty line. Reporting "matched
+  // nothing" is the entire value of asking by selector, so it must not be silent.
+  if (typeof args.selector === 'string' && args.selector.trim() !== '') {
+    const payload = parseSelectorResult(text);
+    if (payload === undefined) {
+      return {
+        ok: false,
+        url: args.url,
+        selector: args.selector,
+        error: `the selector result could not be read: the engine returned ${JSON.stringify(text.slice(0, 120))}`,
+        hint: 'The page may not have finished rendering. Try waitSelector, or wait for the content with waitResponseUrl.',
+      };
+    }
+    if (payload.matched === 0) {
+      return {
+        ok: false,
+        url: args.url,
+        selector: args.selector,
+        matched: 0,
+        error: `no element matches ${JSON.stringify(args.selector)}`,
+        hint: 'The selector found nothing on this page. Check the spelling, wait for the content to arrive (`waitSelector`, `waitResponseUrl`), or use `dump` to see what the page actually contains.',
+      };
+    }
+    if (payload.withText === 0) {
+      return {
+        ok: false,
+        url: args.url,
+        selector: args.selector,
+        matched: payload.matched,
+        error: `${String(payload.matched)} element(s) match ${JSON.stringify(args.selector)} but none of them has any text`,
+        hint: 'The elements are probably images, icons or empty containers. Use `eval` if you need their attributes rather than their text.',
+      };
+    }
+    return {
+      ok: true,
+      url: args.url,
+      kind: 'text',
+      selector: args.selector,
+      content: payload.joined,
+      chars: payload.joined.length,
+      matched: payload.matched,
+      ...(payload.matched > payload.withText
+        ? { note: `${String(payload.matched - payload.withText)} of the ${String(payload.matched)} matched elements had no text and were left out.` }
+        : {}),
+    };
+  }
+  // `eval` together with `dump` is the engine's documented behaviour -- it discards
+  // the expression's value and dumps the page state the expression produced -- but
+  // it reads as a successful answer to a question that was never answered. The
+  // caller asked for `{probe:1}` and got 900 characters of Markdown. The discard is
+  // kept, because mutating a page before capturing it is a real use, so the result
+  // has to say what happened instead of looking clean.
+  const evalDiscarded = args.eval !== undefined && args.eval !== '' && args.dump !== undefined;
+  const evalNote = evalDiscarded
+    ? 'The `eval` expression produced no value here: `dump` was given too, and the engine discards the expression result in that combination. The output above is the page, not the expression. Run again with `eval` alone for the value, or keep both deliberately when the expression only changes the page before it is captured.'
+    : undefined;
   // A JSON dump is the only format that reports the HTTP status, so an error
   // page is otherwise indistinguishable from content. Surface it rather than
   // letting the model read a 404 body as if the fetch succeeded.
@@ -591,7 +763,10 @@ export function runFetch(options) {
       path: args.writeTo,
       chars: text.length,
       bytes,
-      note: 'Full output saved to file; read it for the complete text.',
+      note: evalNote === undefined
+        ? 'Full output saved to file; read it for the complete text.'
+        : `Full output saved to file; read it for the complete text. ${evalNote}`,
+      ...(evalDiscarded ? { evalDiscarded: true } : {}),
     };
   }
 
@@ -613,10 +788,21 @@ export function runFetch(options) {
     const headLen = Math.ceil(budget * 0.6);
     const tailLen = budget - headLen;
     omitted = text.length - budget;
-    const mark = `\n\n… [dsh-moli] ${String(omitted)} characters omitted here; the head and tail are kept. Pass writeTo to keep all ${String(text.length)}. …\n\n`;
+    // The marker inside the body is only a position signal: where the gap is and how
+    // big it is. Everything actionable -- the head/tail split, the total, the writeTo
+    // escape -- lives in the note, which is rendered once at the top. Both used to
+    // say the same thing, and on a 2,000-character budget the two copies cost 12.6%
+    // of everything the model received.
+    const mark = `\n\n… [dsh-moli] ${String(omitted)} characters omitted …\n\n`;
     content = text.slice(0, headLen) + mark + text.slice(text.length - tailLen);
-    note = `Output truncated: showing the first ${String(headLen)} and the last ${String(tailLen)} of ${String(text.length)} characters, with ${String(omitted)} omitted in the middle. Pass writeTo to keep all ${String(text.length)}.`;
+    note = `Truncated to fit maxChars: the first ${String(headLen)} and the last ${String(tailLen)} of ${String(text.length)} characters are shown, with ${String(omitted)} omitted in the middle. Pass writeTo to keep all ${String(text.length)}.`;
   }
+  // `eval` together with `dump` is the engine's documented behaviour -- it discards
+  // the expression's value and dumps the page state the expression produced -- but
+  // it reads as a successful answer to a question that was never answered. The
+  // caller asked for `{probe:1}` and got 900 characters of Markdown. The value is
+  // still discarded (that combination is genuinely useful for mutating a page before
+  // capturing it), so the result has to say so rather than look clean.
   return {
     ok: true,
     url: args.url,
@@ -626,10 +812,43 @@ export function runFetch(options) {
     chars: text.length,
     bytes,
     truncated,
-    ...(truncated ? { omitted, note } : {}),
+    ...(truncated ? { omitted } : {}),
+    ...(evalDiscarded ? { evalDiscarded: true } : {}),
+    ...(note === undefined && evalNote === undefined
+      ? {}
+      : { note: [note, evalNote].filter(part => part !== undefined).join(' ') }),
   };
 }
 
+/**
+ * Read the payload {@link selectorScript} prefixes onto its result.
+ *
+ * The engine prints the expression value verbatim, so the script adds a sentinel to
+ * tell a selector answer apart from page text. Anything without the sentinel is not
+ * a selector answer and comes back as undefined, which the caller reports as a
+ * failure rather than dressing it up as content.
+ *
+ * @param text - the engine's stdout.
+ * @returns `{ matched, withText, joined }`, or undefined.
+ */
+function parseSelectorResult(text) {
+  const marker = '[dsh-moli:selector]';
+  const at = String(text).indexOf(marker);
+  if (at < 0) return undefined;
+  try {
+    const raw = JSON.parse(String(text).slice(at + marker.length).trim());
+    if (raw === null || typeof raw !== 'object') return undefined;
+    if (typeof raw.matched !== 'number' || typeof raw.joined !== 'string') return undefined;
+    return {
+      matched: raw.matched,
+      withText: typeof raw.withText === 'number' ? raw.withText : 0,
+      joined: raw.joined,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Read the HTTP status out of the engine's stderr reason.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-moli",
-  "version": "1.1.15",
+  "version": "1.1.17",
   "type": "module",
   "description": "DeepSeek Harness tools for the local Moli headless browser: rendered fetches, markdown, semantic trees, screenshots, and PDFs.",
   "license": "MIT",