dsh-moli 1.1.16 → 1.1.18

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.
@@ -489,6 +519,11 @@ 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,
@@ -542,47 +577,6 @@ On the versions themselves: npm allows a version to be unpublished only briefly
 individually, so 1.1.11 and 1.1.12 remain installable but are marked deprecated and point here.
 `npm install dsh-moli` resolves to 1.1.13.
 
-## Releasing
-
-Publishing goes through GitHub Actions' OIDC identity, so **no npm token exists to expire**:
-
-```bash
-npm version patch          # or minor / major
-git push && git tag v1.1.6 && git push origin v1.1.6
-```
-
-`.github/workflows/publish.yml` checks that the tag matches `package.json`, runs the offline suites,
-and publishes. One-time setup on npmjs.com: **package → Settings → Trusted Publisher → GitHub
-Actions**, with user `27painter`, repository `dsh-moli`, workflow filename `publish.yml`, and the
-`npm publish` action allowed.
-
-**Do not publish with a stored token.** This machine was configured with a classic token that bypasses
-2FA, and npm is retiring those; when it was revoked, the publish failed with
-
-```
-E404 Not Found - PUT https://registry.npmjs.org/dsh-moli
-     The requested resource 'dsh-moli@1.1.5' could not be found or you do not have permission
-```
-
-which reads as a missing package and is actually an authorisation failure. Run
-`node scripts/preflight-publish.mjs` before any local publish: it reports whether the credential can
-authenticate and names that misleading 404 when it cannot.
-
-### Deprecating a version: do it on the website
-
-Publishing is scripted; deprecating deliberately is not. Use the package's page on npmjs.com —
-**package → Settings → Deprecate** — and name the versions and the reason.
-
-`npm deprecate dsh-moli@1.1.11 "…"` produces the same misleading failure as above when the local
-credential is dead, and there is a second reason not to reach for a token here. npm restricted
-2FA-bypass granular tokens from package-management operations on 31 July 2026, so the kind of token
-that used to make `deprecate` scriptable is being withdrawn, while `publish` has a supported
-token-free path through OIDC. A release process that needs a token only for the rare act of
-deprecating is a process that will be broken the next time it is needed, which is exactly what
-happened with 1.1.11 and 1.1.12.
-
-The 1.0.0 and 1.0.1 deprecations were done this way, from the website.
-
 ## License
 
 MIT. See [LICENSE](LICENSE).

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 里的一切**。它拿不到的是**尚未存在的内容**：首次
@@ -444,6 +468,9 @@ profile。无论生效的是哪个代理，loopback 地址一律绕过它。
 - `scroll-verify.mjs` 在无引擎时校验表达式构造（像素值、负数、`top`、`bottom`、无效输入被拒、调用方的 `eval`
   值被保留），有引擎时抓取一个"滚动处理器填充槽位"的页面，断言带 `scroll` 时内容出现、不带时只有占位符——
   断言的是**输出**的性质，而不是内部调用。
+- `selector-verify.mjs` 覆盖"按容器取值"最容易出现的两个静默错答案：选择器无匹配时报错而不是空内容、匹配多个
+  元素时报告数量并拼接。它还断言选择器是**作为数据被引号包裹**而不是拼进表达式、`selector` 与 `dump`/`eval`
+  同传会被拒绝（而不是静默忽略其中一个）、以及它能与 `scroll` 组合。
 - `http-verify.mjs` 直接断言"参数 → 引擎选项"的映射，因为**参数没送到引擎和功能不生效，从外面看是一样的**。
   随后抓一个 404，验证 `failOnHttpError` 会报告失败同时保留响应体、健康页面不受影响、以及错误页的截图仍然被
   写为合法 PNG 而不是被当文本解码。它还覆盖那两个"静默给错答案"的情形：`eval` 配 `dump` 会带
@@ -494,43 +521,6 @@ Chromium 后端、原始 CDP 逃生舱、按调用的 CDP 端点、持久化浏
 关于这两个版本本身：npm 只允许在很短的时间窗口内撤回发布，且无法单独撤回某一个版本，因此 1.1.11 与
 1.1.12 仍然可安装，但已被标记为废弃并指向这里。`npm install dsh-moli` 会安装到 1.1.13。
 
-## 发布
-
-发布走 GitHub Actions 的 OIDC 身份，**本机不存任何 npm token，因此没有会失效的凭据**：
-
-```bash
-npm version patch          # 或 minor / major
-git push && git tag v1.1.6 && git push origin v1.1.6
-```
-
-`.github/workflows/publish.yml` 会先校验 tag 与 `package.json` 版本一致、跑离线测试套件，然后发布。
-npmjs.com 上需要一次性配置：**package → Settings → Trusted Publisher → GitHub Actions**，用户
-`27painter`、仓库 `dsh-moli`、workflow 文件名 `publish.yml`，并允许 `npm publish` 动作。
-
-**不要再用本机存储的 token 发布。** 这台机器原先配的是一个绕过 2FA 的 classic token，npm 正在淘汰这类
-token；它被吊销后，发布会报：
-
-```
-E404 Not Found - PUT https://registry.npmjs.org/dsh-moli
-     The requested resource 'dsh-moli@1.1.5' could not be found or you do not have permission
-```
-
-**这看起来像"包不存在"，实际是认证失败。** 任何本地发布之前先跑
-`node scripts/preflight-publish.mjs`：它会告诉你凭据能否认证，不能时明确点出这个误导性的 404。
-
-### 废弃某个版本：去网站操作，别用命令行
-
-发布是脚本化的，**废弃则刻意不做成脚本**。用 npmjs.com 上的包页面——**package → Settings →
-Deprecate**——选版本、写理由。
-
-`npm deprecate dsh-moli@1.1.11 "…"` 在本机凭据失效时会给出上面那个同样误导的失败，而且这里还有第二个
-理由不要依赖 token：npm 在 **2026 年 7 月 31 日**起禁止 2FA-bypass 类型的 granular token 执行**包管理**
-操作，也就是说"以前能让 `deprecate` 脚本化"的那类凭据正在被取消；而 `publish` 有受支持的、免 token 的
-OIDC 路径。**一个只在"偶尔废弃版本"时才需要 token 的流程，注定在下次需要它时是坏的**——1.1.11 与 1.1.12
-遇到的正是这种情况。
-
-1.0.0 与 1.0.1 的废弃就是通过网站完成的。
-
 ## 许可
 
 MIT，见 [LICENSE](LICENSE)。

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.',
@@ -175,6 +179,8 @@ const FETCH_OUTPUT_SCHEMA = {
     omitted: { type: 'integer' },
     evalFailed: { type: 'boolean' },
     evalDiscarded: { type: 'boolean' },
+    selector: { type: 'string' },
+    matched: { type: 'integer' },
     truncated: { type: 'boolean' },
     error: { type: 'string' },
     hint: { type: 'string' },
@@ -183,6 +189,7 @@ const FETCH_OUTPUT_SCHEMA = {
     sandboxTlsBlock: { type: 'boolean' },
     unreachable: { type: 'boolean' },
     possiblyUnreachable: { type: 'boolean' },
+    conditionTimedOut: { type: 'boolean' },
     note: { type: 'string' },
   },
 };
@@ -226,14 +233,23 @@ function renderFetch(_args, value) {
     if (value.sandboxTlsBlock === true) lines.push('Cause: the DSH sandbox blocks Schannel client credentials (HTTPS only).');
     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.');
+    // A wait that never resolved is the one failure that is definitely not the
+    // network: the page arrived and was parsed. Saying so up front keeps the caller
+    // from spending their time on a proxy that was never the problem.
+    else if (value.conditionTimedOut === true) lines.push('Cause: the page loaded, but the wait condition never became true — this is not a network problem.');
     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') }];
   }
@@ -250,6 +266,12 @@ function renderFetch(_args, value) {
   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.
@@ -99,38 +137,52 @@ export function scrollScript(scroll) {
 }
 
 /**
- * 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 two share one expression because the engine accepts a single `--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).
  *
- * 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:
+ * 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:
  *
  * - **A `dump` was requested.** The dump produces the output, so the expression is
- *   there only to scroll first and its value is discarded by the engine anyway.
+ *   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`, and the caller gave an expression.** The expression value *is* the
- *   output, and the scroll runs as part of it.
- * - **No `dump`, no caller expression.** 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`.
+ * - **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, hasDump = false) {
+export function combineEval(evalExpression, scroll, hasDump = false, selector = undefined) {
   const move = scrollScript(scroll);
+  const read = selectorScript(selector);
   const caller = evalExpression === undefined || evalExpression === '' ? undefined : evalExpression;
-  if (move === undefined) return caller;
-  // The caller's expression goes last and is wrapped so its value is the one the
-  // engine reports; losing it would contradict the documented `eval` behaviour.
-  if (caller !== undefined) return `${move}; (() => (${caller}))()`;
-  // No caller expression: keep the scroll only when a dump will produce the output.
-  return hasDump ? move : undefined;
+
+  // 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}))()`}`;
 }
 
 /**
@@ -246,22 +298,44 @@ export function isSandboxTlsFailure(message) {
 }
 
 /**
- * Classify a transport failure as "the host never answered".
+ * Classify a transport failure: did the host never answer, or did a wait condition
+ * simply never become true?
  *
  * A blocked host fails at connect time (`Failed to connect`, reset, refused) or,
  * when the socket never opens, as a readiness timeout with nothing to show. A
  * readiness timeout can also mean a genuinely slow page, so that weaker case is
  * reported separately as {@link possiblyUnreachable}.
  *
+ * **But not every readiness timeout is about the network.** The engine reports the
+ * condition it was waiting for, and three of them mean the page was already there:
+ *
+ *     ... while waiting for a selector
+ *     ... while waiting for a script to become truthy
+ *     ... while waiting for a subresource response
+ *
+ * In those cases the document was fetched and parsed; what did not happen is the
+ * selector appearing, the script becoming true, or the matching response arriving.
+ * Telling the caller to retry or configure a proxy then sends them to look at their
+ * network for a problem that is in their selector -- measured: `waitSelector` on an
+ * element that is not on the page used to report "the host did not answer in time".
+ * A timeout "while waiting for response headers" is the opposite case and stays
+ * classified as possibly unreachable, because that one really is the server.
+ *
  * @param message - condensed stderr text.
- * @returns whether a connect-time failure was reported, and whether any timeout was.
+ * @returns `unreachable` (connect-time), `possiblyUnreachable` (network timeout), and
+ *   `conditionTimedOut` (a wait that the page itself never satisfied).
  */
 export function isUnreachableFailure(message) {
   const text = String(message);
   const connectFailure = /Failed to connect|Could not connect|Connection was reset|Connection refused/iu.test(text);
+  const anyTimeout = /Timeout was reached|readiness timed out/iu.test(text);
+  const conditionTimedOut = /readiness timed out .*?while waiting for (?:a selector|a script|a subresource response)/iu.test(text);
   return {
     unreachable: connectFailure,
-    possiblyUnreachable: connectFailure || /Timeout was reached|readiness timed out/iu.test(text),
+    // A condition timeout is not evidence about the network: the page arrived. Only
+    // the remaining timeouts are worth mentioning as a reachability possibility.
+    possiblyUnreachable: connectFailure || (anyTimeout && !conditionTimedOut),
+    conditionTimedOut,
   };
 }
 
@@ -369,13 +443,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.
-  // `scroll` rides along in the same expression: the engine takes a single `--eval`,
-  // and the scroll has to happen before the page is captured. `hasDump` matters --
-  // see combineEval -- because with a dump the expression exists only for its side
-  // effect, and without one it would become the output.
-  const evaluation = combineEval(args.eval, args.scroll, args.dump !== undefined);
+  // `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);
@@ -419,6 +490,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);
@@ -536,7 +631,7 @@ export function runFetch(options) {
     // the socket never opens, as a readiness timeout with nothing to show. A
     // readiness timeout can also mean a genuinely slow page, so it is reported
     // as *possibly* unreachable and worded as a suggestion rather than a verdict.
-    const { unreachable, possiblyUnreachable } = isUnreachableFailure(stderr);
+    const { unreachable, possiblyUnreachable, conditionTimedOut } = isUnreachableFailure(stderr);
     // The engine reports a thrown expression as
     //   `Reason: JavaScript evaluation failed: TypeError: ... at <anonymous>:1:6`
     // which is a bug in the call, not an install or network problem. Falling
@@ -547,15 +642,27 @@ export function runFetch(options) {
     // status 1" leaves the caller to guess whether an image exists; the useful fact
     // is that it does not, and that a text dump would have captured this page.
     const binaryFailure = isBinary && httpStatusFrom(stderr) !== undefined;
+    // Name the wait that never resolved. "Retry or set a proxy" is actively
+    // misleading here: the page arrived, so the network is fine, and the caller
+    // would spend their time on the one part of the setup that is working.
+    const conditionHint = args.waitSelector !== undefined
+      ? `The selector ${JSON.stringify(args.waitSelector)} never matched. The page loaded, so this is not a network problem: check the spelling, and confirm the element is there with \`selector\` (it reports the match count, where a wait only times out) or \`dump\`.`
+      : args.waitScript !== undefined
+        ? 'The wait expression never became truthy. The page loaded, so this is not a network problem: check the expression against the page with `eval`, and remember it is polled rather than evaluated once.'
+        : (args.waitResponseUrl !== undefined || args.waitResponseJson !== undefined)
+          ? 'No response matching that condition arrived. The page loaded, so this is not a network problem: the request may never be made, or its payload may differ from what you matched on. Use `dump` with a short timeout to see what the page does, or an `eval` that inspects the fetch.'
+          : 'The wait condition never became true. The page loaded, so this is not a network problem: check the condition.';
     const hint = evalFailure
       ? 'The eval expression threw. Check that the page has reached the state you expect (`wait` or `waitSelector`), that the selector matches an element, and that the expression is valid JavaScript. The engine error names the type and position.'
       : binaryFailure
         ? 'The engine could not render this page, so no file was written. An HTTP error still produces a body for a text dump (markdown, html or json), so ask for one of those if you need to see what the server returned.'
         : sandboxTls
           ? 'The DSH file sandbox blocks Schannel client credentials, so moli cannot do TLS at low integrity. Retry the same call with sandbox_permissions "danger-full-access" (with a justification), use an http:// URL, or pass proxy to reach a local forward proxy.'
-          : possiblyUnreachable
-            ? 'The host did not answer in time. Reachability to some hosts varies on this network, so retrying may succeed; if a local forward proxy is available, setting the plugin config field `proxy` is the other option. A certificate problem would report a schannel error instead of a timeout.'
-            : 'Run moli_probe to confirm the install, then retry; use waitSelector or eval for a page that renders late.';
+          : conditionTimedOut
+            ? conditionHint
+            : possiblyUnreachable
+              ? 'The host did not answer in time. Reachability to some hosts varies on this network, so retrying may succeed; if a local forward proxy is available, setting the plugin config field `proxy` is the other option. A certificate problem would report a schannel error instead of a timeout.'
+              : 'Run moli_probe to confirm the install, then retry; use waitSelector or eval for a page that renders late.';
     const failureStatus = httpStatusFrom(stderr);
     return {
       ok: false,
@@ -565,6 +672,7 @@ export function runFetch(options) {
       sandboxTlsBlock: sandboxTls,
       unreachable,
       possiblyUnreachable,
+      ...(conditionTimedOut ? { conditionTimedOut: true } : {}),
       ...(evalFailure ? { evalFailed: true } : {}),
       hint,
     };
@@ -602,6 +710,54 @@ 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
@@ -667,9 +823,14 @@ 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
@@ -694,6 +855,35 @@ export function runFetch(options) {
   };
 }
 
+/**
+ * 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.16",
+  "version": "1.1.18",
   "type": "module",
   "description": "DeepSeek Harness tools for the local Moli headless browser: rendered fetches, markdown, semantic trees, screenshots, and PDFs.",
   "license": "MIT",