@poe-platform/safe-bash 0.1.812 → 0.1.813

package/dist/safe-bash-command-html-to-markdown/input.js

@@ -1,10 +1,11 @@
 import {
   Inputs
-} from "../safe-bash/command-chunks/chunk-YS25EI54.js";
-import "../safe-bash/command-chunks/chunk-N4R2SHSS.js";
-import "../safe-bash/command-chunks/chunk-QUM3SYAJ.js";
-import "../safe-bash/command-chunks/chunk-SPW4GW4Z.js";
-import "../safe-bash/command-chunks/chunk-AGLK7OJR.js";
+} from "../safe-bash/command-chunks/chunk-PCCFLPUQ.js";
+import "../safe-bash/command-chunks/chunk-CCZZVCHX.js";
+import "../safe-bash/command-chunks/chunk-SYSX46IV.js";
+import "../safe-bash/command-chunks/chunk-DFI7QF3M.js";
+import "../safe-bash/command-chunks/chunk-HDSIIQBS.js";
+import "../safe-bash/command-chunks/chunk-6ZHQB453.js";
 import "../safe-bash/command-chunks/chunk-65DS4IOB.js";
 export {
   Inputs

package/dist/safe-bash-command-html-to-markdown/options.js

@@ -3,7 +3,8 @@ import {
   argumentsFor,
   helpText,
   settings
-} from "../safe-bash/command-chunks/chunk-26VCZHLJ.js";
+} from "../safe-bash/command-chunks/chunk-PIOQBOEK.js";
+import "../safe-bash/command-chunks/chunk-6ZHQB453.js";
 import "../safe-bash/command-chunks/chunk-65DS4IOB.js";
 export {
   HtmlUsageError,

package/dist/safe-bash-command-html-to-markdown/parser.js

@@ -1,10 +1,11 @@
 import {
   Parser,
   blockTags
-} from "../safe-bash/command-chunks/chunk-N4R2SHSS.js";
-import "../safe-bash/command-chunks/chunk-QUM3SYAJ.js";
-import "../safe-bash/command-chunks/chunk-SPW4GW4Z.js";
-import "../safe-bash/command-chunks/chunk-AGLK7OJR.js";
+} from "../safe-bash/command-chunks/chunk-CCZZVCHX.js";
+import "../safe-bash/command-chunks/chunk-SYSX46IV.js";
+import "../safe-bash/command-chunks/chunk-DFI7QF3M.js";
+import "../safe-bash/command-chunks/chunk-HDSIIQBS.js";
+import "../safe-bash/command-chunks/chunk-6ZHQB453.js";
 import "../safe-bash/command-chunks/chunk-65DS4IOB.js";
 export {
   Parser,

package/dist/safe-bash-command-html-to-markdown/render.js

@@ -1,21 +1,22 @@
 import {
   blockTags
-} from "../safe-bash/command-chunks/chunk-N4R2SHSS.js";
+} from "../safe-bash/command-chunks/chunk-CCZZVCHX.js";
 import {
   destination,
   escapeText
-} from "../safe-bash/command-chunks/chunk-QUM3SYAJ.js";
+} from "../safe-bash/command-chunks/chunk-SYSX46IV.js";
 import {
   htmlSpace,
   normalizeText,
   trimText
-} from "../safe-bash/command-chunks/chunk-SPW4GW4Z.js";
+} from "../safe-bash/command-chunks/chunk-DFI7QF3M.js";
 import {
   Builder
-} from "../safe-bash/command-chunks/chunk-AGLK7OJR.js";
+} from "../safe-bash/command-chunks/chunk-HDSIIQBS.js";
+import "../safe-bash/command-chunks/chunk-6ZHQB453.js";
 import "../safe-bash/command-chunks/chunk-65DS4IOB.js";
 
-// packages/safe-bash-command-html-to-markdown/src/render.ts
+// packages/safe-bash-command-html-to-markdown/dist/render.js
 var format = (tag) => tag === "em" || tag === "i" ? "em" : tag === "strong" || tag === "b" ? "strong" : tag === "del" || tag === "s" ? "del" : void 0;
 var inlineAtoms = /* @__PURE__ */ new Set(["a", "img", "code", "br"]);
 var Renderer = class {

package/dist/safe-bash-command-html-to-markdown/text.js

@@ -2,8 +2,9 @@ import {
   htmlSpace,
   normalizeText,
   trimText
-} from "../safe-bash/command-chunks/chunk-SPW4GW4Z.js";
-import "../safe-bash/command-chunks/chunk-AGLK7OJR.js";
+} from "../safe-bash/command-chunks/chunk-DFI7QF3M.js";
+import "../safe-bash/command-chunks/chunk-HDSIIQBS.js";
+import "../safe-bash/command-chunks/chunk-6ZHQB453.js";
 import "../safe-bash/command-chunks/chunk-65DS4IOB.js";
 export {
   htmlSpace,

package/dist/safe-bash-command-htmlq/index.js

@@ -108,6 +108,9 @@ var HtmlBudget = class {
   }
 };
 
+// packages/safe-bash-command-htmlq/src/tree.ts
+import { yieldTurn } from "../safe-bash-contracts/yield.js";
+
 // packages/safe-bash-command-htmlq/src/entities.ts
 var entities_exports = {};
 __reExport(entities_exports, entities_star);
@@ -392,6 +395,186 @@ var HtmlTokenizer = class {
   }
 };
 
+// packages/safe-bash-command-htmlq/src/streaming-tokenizer.ts
+var StreamingHtmlTokenizer = class {
+  constructor(source, budget) {
+    this.budget = budget;
+    this.input = source[Symbol.asyncIterator]();
+  }
+  budget;
+  buffer = "";
+  ended = false;
+  input;
+  async peek(length = 1) {
+    while (!this.ended && this.buffer.length < length) {
+      const next = await this.input.next();
+      this.budget.check();
+      if (next.done) this.ended = true;
+      else this.buffer += next.value;
+    }
+    return this.buffer.slice(0, length);
+  }
+  async close() {
+    if (!this.ended) await this.input.return?.();
+  }
+  async next(raw, foreign = false) {
+    if (!await this.peek()) return void 0;
+    let frame = "";
+    const take = async (length = 1) => {
+      const value = await this.peek(length);
+      this.budget.bound("tokenBytes", (frame.length + value.length) * 2);
+      frame += value;
+      this.buffer = this.buffer.slice(value.length);
+    };
+    const until = async (delimiter2) => {
+      while (await this.peek()) {
+        if (await this.peek(delimiter2.length) === delimiter2) {
+          await take(delimiter2.length);
+          break;
+        }
+        await take();
+      }
+    };
+    if (raw) {
+      let scriptState = "data";
+      while (await this.peek()) {
+        let end = raw === "plaintext" ? this.buffer.length : this.buffer.indexOf("<");
+        if (end < 0) end = this.buffer.length;
+        if (raw === "script" && scriptState !== "data") {
+          const dash = this.buffer.indexOf("-");
+          if (dash >= 0) end = Math.min(end, dash);
+        }
+        if (end > 0) {
+          await take(end);
+          continue;
+        }
+        if (raw !== "plaintext") {
+          if (raw === "script") {
+            if (scriptState === "data" && await this.peek(4) === "<!--") {
+              scriptState = "escaped";
+              await take(4);
+              continue;
+            }
+            if (scriptState !== "data" && await this.peek(3) === "-->") {
+              scriptState = "data";
+              await take(3);
+              continue;
+            }
+            const opening = (0, entities_exports.asciiLower)(await this.peek(8));
+            if (scriptState === "escaped" && opening.startsWith("<script") && delimiter(opening[7])) {
+              scriptState = "double";
+              await take(7);
+              continue;
+            }
+            const closing = (0, entities_exports.asciiLower)(await this.peek(9));
+            if (scriptState === "double" && closing.startsWith("<\/script") && delimiter(closing[8])) {
+              scriptState = "escaped";
+              await take(8);
+              continue;
+            }
+          }
+          if (scriptState !== "double" && await this.peek(2) === "</") {
+            const closing = (0, entities_exports.asciiLower)(await this.peek(raw.length + 3));
+            if (closing.slice(2, 2 + raw.length) === raw && delimiter(closing[2 + raw.length])) break;
+          }
+        }
+        await take();
+      }
+      if (frame) return new HtmlTokenizer(frame, this.budget).next(raw, foreign);
+    }
+    if (await this.peek() !== "<") {
+      while (await this.peek() && this.buffer[0] !== "<") {
+        const end = this.buffer.indexOf("<");
+        await take(end < 0 ? this.buffer.length : end);
+      }
+    } else if (foreign && await this.peek(9) === "<![CDATA[") {
+      await take(9);
+      await until("]]>");
+    } else if (await this.peek(4) === "<!--") {
+      await take(4);
+      let state = "start";
+      while (await this.peek()) {
+        const c = await this.peek();
+        await take();
+        if (state === "start" || state === "startDash") {
+          if (c === ">") break;
+          state = c === "-" ? state === "start" ? "startDash" : "end" : "data";
+        } else if (state === "data") {
+          if (c === "-") state = "dash";
+        } else if (state === "dash") state = c === "-" ? "end" : "data";
+        else if (state === "end") {
+          if (c === ">") break;
+          if (c !== "-") state = c === "!" ? "bang" : "data";
+        } else {
+          if (c === ">") break;
+          state = c === "-" ? "dash" : "data";
+        }
+      }
+    } else if ((0, entities_exports.asciiLower)(await this.peek(9)) === "<!doctype") {
+      await take(9);
+      await until(">");
+    } else {
+      await take();
+      const closing = await this.peek() === "/";
+      if (closing) await take();
+      const first = await this.peek();
+      if (!asciiLetter(first)) {
+        if (closing || first === "!" || first === "?") await until(">");
+      } else {
+        while (await this.peek() && !delimiter(await this.peek())) await take();
+        let state = "before";
+        let quote = "";
+        while (await this.peek()) {
+          const c = await this.peek();
+          if (state === "quoted") {
+            await take();
+            if (c === quote) state = "before";
+            continue;
+          }
+          if (c === ">") {
+            await take();
+            break;
+          }
+          if (state === "before") {
+            await take();
+            if (!(0, entities_exports.htmlSpace)(c) && c !== "/") state = "name";
+          } else if (state === "name") {
+            if (c === "=") {
+              await take();
+              state = "value";
+            } else if ((0, entities_exports.htmlSpace)(c) || c === "/") state = "after";
+            else await take();
+          } else if (state === "after") {
+            if ((0, entities_exports.htmlSpace)(c)) await take();
+            else if (c === "=") {
+              await take();
+              state = "value";
+            } else state = "before";
+          } else if (state === "value") {
+            await take();
+            if (!(0, entities_exports.htmlSpace)(c)) {
+              if (c === '"' || c === "'") {
+                quote = c;
+                state = "quoted";
+              } else state = "unquoted";
+            }
+          } else {
+            await take();
+            if ((0, entities_exports.htmlSpace)(c)) state = "before";
+          }
+        }
+      }
+    }
+    return new HtmlTokenizer(frame, this.budget).next(void 0, foreign);
+  }
+};
+function delimiter(c) {
+  return c !== void 0 && ((0, entities_exports.htmlSpace)(c) || c === "/" || c === ">");
+}
+function asciiLetter(c) {
+  return c >= "A" && c <= "Z" || c >= "a" && c <= "z";
+}
+
 // packages/safe-bash-command-htmlq/src/tree.ts
 function allSpace(data) {
   for (const c of data) if (!(0, entities_exports.htmlSpace)(c)) return false;
@@ -514,6 +697,7 @@ function originalSource(node) {
     );
   if (owner.mutated)
     throw new HtmlError("E_MUTATED", "Original source does not represent the mutated tree");
+  if (owner.source === void 0) throw new HtmlError("E_UNSUPPORTED", "Original source was not retained");
   return owner.source;
 }
 function unlink(node) {
@@ -751,20 +935,79 @@ var svgAttributes = Object.fromEntries(
     "zoomAndPan"
   ].map((name) => [name.toLowerCase(), name])
 );
-async function parseHtml(source, options) {
+async function parseHtml(source, options, originalSource2 = "retain") {
+  const budget = new HtmlBudget(options);
+  const owner = { source: originalSource2 === "retain" ? "" : void 0, mutated: false };
+  async function* normalized() {
+    let first = true, carriage = false;
+    for await (const original of decodedHtml(source, options)) {
+      if (owner.source !== void 0) {
+        budget.charge("retainedBytes", original.length * 2);
+        owner.source += original;
+      }
+      let text = "";
+      for (const character of original) {
+        budget.charge("work", 1);
+        if (first) {
+          first = false;
+          if (character === "\uFEFF") continue;
+        }
+        if (carriage && character === "\n") {
+          carriage = false;
+          continue;
+        }
+        carriage = character === "\r";
+        text += carriage ? "\n" : character;
+      }
+      yield text;
+    }
+  }
+  const tokenizer = new StreamingHtmlTokenizer(normalized(), budget);
+  const tree = buildTree(owner, budget);
+  let step = tree.next();
+  let failure;
+  try {
+    while (!step.done) step = tree.next(await tokenizer.next(step.value.raw, step.value.foreign));
+  } catch (error) {
+    failure = { error };
+  }
+  try {
+    await tokenizer.close();
+  } catch (error) {
+    if (failure) throw new AggregateError([failure.error, error], "HTML input and cleanup failed");
+    throw error;
+  }
+  if (failure) throw failure.error;
+  return step.value;
+}
+async function* decodedHtml(source, options) {
   const budget = new HtmlBudget(options);
   const decoder = new TextDecoder("utf-8", { fatal: false, ignoreBOM: true });
-  let original = "";
   const iterator = source[Symbol.asyncIterator]();
-  let complete = false;
+  let complete = false, sinceYield = 0;
   let failed = false;
   let failure;
+  const closeInput = async () => {
+    if (!complete && iterator.return) {
+      try {
+        await iterator.return();
+      } catch (cleanup) {
+        if (failed) throw new AggregateError([failure, cleanup], "HTML input and cleanup failed");
+        throw cleanup;
+      }
+    }
+  };
   const abort = () => {
     throw new HtmlError("E_CANCELLED", "HTML invocation cancelled");
   };
   try {
     while (true) {
       budget.charge("work", 1);
+      if (++sinceYield >= 4096) {
+        await yieldTurn();
+        budget.check();
+        sinceYield = 0;
+      }
       let listener = () => {
       };
       const cancellation = new Promise((_, reject) => {
@@ -791,29 +1034,29 @@ async function parseHtml(source, options) {
       budget.charge("inputBytes", byteLength2);
       budget.charge("retainedBytes", byteLength2 * 2);
       budget.charge("work", byteLength2);
-      const text = decoder.decode(chunk, { stream: true });
-      budget.charge("decodedBytes", text.length * 2);
-      original += text;
+      for (let offset = 0; offset < byteLength2; offset += 4096) {
+        if (sinceYield >= 4096) {
+          await yieldTurn();
+          budget.check();
+          sinceYield = 0;
+        }
+        sinceYield += Math.min(4096, byteLength2 - offset);
+        const text = decoder.decode(Uint8Array.prototype.subarray.call(chunk, offset, Math.min(byteLength2, offset + 4096)), { stream: true });
+        budget.charge("decodedBytes", text.length * 2);
+        yield text;
+      }
     }
   } catch (error) {
     failed = true;
     failure = error;
-  }
-  if (!complete && iterator.return) {
-    try {
-      await iterator.return();
-    } catch (cleanup) {
-      if (failed)
-        throw new AggregateError([failure, cleanup], "HTML input and cleanup failed");
-      throw cleanup;
-    }
+  } finally {
+    await closeInput();
   }
   if (failed) throw failure;
   const tail = decoder.decode();
   budget.charge("decodedBytes", tail.length * 2);
   budget.charge("retainedBytes", tail.length * 2);
-  original += tail;
-  return parseHtmlSync(original, options, budget);
+  yield tail;
 }
 function parseHtmlSync(original, options, existingBudget) {
   const budget = existingBudget ?? new HtmlBudget(options);
@@ -832,7 +1075,13 @@ function parseHtmlSync(original, options, existingBudget) {
       } else normalized += original[i];
     }
   }
-  const owner = { source: original, mutated: false };
+  const tree = buildTree({ source: original, mutated: false }, budget);
+  const tokenizer = new HtmlTokenizer(normalized, budget);
+  let step = tree.next();
+  while (!step.done) step = tree.next(tokenizer.next(step.value.raw, step.value.foreign));
+  return step.value;
+}
+function* buildTree(owner, budget) {
   const make = (kind, name = "", data = "", namespace = "html") => {
     budget.charge("nodes", 1);
     budget.charge("retainedBytes", 128 + (name.length + data.length) * 2);
@@ -1035,12 +1284,11 @@ function parseHtmlSync(original, options, existingBudget) {
       last.data += data;
     } else append(parent, make("text", "", data), before);
   };
-  const tokenizer = new HtmlTokenizer(normalized, budget);
   let token;
-  while (token = tokenizer.next(
-    current().namespace === "html" && (rawElements.has(current().name) || current().name === "title" || current().name === "textarea") ? current().name : void 0,
-    current().namespace !== "html"
-  )) {
+  while (token = yield {
+    raw: current().namespace === "html" && (rawElements.has(current().name) || current().name === "title" || current().name === "textarea") ? current().name : void 0,
+    foreign: current().namespace !== "html"
+  }) {
     budget.charge("work", stack.length + active.length + 1);
     if (token.kind === "doctype") {
       if (mode === "beforeHead") append(document, make("doctype", "", token.data), html);
@@ -1553,7 +1801,7 @@ function* inclusiveHtmlDescendants(root, options) {
 
 // packages/safe-bash-command-htmlq/src/selectors.ts
 var cssSpace = (c) => c === " " || c === "	" || c === "\n" || c === "\r" || c === "\f";
-function asciiLower2(s) {
+function asciiLower3(s) {
   let out = "", changed = false;
   for (let i = 0; i < s.length; i++) {
     const n = s.charCodeAt(i);
@@ -1696,7 +1944,7 @@ var Parser = class {
               expected = this.peek() === '"' || this.peek() === "'" ? this.quoted() : this.identifier();
               this.spaces();
               if (this.peek() !== "]") {
-                const flag = asciiLower2(this.identifier());
+                const flag = asciiLower3(this.identifier());
                 if (flag !== "i" && flag !== "s") this.fail();
                 insensitive = flag === "i";
                 this.spaces();
@@ -1705,7 +1953,7 @@ var Parser = class {
             if (this.take() !== "]") this.fail();
             tests.push({ kind: "attribute", value, operator, expected, insensitive });
           } else {
-            const value = asciiLower2(this.identifier());
+            const value = asciiLower3(this.identifier());
             if (value === "not") {
               if (inNot || this.take() !== "(") this.fail();
               const negated = this.list(true);
@@ -1787,13 +2035,13 @@ var Parser = class {
     spaces();
     let end = source.length;
     while (end > at && cssSpace(source[end - 1])) end--;
-    const word = asciiLower2(source.slice(at, end));
+    const word = asciiLower3(source.slice(at, end));
     if (word === "odd") return [2, 1];
     if (word === "even") return [2, 0];
     let sign = "";
     if (source[at] === "+" || source[at] === "-") sign = source[at++];
     const number = digits();
-    if (asciiLower2(source[at] ?? "") !== "n") {
+    if (asciiLower3(source[at] ?? "") !== "n") {
       spaces();
       if (!number || at !== source.length) this.fail();
       return [0, integer(sign + number)];
@@ -1814,7 +2062,7 @@ var Parser = class {
 function attribute(node, name, budget) {
   budget.charge("work", name.length);
   budget.charge("retainedBytes", name.length * 2);
-  const expected = node.namespace === "html" ? asciiLower2(name) : name;
+  const expected = node.namespace === "html" ? asciiLower3(name) : name;
   for (const a of node.attributes) {
     budget.charge("work", a.name.length + expected.length + 1);
     if (a.namespace === "none" && a.name === expected) return a.value;
@@ -1847,7 +2095,7 @@ function matchesTest(node, test, budget) {
   if (test.kind === "type") {
     budget.charge("work", node.name.length + test.value.length);
     budget.charge("retainedBytes", test.value.length * 2);
-    return test.namespace !== "none" && (test.value === "*" || node.name === (node.namespace === "html" ? asciiLower2(test.value) : test.value));
+    return test.namespace !== "none" && (test.value === "*" || node.name === (node.namespace === "html" ? asciiLower3(test.value) : test.value));
   }
   if (test.kind === "id") {
     const value = attribute(node, "id", budget);
@@ -1863,8 +2111,8 @@ function matchesTest(node, test, budget) {
     budget.charge("work", value.length + expected.length);
     if (test.insensitive) {
       budget.charge("retainedBytes", (value.length + expected.length) * 4);
-      value = asciiLower2(value);
-      expected = asciiLower2(expected);
+      value = asciiLower3(value);
+      expected = asciiLower3(expected);
     }
     switch (test.operator) {
       case "":
@@ -2222,7 +2470,7 @@ function evalSyncHtmlq(inBytes, opArgs, readFileSync, writeFileSync) {
 }
 
 // packages/safe-bash-command-htmlq/src/behavior.ts
-import { yieldTurn } from "../safe-bash-contracts/yield.js";
+import { yieldTurn as yieldTurn2 } from "../safe-bash-contracts/yield.js";
 
 // packages/safe-bash-command-htmlq/src/information.ts
 var help = `Like jq, but for HTML.
@@ -2284,7 +2532,7 @@ async function* projectHtmlq(source, args, invocation) {
     budget.check();
     return;
   }
-  const document = await parseHtml(source, invocation);
+  const document = await parseHtml(source, invocation, "discard");
   let base = baseUrl(args.base);
   if (args.detectBase) {
     const first = selectHtml(document, "base", invocation).next().value;
@@ -2360,7 +2608,7 @@ async function* projectHtmlq(source, args, invocation) {
   let selectedIndex = 0;
   for (const node of nodes) {
     if (selectedIndex % 64 === 0) {
-      await yieldTurn(invocation.signal);
+      await yieldTurn2(invocation.signal);
       invocation.signal.throwIfAborted();
     }
     const isFirstNode = selectedIndex++ === 0;
@@ -2443,6 +2691,79 @@ import { FsError } from "../safe-bash-contracts/errors.js";
 import { writeBytes } from "../safe-bash-contracts/io.js";
 import { createOutputOperation } from "../safe-bash-contracts/output.js";
 import { shellValueByteLength } from "../safe-bash-contracts/value.js";
+
+// packages/safe-bash-command-htmlq/src/staged-output.ts
+import { normalizePath } from "@poe-platform/safe-fs/core";
+async function publishStagedHtmlq(fs, path, source, signal) {
+  const target = await fs.prepareStagingResolution(normalizePath(path), { signal });
+  target.validate();
+  if (target.destination && target.destination.type !== "file")
+    throw new HtmlError("E_UNSUPPORTED", "Output must be a regular VFS file");
+  let stage;
+  let failure;
+  try {
+    const parentPath = target.path.slice(0, target.path.lastIndexOf("/"));
+    stage = await fs.createStagedFile(
+      `${parentPath}/.htmlq-${crypto.randomUUID()}`,
+      "output",
+      { type: "file", data: new Uint8Array() },
+      {
+        parent: target.parent,
+        retainCleanup: true,
+        signal,
+        mode: target.destination ? target.destination.mode & 4095 : 438
+      }
+    );
+    if (!stage.writer || !stage.cleanup)
+      throw new HtmlError("E_UNSUPPORTED", "Output requires retained staging handles");
+    signal.throwIfAborted();
+    for await (const bytes of source) {
+      for (let offset = 0; offset < bytes.length; offset += 16384) {
+        signal.throwIfAborted();
+        await stage.writer.write(bytes.slice(offset, offset + 16384), { signal });
+      }
+    }
+    const stat = await stage.writer.finish({ signal });
+    signal.throwIfAborted();
+    target.validate();
+    await fs.publishStagedFile({ ...stage, file: { ...stage.file, stat } }, target.path, {
+      parent: target.parent,
+      destination: target.destination,
+      ancestors: target.ancestors,
+      commitGuard: target.validate,
+      preserveIdentity: target.destination !== null,
+      signal
+    });
+  } catch (error) {
+    failure = { error };
+  }
+  const cleanupErrors = [];
+  if (stage?.cleanup) {
+    try {
+      await stage.cleanup.remove();
+    } catch (error) {
+      cleanupErrors.push(error);
+    }
+    try {
+      await stage.cleanup.close();
+    } catch (error) {
+      cleanupErrors.push(error);
+    }
+  } else if (stage) {
+    try {
+      await fs.removeStagedFile(stage);
+    } catch (error) {
+      cleanupErrors.push(error);
+    }
+  }
+  if (cleanupErrors.length) {
+    if (failure) cleanupErrors.unshift(failure.error);
+    throw new AggregateError(cleanupErrors, "htmlq staged output cleanup failed");
+  }
+  if (failure) throw failure.error;
+}
+
+// packages/safe-bash-command-htmlq/src/command.ts
 function admittedLimits(overrides = {}) {
   const limits = { ...defaultHtmlLimits, ...overrides };
   for (const name of Object.keys(defaultHtmlLimits)) {
@@ -2654,10 +2975,11 @@ async function htmlq(context, configuration = {}) {
         }
       } else {
         const path = args.output.startsWith("/") ? args.output : `${context.cwd}/${args.output}`;
-        const caps = await context.fs.capabilitiesFor?.(path, { signal: options.signal }) ?? context.fs.capabilities;
+        const caps = await context.fs.capabilitiesFor?.(path, { signal: options.signal, stagingResolution: true }) ?? context.fs.capabilities;
         const streaming = caps.atomicFilePublication ? context.fs.publishFileConditional : void 0;
+        const staged = caps.atomicFileStaging && caps.atomicStagedFileMutation && caps.atomicStagingAncestry && caps.retainedStagingWrite && caps.retainedStagingCleanup && caps.synchronousStagingResolution && caps.guardedStagingPublication && context.fs.prepareStagingResolution && context.fs.createStagedFile && context.fs.publishStagedFile && context.fs.removeStagedFile;
         const buffered = caps.atomicFileMutation || caps.trustedOwnedStaging ? context.fs.writeFileConditional : void 0;
-        if (caps.write === false || caps.readOnly || !streaming && !buffered)
+        if (caps.write === false || caps.readOnly || !streaming && !staged && !buffered)
           throw new HtmlError(
             "E_UNSUPPORTED",
             "Output requires atomic conditional VFS publication"
@@ -2680,6 +3002,8 @@ async function htmlq(context, configuration = {}) {
             signal: options.signal,
             maxBytes: options.limits.outputBytes
           });
+        } else if (staged) {
+          await publishStagedHtmlq(context.fs, path, rendered, options.signal);
         } else {
           const chunks = [];
           let size = 0;

package/dist/safe-bash-command-htmlq/tree.d.ts

@@ -1,6 +1,6 @@
 import { HtmlBudget, type MutableHtmlNode as HtmlNode, type HtmlNode as PublicHtmlNode, type HtmlOptions } from "./contracts.js";
 interface Owner {
-    source: string;
+    source: string | undefined;
     mutated: boolean;
 }
 export type FastMutableNode = HtmlNode & {
@@ -16,6 +16,7 @@ export declare function originalSource(node: PublicHtmlNode): string;
 export declare function detachHtmlNode(node: PublicHtmlNode, options: HtmlOptions): void;
 /** Replace an existing attribute through engine ownership; preserve insertion order. */
 export declare function replaceHtmlAttribute(node: PublicHtmlNode, name: string, value: string, options: HtmlOptions): void;
-export declare function parseHtml(source: AsyncIterable<Uint8Array>, options: HtmlOptions): Promise<PublicHtmlNode>;
+/** Original-source retention is optional for projections and normalized output. */
+export declare function parseHtml(source: AsyncIterable<Uint8Array>, options: HtmlOptions, originalSource?: "retain" | "discard"): Promise<PublicHtmlNode>;
 export declare function parseHtmlSync(original: string, options: HtmlOptions, existingBudget?: HtmlBudget): PublicHtmlNode;
 export {};