dsh-moli 1.1.16 → 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.
@@ -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,

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` 会带

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' },
@@ -227,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') }];
   }
@@ -250,6 +261,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}))()`}`;
 }
 
 /**
@@ -369,13 +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.
-  // `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 +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);
@@ -602,6 +675,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 +788,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 +820,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.17",
   "type": "module",
   "description": "DeepSeek Harness tools for the local Moli headless browser: rendered fetches, markdown, semantic trees, screenshots, and PDFs.",
   "license": "MIT",