@poe-platform/safe-fs 0.1.812 → 0.1.813

package/dist/safe-fs/core.d.ts

@@ -8,8 +8,8 @@ export * from "./fs/object-publication/index.js";
 export * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";
 export * from "./python/index.js";
-export { parseXml, parseXmlSteps, parseXmlStream, XmlLimitError } from "./xml.js";
-export type { XmlName, XmlAttribute, XmlContent, XmlElement, XmlLimits } from "./xml.js";
+export { parseXml, parseXmlSteps, parseXmlSourceSteps, normalizeXmlChunks, parseXmlStream, XmlLimitError } from "./xml.js";
+export type { XmlName, XmlAttribute, XmlContent, XmlElement, XmlLimits, XmlParserFrame, XmlFrameRequest } from "./xml.js";
 export * from "./contracts/object.js";
 export { ObjectAuthority } from "./fs/object-authority.js";
 export * from "./fs/s3/index.js";

package/dist/safe-fs/core.js

@@ -8,7 +8,7 @@ export * from "./fs/object-publication/index.js";
 export * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";
 export * from "./python/index.js";
-export { parseXml, parseXmlSteps, parseXmlStream, XmlLimitError } from "./xml.js";
+export { parseXml, parseXmlSteps, parseXmlSourceSteps, normalizeXmlChunks, parseXmlStream, XmlLimitError } from "./xml.js";
 export * from "./contracts/object.js";
 export { ObjectAuthority } from "./fs/object-authority.js";
 export * from "./fs/s3/index.js";

package/dist/xml-ast/characters.d.ts

@@ -0,0 +1,3 @@
+export declare function validCharacter(point: number): boolean;
+/** Validate scalar values and normalize XML line endings in fixed windows. */
+export declare function normalizeXmlChunks(source: AsyncIterable<string> | Iterable<string>, flushChunks?: boolean): AsyncGenerator<string>;

package/dist/xml-ast/characters.js

@@ -0,0 +1,53 @@
+export function validCharacter(point) {
+    return point === 9 || point === 10 || point === 13
+        || (point >= 0x20 && point <= 0xd7ff)
+        || (point >= 0xe000 && point <= 0xfffd)
+        || (point >= 0x10000 && point <= 0x10ffff);
+}
+/** Validate scalar values and normalize XML line endings in fixed windows. */
+export async function* normalizeXmlChunks(source, flushChunks = false) {
+    let first = true, afterCR = false, high = 0, output = '';
+    for await (const chunk of source) {
+        for (let index = 0; index < chunk.length; index++) {
+            const code = chunk.charCodeAt(index);
+            if (first) {
+                first = false;
+                if (code === 0xfeff)
+                    continue;
+            }
+            if (high) {
+                if (code < 0xdc00 || code > 0xdfff)
+                    throw new SyntaxError('Invalid XML: invalid character');
+                output += String.fromCharCode(high, code);
+                high = 0;
+            }
+            else {
+                if (afterCR) {
+                    afterCR = false;
+                    if (code === 10)
+                        continue;
+                }
+                if (code >= 0xd800 && code <= 0xdbff) {
+                    high = code;
+                    continue;
+                }
+                if (!validCharacter(code))
+                    throw new SyntaxError('Invalid XML: invalid character');
+                afterCR = code === 13;
+                output += code === 13 ? '\n' : chunk[index];
+            }
+            if (output.length >= 512) {
+                yield output;
+                output = '';
+            }
+        }
+        if (flushChunks && output) {
+            yield output;
+            output = '';
+        }
+    }
+    if (high)
+        throw new SyntaxError('Invalid XML: invalid character');
+    if (output)
+        yield output;
+}

package/dist/xml-ast/frames.d.ts

@@ -0,0 +1,28 @@
+import type { XmlContent, XmlElement } from './index.js';
+export interface XmlParserFrame {
+    element: XmlElement;
+    content: XmlContent[] | undefined;
+    name: string;
+    namespaces: Map<string, string>;
+}
+export type XmlFrameRequest = {
+    readonly frameOperation: 'push';
+    readonly frame: XmlParserFrame;
+} | {
+    readonly frameOperation: 'pop';
+} | {
+    readonly frameOperation: 'peek';
+    frame?: XmlParserFrame;
+};
+/** External mode caches only the current frame. The host owns the linked stack. */
+export declare class XmlFrames {
+    private readonly external;
+    private readonly frames;
+    private depth;
+    private current;
+    constructor(external: boolean);
+    get length(): number;
+    peek(): Generator<XmlFrameRequest, XmlParserFrame | undefined, void>;
+    push(frame: XmlParserFrame): Generator<XmlFrameRequest, void, void>;
+    pop(): Generator<XmlFrameRequest, XmlParserFrame | undefined, void>;
+}

package/dist/xml-ast/frames.js

@@ -0,0 +1,45 @@
+/** External mode caches only the current frame. The host owns the linked stack. */
+export class XmlFrames {
+    external;
+    frames = [];
+    depth = 0;
+    current;
+    constructor(external) {
+        this.external = external;
+    }
+    get length() { return this.external ? this.depth : this.frames.length; }
+    *peek() {
+        if (!this.external)
+            return this.frames.at(-1);
+        if (!this.depth)
+            return undefined;
+        if (!this.current) {
+            const request = { frameOperation: 'peek' };
+            yield request;
+            if (!request.frame)
+                throw new TypeError('Incomplete XML frame read');
+            this.current = request.frame;
+        }
+        return this.current;
+    }
+    *push(frame) {
+        if (!this.external) {
+            this.frames.push(frame);
+            return;
+        }
+        yield { frameOperation: 'push', frame };
+        this.current = frame;
+        this.depth++;
+    }
+    *pop() {
+        if (!this.external)
+            return this.frames.pop();
+        if (!this.depth)
+            return undefined;
+        const frame = yield* this.peek();
+        yield { frameOperation: 'pop' };
+        this.depth--;
+        this.current = undefined;
+        return frame;
+    }
+}

package/dist/xml-ast/index.d.ts

@@ -1,3 +1,9 @@
+import { type XmlFrameRequest } from "./frames.js";
+export type { XmlParserFrame, XmlFrameRequest } from "./frames.js";
+export { normalizeXmlChunks } from "./characters.js";
+import { type XmlSourceStep } from "./source.js";
+export type { XmlSourceRead, XmlSourceStep } from "./source.js";
+import type { XmlStreamEvent } from "./stream.js";
 export { XmlLimitError } from "./errors.js";
 export interface XmlName {
     readonly name: string;
@@ -40,6 +46,26 @@ export interface XmlLimits {
     readonly maxTextLength?: number;
     readonly onElement?: (element: XmlName, parent: XmlName | undefined, depth: number) => void;
 }
-export declare function parseXmlSteps(input: string, limits?: XmlLimits): Generator<number, XmlElement, void>;
+export interface XmlStepLimits extends XmlLimits {
+    /** Return root metadata without retaining descendants or text. */
+    readonly retainTree?: boolean;
+    /** Synchronous ordered events, including repaired closes. Requires retainTree:
+     * false. Drive the step iterator to await external consumers between windows. */
+    readonly events?: (event: XmlStreamEvent) => void;
+}
+export interface XmlSourceLimits extends XmlStepLimits {
+    /** Emit text and CDATA in bounded fragments, marking continuations of the same logical
+     * node. Requires retainTree: false; consumers must preserve fragment identity. */
+    readonly fragmentContent?: boolean;
+    /** Store active parser frames through host-serviced requests. Requires retainTree: false. */
+    readonly storeFrames?: boolean;
+}
+export type XmlParseStep = XmlSourceStep | XmlFrameRequest;
+/** Parse a validated, BOM-free, line-normalized UTF-16 source via bounded read requests. */
+export declare function parseXmlSourceSteps(length: number | undefined, limits?: XmlStepLimits & {
+    readonly storeFrames?: false;
+}): Generator<XmlSourceStep, XmlElement, void>;
+export declare function parseXmlSourceSteps(length: number | undefined, limits: XmlSourceLimits): Generator<XmlParseStep, XmlElement, void>;
+export declare function parseXmlSteps(input: string, limits?: XmlStepLimits): Generator<number, XmlElement, void>;
 export declare function parseXml(input: string, limits?: XmlLimits): XmlElement;
 export { parseXmlStream, type XmlStreamLimits, type XmlStreamEvent } from "./stream.js";

package/dist/xml-ast/index.js

@@ -1,7 +1,11 @@
+import { XmlFrames } from "./frames.js";
+import { validCharacter } from "./characters.js";
+export { normalizeXmlChunks } from "./characters.js";
+import { XmlSource } from "./source.js";
 import { XmlLimitError } from "./errors.js";
 export { XmlLimitError } from "./errors.js";
 function* find(source, needle, start) {
-    const found = source.indexOf(needle, start);
+    const found = typeof source === "string" ? source.indexOf(needle, start) : yield* source.indexOf(needle, start);
     const end = found < 0 ? source.length : found;
     let remaining = end - start;
     while (remaining >= 512) {
@@ -17,12 +21,6 @@ const xmlnsNamespace = "http://www.w3.org/2000/xmlns/";
 function invalid(message) {
     throw new SyntaxError(`Invalid XML: ${message}`);
 }
-function validCharacter(point) {
-    return point === 9 || point === 10 || point === 13
-        || (point >= 0x20 && point <= 0xd7ff)
-        || (point >= 0xe000 && point <= 0xfffd)
-        || (point >= 0x10000 && point <= 0x10ffff);
-}
 function nameStart(point) {
     return point === 95 || (point >= 65 && point <= 90) || (point >= 97 && point <= 122)
         || (point >= 0xc0 && point <= 0xd6) || (point >= 0xd8 && point <= 0xf6)
@@ -69,6 +67,95 @@ function qualifiedNameSync(name, cache) {
     }
     return parts;
 }
+function* entity(source, start, end, recover) {
+    // Inspect only a bounded prefix, even for arbitrarily long numeric references.
+    const prefix = typeof source === "string" ? source.slice(start, Math.min(end, start + 4))
+        : yield* source.slice(start, Math.min(end, start + 4));
+    const predefined = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
+    if (end - start <= 4 && Object.hasOwn(predefined, prefix))
+        return predefined[prefix];
+    const hexadecimal = prefix.startsWith("#x"), digits = start + (hexadecimal ? 2 : 1);
+    if (!prefix.startsWith("#") || digits >= end) {
+        if (!recover)
+            invalid("undeclared entity");
+        recover("undeclared entity");
+        return "";
+    }
+    let point = 0;
+    for (let index = digits; index < end; index++) {
+        const code = typeof source === "string" ? source.charCodeAt(index) : yield* source.charCodeAt(index);
+        const digit = code >= 48 && code <= 57 ? code - 48 : hexadecimal && code >= 65 && code <= 70 ? code - 55
+            : hexadecimal && code >= 97 && code <= 102 ? code - 87 : -1;
+        if (digit < 0)
+            invalid("undeclared entity");
+        point = point * (hexadecimal ? 16 : 10) + digit;
+        if (point > 0x10ffff)
+            invalid("invalid character reference");
+        if ((index - digits + 1) % 512 === 0)
+            yield 512;
+    }
+    if ((end - digits) % 512)
+        yield (end - digits) % 512;
+    if (!validCharacter(point))
+        invalid("invalid character reference");
+    return String.fromCodePoint(point);
+}
+/** Decoded text fragments; source read/work requests remain host-serviced. */
+function* textParts(source, start, end, decode, recover) {
+    let cursor = start;
+    while (cursor < end) {
+        let finish = Math.min(end, cursor + 512);
+        if (finish < end) {
+            const last = yield* source.charCodeAt(finish - 1);
+            if (last >= 0xd800 && last <= 0xdbff)
+                finish--;
+        }
+        const raw = yield* source.slice(cursor, finish);
+        const found = decode ? raw.indexOf("&") : -1;
+        if (found < 0) {
+            yield raw;
+            yield raw.length;
+            cursor = finish;
+            continue;
+        }
+        const amp = cursor + found;
+        if (found) {
+            yield raw.slice(0, found);
+            yield found;
+        }
+        const semicolon = yield* source.indexOf(";", amp + 1, end);
+        if (semicolon < 0) {
+            if (!recover)
+                invalid("unterminated entity");
+            recover("unterminated entity");
+            cursor = amp + 1;
+            decode = false;
+            continue;
+        }
+        const part = yield* entity(source, amp + 1, semicolon, recover);
+        if (part)
+            yield part;
+        yield 1;
+        cursor = semicolon + 1;
+    }
+}
+function* textFragments(source, start, end, decode, recover) {
+    let pending = "";
+    for (const part of textParts(source, start, end, decode, recover)) {
+        if (typeof part !== "string") {
+            yield part;
+            continue;
+        }
+        pending += part;
+        while (pending.length >= 512) {
+            const last = pending.charCodeAt(511), width = last >= 0xd800 && last <= 0xdbff ? 511 : 512;
+            yield pending.slice(0, width);
+            pending = pending.slice(width);
+        }
+    }
+    if (pending)
+        yield pending;
+}
 function* entities(text, recover) {
     let result = "";
     let offset = 0;
@@ -84,39 +171,7 @@ function* entities(text, recover) {
             recover("unterminated entity");
             return result + text.slice(start + 1);
         }
-        const entity = text.slice(start + 1, end);
-        const predefined = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
-        if (Object.hasOwn(predefined, entity))
-            result += predefined[entity];
-        else {
-            const hexadecimal = entity.startsWith("#x");
-            const digits = entity.slice(hexadecimal ? 2 : 1);
-            if (!entity.startsWith("#") || !digits.length) {
-                if (!recover)
-                    invalid("undeclared entity");
-                recover("undeclared entity");
-                offset = end + 1;
-                continue;
-            }
-            let point = 0;
-            for (let index = 0; index < digits.length; index++) {
-                const code = digits.charCodeAt(index);
-                const digit = code >= 48 && code <= 57 ? code - 48 : hexadecimal && code >= 65 && code <= 70 ? code - 55
-                    : hexadecimal && code >= 97 && code <= 102 ? code - 87 : -1;
-                if (digit < 0)
-                    invalid("undeclared entity");
-                point = point * (hexadecimal ? 16 : 10) + digit;
-                if (point > 0x10ffff)
-                    invalid("invalid character reference");
-                if ((index + 1) % 512 === 0)
-                    yield 512;
-            }
-            if (digits.length % 512)
-                yield digits.length % 512;
-            if (!validCharacter(point))
-                invalid("invalid character reference");
-            result += String.fromCodePoint(point);
-        }
+        result += yield* entity(text, start + 1, end, recover);
         offset = end + 1;
     }
     return result;
@@ -182,68 +237,43 @@ function* validDeclaration(content, expectedEncoding) {
     }
     return offset === content.length;
 }
-export function* parseXmlSteps(input, limits = {}) {
+function validateLimits(limits) {
+    for (const limit of [limits.maxDepth, limits.maxNodes, limits.maxAttributes, limits.maxContentNodes, limits.maxAttributesPerElement, limits.maxNamespaces]) {
+        if (limit !== undefined && ((limit !== Infinity && !Number.isSafeInteger(limit)) || limit < 1))
+            throw new RangeError("XML limits must be positive integers");
+    }
+    if (limits.maxTextLength !== undefined && ((limits.maxTextLength !== Infinity && !Number.isSafeInteger(limits.maxTextLength)) || limits.maxTextLength < 1))
+        throw new RangeError("XML limits must be positive integers");
+    if (limits.events && limits.retainTree !== false)
+        throw new TypeError("XML events require retainTree: false");
+}
+export function* parseXmlSourceSteps(length, limits = {}) {
+    validateLimits(limits);
+    if (limits.storeFrames && limits.retainTree !== false)
+        throw new TypeError("Stored XML frames require retainTree: false");
+    if (limits.fragmentContent && limits.retainTree !== false)
+        throw new TypeError("XML content fragments require retainTree: false");
+    const source = new XmlSource(length);
     const maxDepth = limits.maxDepth ?? Infinity;
     const maxNodes = limits.maxNodes ?? Infinity;
     const maxAttributes = limits.maxAttributes ?? Infinity;
     const retainContent = limits.retainContent !== false;
+    const retainTree = limits.retainTree !== false;
+    const retain = retainTree && retainContent;
     const maxContentNodes = limits.maxContentNodes ?? Infinity;
     const emptyContent = Object.freeze([]);
     const emptyAttributes = Object.freeze([]);
     const emptyNamespaces = new Map();
     const maxAttributesPerElement = limits.maxAttributesPerElement ?? Infinity;
     const maxNamespaces = limits.maxNamespaces ?? Infinity;
-    for (const limit of [limits.maxDepth, limits.maxNodes, limits.maxAttributes, limits.maxContentNodes, limits.maxAttributesPerElement, limits.maxNamespaces]) {
-        if (limit !== undefined && ((limit !== Infinity && !Number.isSafeInteger(limit)) || limit < 1))
-            throw new RangeError("XML limits must be positive integers");
-    }
     const maxTextLength = limits.maxTextLength ?? Infinity;
-    if (limits.maxTextLength !== undefined && ((maxTextLength !== Infinity && !Number.isSafeInteger(maxTextLength)) || maxTextLength < 1))
-        throw new RangeError("XML limits must be positive integers");
     let textLength = 0;
     const admitText = (text) => {
         if (text.length > maxTextLength - textLength)
             throw new XmlLimitError("maxTextLength", "XML text limit exceeded");
         textLength += text.length;
     };
-    const chunks = [];
-    const start = input.charCodeAt(0) === 0xfeff ? 1 : 0;
-    let chunkStart = start;
-    let chunkLength = 0;
-    let normalizedChunk = "";
-    // Keep validated spans intact; only changed line endings need new strings.
-    for (let index = start; index < input.length; index++) {
-        const point = input.codePointAt(index);
-        if (!validCharacter(point))
-            invalid("invalid character");
-        if (point === 13) {
-            normalizedChunk += input.slice(chunkStart, index) + "\n";
-            if (input.charCodeAt(index + 1) === 10)
-                index++;
-            chunkStart = index + 1;
-            chunkLength++;
-        }
-        else {
-            chunkLength += point > 0xffff ? 2 : 1;
-            if (point > 0xffff)
-                index++;
-        }
-        if (chunkLength >= 512) {
-            if (normalizedChunk) {
-                chunks.push(normalizedChunk + input.slice(chunkStart, index + 1));
-                normalizedChunk = "";
-                chunkStart = index + 1;
-            }
-            chunkLength = 0;
-            yield 512;
-        }
-    }
-    if (chunkLength)
-        yield chunkLength;
-    if (chunks.length || normalizedChunk)
-        chunks.push(normalizedChunk + input.slice(chunkStart));
-    const source = chunks.length ? chunks.join("") : input.slice(start);
-    const stack = [];
+    const stack = new XmlFrames(limits.storeFrames === true);
     let root;
     const prolog = [];
     const epilog = [];
@@ -261,8 +291,8 @@ export function* parseXmlSteps(input, limits = {}) {
     let pendingWork = 0;
     const skipWhitespace = function* () {
         const start = offset;
-        while (offset < source.length) {
-            const c = source.charCodeAt(offset);
+        while (yield* source.has(offset)) {
+            const c = (yield* source.charCodeAt(offset));
             if (c !== 32 && c !== 9 && c !== 10 && c !== 13)
                 break;
             offset++;
@@ -276,8 +306,8 @@ export function* parseXmlSteps(input, limits = {}) {
     };
     const scanName = function* () {
         const start = offset;
-        while (offset < source.length) {
-            const c = source.charCodeAt(offset);
+        while (yield* source.has(offset)) {
+            const c = (yield* source.charCodeAt(offset));
             if (c === 32 || c === 9 || c === 13 || c === 10 || c === 47 || c === 61 || c === 62 || c === 63)
                 break;
             offset++;
@@ -287,7 +317,7 @@ export function* parseXmlSteps(input, limits = {}) {
                 pendingWork -= 512;
             }
         }
-        const name = source.slice(start, offset);
+        const name = (yield* source.slice(start, offset));
         pendingWork += offset - start;
         while (pendingWork >= 512) {
             yield 512;
@@ -296,7 +326,7 @@ export function* parseXmlSteps(input, limits = {}) {
         const [prefix, localName] = qualifiedNameSync(name, qualifiedNames);
         return [name, prefix, localName];
     };
-    while (offset < source.length) {
+    while (yield* source.has(offset)) {
         pendingWork += 1;
         if (pendingWork >= 512) {
             while (pendingWork >= 512) {
@@ -304,10 +334,53 @@ export function* parseXmlSteps(input, limits = {}) {
                 pendingWork -= 512;
             }
         }
-        if (source.charCodeAt(offset) !== 60) {
-            const next = source.indexOf("<", offset);
+        if ((yield* source.charCodeAt(offset)) !== 60) {
+            const next = (yield* source.indexOf("<", offset));
             const endPos = next < 0 ? source.length : next;
-            const text = source.slice(offset, endPos);
+            if (limits.fragmentContent) {
+                if ((yield* source.indexOf("]]>", offset, endPos)) >= 0)
+                    invalid("CDATA terminator in text");
+                const parent = yield* stack.peek();
+                let size = 0, outsideText = false;
+                // Validate before emitting any part of the logical node. This preserves
+                // entity/recovery diagnostics and limit precedence without retaining it.
+                for (const part of textFragments(source, offset, endPos, !!parent, limits.recover)) {
+                    if (typeof part !== "string") {
+                        yield part;
+                        continue;
+                    }
+                    size += part.length;
+                    if (!parent)
+                        for (const character of part) {
+                            if (!" \t\r\n".includes(character))
+                                outsideText = true;
+                        }
+                }
+                if (size > maxTextLength - textLength)
+                    throw new XmlLimitError("maxTextLength", "XML text limit exceeded");
+                textLength += size;
+                if (outsideText)
+                    invalid("text outside the root");
+                if (size) {
+                    admitContent();
+                    if (limits.events) {
+                        let continuation = false;
+                        for (const part of textFragments(source, offset, endPos, !!parent, limits.recover ? () => { } : undefined)) {
+                            if (typeof part !== "string") {
+                                yield part;
+                                continue;
+                            }
+                            limits.events({ type: "content", content: { kind: "text", text: part }, parent: parent?.element,
+                                ...(continuation ? { continuation: true } : {}) });
+                            continuation = true;
+                            yield 1;
+                        }
+                    }
+                }
+                offset = endPos;
+                continue;
+            }
+            const text = (yield* source.slice(offset, endPos));
             pendingWork += (endPos - offset) + text.length;
             while (pendingWork >= 512) {
                 yield 512;
@@ -321,13 +394,15 @@ export function* parseXmlSteps(input, limits = {}) {
                 pendingWork -= 512;
             }
             admitText(resolved);
-            const parent = stack.at(-1);
+            const parent = (yield* stack.peek());
             if (parent) {
-                parent.element.text += resolved;
+                if (retainTree)
+                    parent.element.text += resolved;
                 if (resolved.length) {
                     admitContent();
-                    if (retainContent)
+                    if (retain)
                         parent.content.push({ kind: "text", text: resolved });
+                    limits.events?.({ type: "content", content: { kind: "text", text: resolved }, parent: parent.element });
                 }
             }
             else {
@@ -347,42 +422,63 @@ export function* parseXmlSteps(input, limits = {}) {
                 }
                 if (resolved.length) {
                     admitContent();
-                    if (retainContent)
+                    if (retain)
                         (root ? epilog : prolog).push({ kind: "text", text: resolved });
+                    limits.events?.({ type: "content", content: { kind: "text", text: resolved }, parent: undefined });
                 }
             }
             offset = endPos;
         }
-        else if (source.startsWith("<!--", offset)) {
+        else if ((yield* source.startsWith("<!--", offset))) {
             const end = yield* find(source, "-->", offset + 4);
-            if (end < 0 || (yield* find(source.slice(offset + 4, end), "--", 0)) >= 0 || source.slice(offset + 4, end).endsWith("-")) {
+            const text = end < 0 ? "" : yield* source.slice(offset + 4, end);
+            if (end < 0 || (yield* find(text, "--", 0)) >= 0 || text.endsWith("-")) {
                 invalid("malformed comment");
             }
-            const parent = stack.at(-1);
-            const text = source.slice(offset + 4, end);
+            const parent = (yield* stack.peek());
             admitText(text);
             admitContent();
-            if (retainContent) {
+            if (retain) {
                 (parent?.content ?? (root ? epilog : prolog)).push({ kind: "comment", text });
             }
+            limits.events?.({ type: "content", content: { kind: "comment", text }, parent: parent?.element });
             offset = end + 3;
         }
-        else if (source.startsWith("<![CDATA[", offset)) {
+        else if ((yield* source.startsWith("<![CDATA[", offset))) {
             if (!stack.length)
                 invalid("CDATA outside root");
             const end = yield* find(source, "]]>", offset + 9);
             if (end < 0)
                 invalid("unterminated CDATA");
-            const cdataText = source.slice(offset + 9, end);
-            admitText(cdataText);
-            const parent = stack.at(-1);
-            parent.element.text += cdataText;
+            if (end - offset - 9 > maxTextLength - textLength)
+                throw new XmlLimitError("maxTextLength", "XML text limit exceeded");
+            const parent = (yield* stack.peek());
             admitContent();
-            if (retainContent)
-                parent.content.push({ kind: "cdata", text: cdataText });
+            let cursor = offset + 9, continuation = false;
+            do {
+                let finish = limits.fragmentContent ? Math.min(end, cursor + 512) : end;
+                if (finish < end) {
+                    const last = yield* source.charCodeAt(finish - 1);
+                    if (last >= 0xd800 && last <= 0xdbff)
+                        finish--;
+                }
+                const text = yield* source.slice(cursor, finish);
+                admitText(text);
+                if (retainTree)
+                    parent.element.text += text;
+                if (retain)
+                    parent.content.push({ kind: "cdata", text });
+                limits.events?.({ type: "content", content: { kind: "cdata", text }, parent: parent.element,
+                    ...(continuation ? { continuation: true } : {}) });
+                // Let external consumers persist each fragment before producing another.
+                if (limits.fragmentContent)
+                    yield Math.max(1, text.length);
+                continuation = true;
+                cursor = finish;
+            } while (cursor < end);
             offset = end + 3;
         }
-        else if (source.startsWith("<?", offset)) {
+        else if ((yield* source.startsWith("<?", offset))) {
             const start = offset;
             offset += 2;
             const [target] = yield* scanName();
@@ -393,19 +489,19 @@ export function* parseXmlSteps(input, limits = {}) {
             const end = yield* find(source, "?>", offset);
             if (end < 0)
                 invalid("unterminated processing instruction");
-            const content = source.slice(offset, end);
+            const content = (yield* source.slice(offset, end));
             if (target.length === 3 && target.toLowerCase() === "xml") {
                 if (start !== 0 || target !== "xml"
                     || !(yield* validDeclaration(content, limits.expectedEncoding))) {
                     invalid("unsupported XML declaration");
                 }
                 if (retainContent)
-                    declaration = source.slice(start, end + 2);
+                    declaration = (yield* source.slice(start, end + 2));
             }
             else if (content && !" \t\n\r".includes(content[0]))
                 invalid("invalid processing instruction");
             if (!(target.length === 3 && target.toLowerCase() === "xml")) {
-                const parent = stack.at(-1);
+                const parent = (yield* stack.peek());
                 let wsStart = 0;
                 while (wsStart < content.length && " \t\n\r".includes(content[wsStart]))
                     wsStart++;
@@ -417,16 +513,17 @@ export function* parseXmlSteps(input, limits = {}) {
                 const text = content.slice(wsStart);
                 admitText(text);
                 admitContent();
-                if (retainContent) {
+                if (retain) {
                     (parent?.content ?? (root ? epilog : prolog)).push({ kind: "processing-instruction", target, text });
                 }
+                limits.events?.({ type: "content", content: { kind: "processing-instruction", target, text }, parent: parent?.element });
             }
             offset = end + 2;
         }
-        else if (source.startsWith("<!", offset)) {
+        else if ((yield* source.startsWith("<!", offset))) {
             invalid("DTD and entity declarations are forbidden");
         }
-        else if (source.charCodeAt(offset + 1) === 47) {
+        else if ((yield* source.charCodeAt(offset + 1)) === 47) {
             offset += 2;
             const [name] = yield* scanName();
             yield* skipWhitespace();
@@ -434,15 +531,18 @@ export function* parseXmlSteps(input, limits = {}) {
                 yield 512;
                 pendingWork -= 512;
             }
-            if (source[offset++] !== ">" || stack.pop()?.name !== name) {
+            const closed = (yield* source.slice(offset++, offset)) === ">" ? (yield* stack.pop()) : undefined;
+            if (closed?.name !== name) {
                 if (!limits.recover)
                     invalid("mismatched closing tag");
                 limits.recover("mismatched closing tag");
             }
+            if (closed)
+                limits.events?.({ type: "close", element: closed.element, parent: (yield* stack.peek())?.element });
         }
         else {
             offset++;
-            const repeated = previousEmpty && source.startsWith(previousEmpty.suffix, offset) ? previousEmpty : undefined;
+            const repeated = previousEmpty && (yield* source.startsWith(previousEmpty.suffix, offset)) ? previousEmpty : undefined;
             const [name, prefix, localName] = repeated
                 ? [repeated.name, repeated.prefix, repeated.localName]
                 : (yield* scanName());
@@ -457,7 +557,7 @@ export function* parseXmlSteps(input, limits = {}) {
             }
             let attributes;
             const attrMeta = [];
-            let namespaces = stack.at(-1)?.namespaces ?? new Map([["xml", xmlNamespace]]);
+            let namespaces = (yield* stack.peek())?.namespaces ?? new Map([["xml", xmlNamespace]]);
             let ownsNamespaces = stack.length === 0;
             while (!repeated) {
                 const ws = (yield* skipWhitespace());
@@ -465,7 +565,7 @@ export function* parseXmlSteps(input, limits = {}) {
                     yield 512;
                     pendingWork -= 512;
                 }
-                const ch = source.charCodeAt(offset);
+                const ch = (yield* source.charCodeAt(offset));
                 if (ch === 47 || ch === 62 || limits.recover && offset === source.length)
                     break;
                 if (ws === 0)
@@ -482,13 +582,13 @@ export function* parseXmlSteps(input, limits = {}) {
                 if ((attributes?.size ?? 0) >= maxAttributesPerElement)
                     throw new XmlLimitError("maxAttributesPerElement", "XML attribute limit exceeded");
                 yield* skipWhitespace();
-                if (source[offset++] !== "=")
+                if ((yield* source.slice(offset++, offset)) !== "=")
                     invalid("missing attribute equals");
                 yield* skipWhitespace();
-                const quote = source[offset++];
+                const quote = (yield* source.slice(offset++, offset));
                 if (quote !== '"' && quote !== "'")
                     invalid("unquoted attribute");
-                const end = source.indexOf(quote, offset);
+                const end = (yield* source.indexOf(quote, offset));
                 const scanLen = (end < 0 ? source.length : end) - offset;
                 pendingWork += scanLen;
                 while (pendingWork >= 512) {
@@ -497,7 +597,7 @@ export function* parseXmlSteps(input, limits = {}) {
                 }
                 if (end < 0)
                     invalid("unterminated attribute");
-                const raw = source.slice(offset, end);
+                const raw = (yield* source.slice(offset, end));
                 pendingWork += raw.length * 2;
                 while (pendingWork >= 512) {
                     yield 512;
@@ -564,7 +664,7 @@ export function* parseXmlSteps(input, limits = {}) {
             if (stack.length + 1 > maxDepth)
                 throw new XmlLimitError("maxDepth", "XML resource limit exceeded");
             const namespace = namespaces.get(prefix) ?? "";
-            limits.onElement?.({ name, namespace, localName }, stack.at(-1)?.element, stack.length + 1);
+            limits.onElement?.({ name, namespace, localName }, (yield* stack.peek())?.element, stack.length + 1);
             admitContent();
             const retainedAttributes = [];
             if (retainContent && attributes) {
@@ -581,31 +681,36 @@ export function* parseXmlSteps(input, limits = {}) {
                 yield 512;
                 pendingWork -= 512;
             }
-            const content = retainContent ? [] : undefined;
+            const content = retain ? [] : undefined;
             const element = { kind: "element", name, namespace, localName, children: [], text: "", content: content ?? emptyContent, attributes: retainContent ? retainedAttributes : emptyAttributes, namespaces: retainContent ? namespaces : emptyNamespaces, ...(root === undefined && retainContent ? { prolog, epilog, ...(declaration === undefined ? {} : { declaration }) } : {}) };
-            const parent = stack.at(-1);
+            const parent = (yield* stack.peek());
             if (parent) {
-                parent.element.children.push(element);
-                parent.content?.push(element);
+                if (retainTree) {
+                    parent.element.children.push(element);
+                    parent.content?.push(element);
+                }
             }
             else if (root)
                 invalid("multiple root elements");
             else
                 root = element;
-            const empty = source[offset] === "/";
+            const empty = (yield* source.slice(offset, offset + 1)) === "/";
             if (empty)
                 offset++;
-            if (source[offset++] !== ">") {
+            if ((yield* source.slice(offset++, offset)) !== ">") {
                 if (!limits.recover)
                     invalid("unterminated start tag");
                 limits.recover("unterminated start tag");
             }
             // Only cache compact, attribute-free spellings. Namespace resolution and
             // every admission counter still run for each distinct physical element.
-            if (empty && !attributes && name.length <= 512 && source.slice(offset - name.length - 3, offset) === `<${name}/>`)
+            if (empty && !attributes && name.length <= 512 && (yield* source.slice(offset - name.length - 3, offset)) === `<${name}/>`)
                 previousEmpty = { suffix: name + "/>", name, prefix, localName };
+            limits.events?.({ type: "open", element, parent: parent?.element });
             if (!empty)
-                stack.push({ element, content, name, namespaces });
+                yield* stack.push({ element, content, name, namespaces });
+            else
+                limits.events?.({ type: "close", element, parent: parent?.element });
         }
     }
     if (pendingWork > 0) {
@@ -618,9 +723,73 @@ export function* parseXmlSteps(input, limits = {}) {
         if (!limits.recover)
             invalid("incomplete document");
         limits.recover("incomplete document");
+        while (stack.length) {
+            const closed = (yield* stack.pop());
+            limits.events?.({ type: "close", element: closed.element, parent: (yield* stack.peek())?.element });
+            yield 1;
+        }
     }
     return root;
 }
+function* normalizeXmlSteps(input) {
+    const chunks = [];
+    const start = input.charCodeAt(0) === 0xfeff ? 1 : 0;
+    let chunkStart = start;
+    let chunkLength = 0;
+    let normalizedChunk = "";
+    // Keep validated spans intact; only changed line endings need new strings.
+    for (let index = start; index < input.length; index++) {
+        const point = input.codePointAt(index);
+        if (!validCharacter(point))
+            invalid("invalid character");
+        if (point === 13) {
+            normalizedChunk += input.slice(chunkStart, index) + "\n";
+            if (input.charCodeAt(index + 1) === 10)
+                index++;
+            chunkStart = index + 1;
+            chunkLength++;
+        }
+        else {
+            chunkLength += point > 0xffff ? 2 : 1;
+            if (point > 0xffff)
+                index++;
+        }
+        if (chunkLength >= 512) {
+            if (normalizedChunk) {
+                chunks.push(normalizedChunk + input.slice(chunkStart, index + 1));
+                normalizedChunk = "";
+                chunkStart = index + 1;
+            }
+            chunkLength = 0;
+            yield 512;
+        }
+    }
+    if (chunkLength)
+        yield chunkLength;
+    if (chunks.length || normalizedChunk)
+        chunks.push(normalizedChunk + input.slice(chunkStart));
+    return chunks.length ? chunks.join("") : input.slice(start);
+}
+export function* parseXmlSteps(input, limits = {}) {
+    validateLimits(limits);
+    const source = yield* normalizeXmlSteps(input);
+    const parser = parseXmlSourceSteps(source.length, limits);
+    let step = parser.next();
+    try {
+        while (!step.done) {
+            if (typeof step.value === "number")
+                yield step.value;
+            else
+                step.value.value = source.slice(step.value.offset, step.value.offset + step.value.length);
+            step = parser.next();
+        }
+        return step.value;
+    }
+    finally {
+        if (!step.done)
+            parser.return(undefined);
+    }
+}
 export function parseXml(input, limits = {}) {
     const parser = parseXmlSteps(input, limits);
     let result = parser.next();

package/dist/xml-ast/source.d.ts

@@ -0,0 +1,24 @@
+/** Fill value before advancing. Streaming reads may be short; mark complete at EOF. */
+export interface XmlSourceRead {
+    readonly offset: number;
+    readonly length: number;
+    readonly streaming?: boolean;
+    value?: string;
+    complete?: boolean;
+}
+export type XmlSourceStep = number | XmlSourceRead;
+/** One fixed window; individual returned tokens still have their own size cost. */
+export declare class XmlSource {
+    private window;
+    private start;
+    private end;
+    private readonly streaming;
+    constructor(length: number | undefined);
+    get length(): number;
+    private load;
+    has(offset: number): Generator<XmlSourceStep, boolean, void>;
+    slice(start: number, end?: number): Generator<XmlSourceStep, string, void>;
+    charCodeAt(offset: number): Generator<XmlSourceStep, number, void>;
+    startsWith(value: string, offset: number): Generator<XmlSourceStep, boolean, void>;
+    indexOf(value: string, offset: number, end?: number): Generator<XmlSourceStep, number, void>;
+}

package/dist/xml-ast/source.js

@@ -0,0 +1,71 @@
+/** One fixed window; individual returned tokens still have their own size cost. */
+export class XmlSource {
+    window = '';
+    start = -1;
+    end;
+    streaming;
+    constructor(length) {
+        if (length !== undefined && (!Number.isSafeInteger(length) || length < 0))
+            throw new RangeError('Invalid XML source length');
+        this.streaming = length === undefined;
+        this.end = length ?? Infinity;
+    }
+    get length() { return this.end; }
+    *load(offset) {
+        if (offset >= this.end || offset >= this.start && offset < this.start + this.window.length)
+            return;
+        const start = this.streaming ? offset : Math.floor(offset / 4096) * 4096;
+        const request = { offset: start, length: Math.min(this.streaming ? 512 : 4096, this.end - start),
+            ...(this.streaming ? { streaming: true } : {}) };
+        yield request;
+        if (typeof request.value !== 'string' || request.value.length > request.length ||
+            (!this.streaming && request.value.length !== request.length) ||
+            (!request.value.length && !request.complete && this.streaming))
+            throw new TypeError('Incomplete XML source read');
+        if (this.streaming && request.complete)
+            this.end = start + request.value.length;
+        this.window = request.value;
+        this.start = start;
+    }
+    *has(offset) {
+        yield* this.load(offset);
+        return offset < this.end;
+    }
+    *slice(start, end = this.length) {
+        start = start < 0 ? Math.max(0, this.length + start) : Math.min(start, this.length);
+        end = end < 0 ? Math.max(0, this.length + end) : Math.min(end, this.length);
+        let result = '';
+        while (start < Math.min(end, this.length)) {
+            yield* this.load(start);
+            if (start >= this.end)
+                break;
+            const stop = Math.min(end, this.start + this.window.length);
+            result += this.window.slice(start - this.start, stop - this.start);
+            start = stop;
+        }
+        return result;
+    }
+    *charCodeAt(offset) {
+        return (yield* this.slice(offset, offset + 1)).charCodeAt(0);
+    }
+    *startsWith(value, offset) {
+        for (let index = 0; index < value.length; index++) {
+            if ((yield* this.charCodeAt(offset + index)) !== value.charCodeAt(index))
+                return false;
+        }
+        return true;
+    }
+    *indexOf(value, offset, end = Infinity) {
+        let tail = '';
+        while (offset < end && (yield* this.has(offset))) {
+            const stop = Math.min(end, this.start + this.window.length);
+            const part = tail + this.window.slice(offset - this.start, stop - this.start);
+            const found = part.indexOf(value);
+            if (found >= 0)
+                return offset - tail.length + found;
+            tail = value.length > 1 ? part.slice(-(value.length - 1)) : '';
+            offset = stop;
+        }
+        return -1;
+    }
+}

package/dist/xml-ast/stream.d.ts

@@ -5,6 +5,7 @@ export type XmlStreamEvent = {
     readonly parent: XmlElement | undefined;
 } | {
     readonly type: "content";
+    readonly continuation?: boolean;
     readonly content: Exclude<XmlContent, XmlElement>;
     readonly parent: XmlElement | undefined;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-fs",
-  "version": "0.1.812",
+  "version": "0.1.813",
   "description": "Composable filesystem with a portable core and explicit Node adapters",
   "type": "module",
   "license": "MIT",