@jini-ai/vibecoding 0.6.10 → 0.6.12

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 0.6.12
+
+### Patch Changes
+
+- Updated dependencies
+  - @jini-ai/platform@0.6.12
+  - @jini-ai/core@0.6.12
+
+## 0.6.11
+
+### Patch Changes
+
+- `./node` file-tree projects with revision undo and a React-free `./session`; `./html` gains a non-throwing region scan and pure region edits; async atomic writes in platform.
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+  - @jini-ai/core@0.6.11
+  - @jini-ai/platform@0.6.11
+
+## Unreleased
+
+### Added
+
+- Add `./node` real file-tree projects with content-addressed revisions, pending-journal recovery,
+  external-drift capture, optional whole-candidate validation and exact pointer-part undo/redo.
+- Add React-free `./session` with injectable project history/mutation; preserve React re-exports.
+- Expose both retained history stacks for object/manifest garbage collection.
+- Export non-throwing `scanHtmlRegions` from `./html/node`, with source-ordered inner/outer offsets,
+  tags, per-region problems, document diagnostics and top-level tagging metadata.
+- Export pure lookup, inner replacement, whole-element move, ambiguity comparison, handle listing
+  and heading-based tagging suggestions from `./html`; slugification is supplied by the host.
+
+### Changed
+
+- Delegate the strict parse5 parser to the scan while preserving target validation. Ignore handle
+  examples in comments and literal-text bodies (including `noscript`), and collapse reconstructed
+  formatting clones to one unsafe address. The scan path keeps safe regions usable alongside
+  malformed markup.
+- HTML5 recovery differs from Tovu's former lexical scanner: non-void self-closing syntax remains
+  open, an explicit later close permits editing, unclosed top-level elements use recovered advice
+  boundaries, malformed tokens follow parse5 recovery, and unquoted/upper-case handle attributes
+  are recognized.
+
 ## 0.6.10
 
 ### Patch Changes

package/README.md

@@ -33,10 +33,12 @@ Neither reimplements the loop.
 | `./core` | universal | the loop and the `EditTarget` port — no React, no Node, no DOM |
 | `./html` | universal | the tagged-region, single-HTML-document `EditTarget` (parser injected) |
 | `./html/node` | node | a parse5-backed `HtmlRegionParser` for `./html`, for a Node host |
-| `./react` | browser | `VibecodingSession`, the `@jini-ai/core`-registrable tool set, and the file-viewer/renderer components — see `src/react/README` section below |
+| `./session` | universal | Sessions and registered/direct tools; no React import |
+| `./node` | node | Real local file trees, whole-turn validation, capture, journal recovery and exact history |
+| `./react` | browser | Session/tool re-exports, hooks and file-viewer/renderer components |
 
-`./node` (filesystem targets) is planned and deliberately not present yet — building it is a
-separate `EditTarget` implementation, not a `./react` concern. React is an **optional** peer of
+`./node` supplies a file-tree project behind the same `EditTarget` port. The host selects the
+real working directory and a private state directory outside the app root. React is an **optional** peer of
 `./react`: keeping the framework-free half importable without a UI dependency is the point of the
 split, not a stylistic preference, and importing `.`/`./core`/`./html` never pulls React in.
 
@@ -108,7 +110,7 @@ React components keep their props and framework callbacks keep the framework's s
 | Handle check / parser | `isValidRegionHandle({ handle })`, `createParse5RegionParser()` |
 | Parser port | `parser.findRegions({ html })`, `parser.checkWellFormed?.({ html })` |
 | Document store port | `store.read()`, `store.write({ html })` |
-| Session | `createVibecodingSession({ target }, { historyOptions })` |
+| Session | `createVibecodingSession({ target }, { historyOptions?, history?, applyTurn? })` |
 | Session methods | `session.subscribe({ listener })`, `session.readPart({ id })`, `session.applyEdits({ edits }, { label })`, `session.restoreSnapshot({ snapshot })` |
 | React hook | `useVibecodingSession({ session })`; its `readPart` and `applyEdits` actions use the session method shapes |
 | Registered tools | `createVibecodingToolRegistrations({ session }, { policy })` |
@@ -117,9 +119,9 @@ React components keep their props and framework callbacks keep the framework's s
 `createParse5RegionParser()` always provides `checkWellFormed({ html })`; optional chaining
 is only needed when working with the generic `HtmlRegionParser` port.
 
-`VibecodingSessionArgs` holds the required target; `VibecodingSessionOptions` now holds only
-optional `historyOptions`. `UseVibecodingSessionArgs` and `VibecodingToolArgs` describe the required
-session port. All are exported from `./react`. Tool input JSON remains unchanged: `edits` and
+`VibecodingSessionArgs` holds the required target; `VibecodingSessionOptions` holds optional
+`historyOptions`, injected `history` and whole-turn `applyTurn`. `UseVibecodingSessionArgs` and `VibecodingToolArgs` describe the required
+session port. All are exported from `./session` and re-exported from `./react`. Tool input JSON remains unchanged: `edits` and
 `label` still belong to the same tool input object.
 
 ```ts
@@ -152,3 +154,45 @@ belong to the host. Integration verification is deferred by owner directive; see
 ## Design decisions
 
 - [Ambiguous region detection refuses rather than dropping a handle](docs/decisions/DR-001-conservative-region-detection.md).
+
+
+## Local app projects
+
+```ts
+import { openFileTreeProject } from '@jini-ai/vibecoding/node';
+import { createVibecodingSession } from '@jini-ai/vibecoding/session';
+
+const project = await openFileTreeProject({
+  root: appDirectory,
+  stateDir: privateHostStateDirectory, // outside appDirectory: dev servers must never serve history
+  policy: { allows: ({ relativePath }) => allowedAppPath(relativePath) },
+  // Optional validator.validate({candidate, signal}) checks the entire candidate once.
+});
+const session = createVibecodingSession({ target: project.target }, {
+  history: project.history,
+  applyTurn: project.applyEdits,
+});
+await project.applyTurn({
+  expectedRevision: await project.capture(),
+  changes: [{ op: 'create', relativePath: 'src/App.tsx', content: appSource }],
+});
+await session.undo(); // removes the created file and its empty managed folders
+await project.close();
+```
+
+PartIds are canonical relative paths. Explicit creates need no reservation; replacements/deletes
+must name existing parts. The root remains the real working tree watched by Vite and other local
+dev servers; dependencies, secrets and generated output are excluded. `capture()` records npm,
+editor or user drift before a turn/undo so it is not silently overwritten. Revisions deduplicate
+unchanged bytes in objects plus manifests. A pending journal rolls interrupted materialization
+forward on reopen. History is session-local; another writer's generation clears it and returns `CONFLICT`.
+
+Defaults: 2000 files, 2 MiB/file, 64 MiB/tree, depth 32, 100 changes/turn, 30-second validation,
+50 history entries, and 200-character relative paths. A host allowlist always intersects mandatory
+exclusions. Candidate-wide case/NFC checks permit case-only rename turns; nonportable names and
+physical escapes refuse. Snapshots may expire once no longer retained by current/undo/redo.
+
+Read [Node projects](docs/spec/api.spec.md#node-projects), the
+[error table](docs/spec/errors.spec.md#node-project-errors), and
+[DR-002](docs/decisions/DR-002-file-tree-revisions.md) for recovery and authority limits. No process,
+package-install, compiler, preview or deployment implementation is included in this step.

package/dist/core/history.d.ts

@@ -127,6 +127,8 @@ export interface EditHistory {
     }): Promise<HistoryEntry | null>;
     /** Undoable entries, oldest first. For rendering a history UI; do not mutate. */
     entries(): readonly HistoryEntry[];
+    /** Entries in both stacks, for pinning revisions during garbage collection. */
+    retainedEntries(): readonly HistoryEntry[];
     /** Discard both stacks. */
     clear(): void;
 }

package/dist/core/history.js

@@ -123,6 +123,7 @@ export function createEditHistory({ target }, options = {}) {
             return entry;
         },
         entries: () => [...undoStack],
+        retainedEntries: () => [...undoStack, ...redoStack],
         clear() {
             undoStack.length = 0;
             redoStack.length = 0;

package/dist/core/index.d.ts

@@ -16,4 +16,5 @@ export type { ProposedEdit } from "./apply.js";
 export { applyEdit, applyEdits, correctionsFor } from "./apply.js";
 export type { EditHistory, EditHistoryOptions, HistoryEntry, PartChange } from "./history.js";
 export { createEditHistory } from "./history.js";
+export * from './project.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -1,3 +1,4 @@
 export { applyEdit, applyEdits, correctionsFor } from "./apply.js";
 export { createEditHistory } from "./history.js";
+export * from './project.js';
 //# sourceMappingURL=index.js.map

package/dist/core/project.d.ts

@@ -0,0 +1,96 @@
+import type { EditHistory } from './history.js';
+import type { EditTarget } from './target.js';
+import type { ApplyOutcome } from './types.js';
+import type { ProposedEdit } from './apply.js';
+/** Creates name a relative path; existing files use the same canonical path as PartId. */
+export type FileChange = {
+    readonly op: 'create';
+    readonly relativePath: string;
+    readonly content: string;
+} | {
+    readonly op: 'replace';
+    readonly id: string;
+    readonly content: string;
+} | {
+    readonly op: 'delete';
+    readonly id: string;
+};
+export interface RevisionToken {
+    readonly revisionId: string;
+    readonly generation: number;
+}
+export interface ProjectDiagnostic {
+    readonly code: string;
+    readonly message: string;
+    readonly relativePath?: string;
+}
+/** Byte reads return copies, so a validator cannot mutate the eventual commit. */
+export interface ProjectCandidate {
+    readonly paths: readonly string[];
+    readBytes(input: {
+        readonly relativePath: string;
+    }, options?: Record<string, never>): Promise<Uint8Array>;
+}
+export interface ProjectValidator {
+    validate(input: {
+        readonly candidate: ProjectCandidate;
+        readonly signal: AbortSignal;
+    }, options?: Record<string, never>): Promise<{
+        readonly ok: boolean;
+        readonly diagnostics?: readonly ProjectDiagnostic[];
+    }>;
+}
+export type ProjectErrorCode = 'CONFLICT' | 'INVALID_PATH' | 'INVALID_CHANGE' | 'LIMIT' | 'CANCELLED' | 'VALIDATION' | 'STORAGE' | 'CORRUPT' | 'CLOSED' | 'SNAPSHOT_EXPIRED';
+/** Stable project-boundary errors; native causes remain available to the host. */
+export declare class ProjectError extends Error {
+    constructor(input: {
+        code: ProjectErrorCode;
+        message: string;
+        cause?: unknown;
+    });
+    readonly code: ProjectErrorCode;
+}
+export interface ProjectLimits {
+    readonly maxFiles: number;
+    readonly maxFileBytes: number;
+    readonly maxTreeBytes: number;
+    readonly maxDepth: number;
+    readonly maxChanges: number;
+    readonly validationTimeoutMs: number;
+}
+export type TurnResult = {
+    readonly status: 'committed' | 'unchanged' | 'rejected';
+    readonly revision: RevisionToken;
+    readonly diagnostics: readonly ProjectDiagnostic[];
+};
+export interface ProjectSnapshot {
+    readonly revisionId: string;
+}
+export interface FileTreeProject {
+    readonly target: EditTarget;
+    readonly history: EditHistory;
+    getRevision(): Promise<RevisionToken>;
+    /** Captures external edits as an ordinary undoable revision, without rewriting the tree. */
+    capture(): Promise<RevisionToken>;
+    applyTurn(input: {
+        readonly expectedRevision: RevisionToken;
+        readonly changes: readonly FileChange[];
+    }, options?: {
+        readonly label?: string;
+        readonly signal?: AbortSignal;
+    }): Promise<TurnResult>;
+    /** Session adapter: replacements share the same whole-candidate validation and history. */
+    applyEdits(input: {
+        readonly edits: readonly ProposedEdit[];
+    }, options?: {
+        readonly label?: string;
+    }): Promise<readonly ApplyOutcome[]>;
+    snapshot(): Promise<ProjectSnapshot>;
+    restore(input: {
+        readonly snapshot: ProjectSnapshot;
+    }, options?: {
+        readonly label?: string;
+    }): Promise<RevisionToken>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=project.d.ts.map

package/dist/core/project.js

@@ -0,0 +1,10 @@
+/** Stable project-boundary errors; native causes remain available to the host. */
+export class ProjectError extends Error {
+    constructor(input) {
+        super(input.message, { cause: input.cause });
+        this.name = 'ProjectError';
+        this.code = input.code;
+    }
+    code;
+}
+//# sourceMappingURL=project.js.map

package/dist/html/edit.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Pure region edits over a caller-owned scan. Offsets always index the original string (UTF-16
+ * code units); scan each new string once and keep storage, version checks and policy in the host.
+ * Unlike the EditTarget allowlist, these helpers permit adding/removing handles. The ambiguity
+ * comparison only identifies handles whose duplicate count increases.
+ *
+ * @example
+ * const found = locateRegion({ scan, handle: "hero" });
+ * if ("region" in found) replaceRegionInner({ html, region: found.region, fragment: "<h1>Hi</h1>" });
+ */
+import type { ParsedRegion } from "./regions.js";
+/** A discovered handle, including unsafe regions so reads never silently lose an address. */
+export interface ScannedRegion extends ParsedRegion {
+    readonly tag: string;
+    /** Outer offsets; -1 means parse5 could not locate the boundary. Never splice a problem region. */
+    readonly start: number;
+    readonly end: number;
+    /** Why this region cannot safely be replaced or moved. */
+    readonly problem?: string;
+}
+/** A direct fragment child, used for host tagging advice; implicit closes are allowed here. */
+export interface HtmlTopLevelElement {
+    readonly tag: string;
+    readonly handle?: string;
+    readonly start: number;
+    readonly end: number;
+    readonly innerStart: number;
+    readonly innerEnd: number;
+}
+/** Reusable analysis of exactly one source string. Parse errors are diagnostics, not read failures. */
+export interface HtmlRegionScan {
+    readonly regions: readonly ScannedRegion[];
+    readonly topLevel: readonly HtmlTopLevelElement[];
+    /** A raw-source handle could not be accounted for in the recovered tree. */
+    readonly documentProblem?: string;
+    readonly parseErrorReasons?: readonly string[];
+}
+/** Why lookup could not identify a single safe span. Legacy handle values are deliberately retained. */
+export type RegionLookupProblem = {
+    readonly kind: "absent";
+    readonly available: readonly string[];
+} | {
+    readonly kind: "ambiguous";
+    readonly count: number;
+} | {
+    readonly kind: "not-replaceable";
+    readonly tag: string;
+};
+export type RegionLookup = {
+    readonly region: ScannedRegion;
+} | {
+    readonly problem: RegionLookupProblem;
+};
+/** Resolve one address, refusing duplicates and unsafe boundaries without throwing on reads. */
+export declare function locateRegion({ scan, handle }: {
+    readonly scan: HtmlRegionScan;
+    readonly handle: string;
+}, _options?: Record<string, never>): RegionLookup;
+/**
+ * Replace INNER content only: the addressed element, its handle and every surrounding byte survive.
+ * The region must be safely located in this exact html string; this helper performs no policy check.
+ */
+export declare function replaceRegionInner({ html, region, fragment }: {
+    readonly html: string;
+    readonly region: ParsedRegion;
+    readonly fragment: string;
+}, _options?: Record<string, never>): string;
+export type RegionMoveProblem = "self" | "into-itself";
+/**
+ * Move a WHOLE safely located element, carrying trailing whitespace (or leading whitespace at EOF).
+ * Refuse self/descendant destinations. Both regions must have been resolved from this exact source.
+ * Everything else retains its original bytes and order; an adjacent move may return identical HTML.
+ */
+export declare function moveRegion({ html, moving, target, placement }: {
+    readonly html: string;
+    readonly moving: ScannedRegion;
+    readonly target: ScannedRegion;
+    readonly placement: "before" | "after";
+}, _options?: Record<string, never>): {
+    readonly html: string;
+} | {
+    readonly problem: RegionMoveProblem;
+};
+/** Host-owned slug policy keeps suggestions compatible without adding a slugifier dependency. */
+export interface RegionHandleOptions {
+    readonly slugify: (text: string) => string;
+}
+/** A top-level element needing a handle, with a suggestion only when its own heading provides one. */
+export interface UntaggedSection {
+    readonly tag: string;
+    readonly suggestedHandle: string | undefined;
+}
+/**
+ * Derive a stable handle from the first heading, stripping inline tags and truncating to 48 chars.
+ * Never suggest positional handles: moving sections must not change their addresses. Collisions,
+ * absent headings and empty slugs get no suggestion; the host chooses its own slugification policy.
+ */
+export declare function suggestRegionHandle({ inner, taken }: {
+    readonly inner: string;
+    readonly taken: ReadonlySet<string>;
+}, { slugify }: RegionHandleOptions): string | undefined;
+/** Find untagged top-level content; reserve each suggestion so a batch never creates duplicates. */
+export declare function untaggedTopLevelSections({ html, scan }: {
+    readonly html: string;
+    readonly scan: HtmlRegionScan;
+}, options: RegionHandleOptions): readonly UntaggedSection[];
+/** Report newly worsened ambiguity, once per handle in after's source order; existing duplicates stay editable. */
+export declare function handlesMadeAmbiguous({ before, after }: {
+    readonly before: HtmlRegionScan;
+    readonly after: HtmlRegionScan;
+}, _options?: Record<string, never>): string[];
+/** All handles in source order, preserving duplicates, empty values and legacy grammar. */
+export declare function regionHandlesIn({ scan }: {
+    readonly scan: HtmlRegionScan;
+}, _options?: Record<string, never>): string[];
+//# sourceMappingURL=edit.d.ts.map

package/dist/html/edit.js

@@ -0,0 +1,103 @@
+/** Resolve one address, refusing duplicates and unsafe boundaries without throwing on reads. */
+export function locateRegion({ scan, handle }, _options = {}) {
+    const matches = scan.regions.filter((region) => region.handle === handle);
+    if (matches.length === 0)
+        return { problem: { kind: "absent", available: regionHandlesIn({ scan }) } };
+    if (matches.length > 1)
+        return { problem: { kind: "ambiguous", count: matches.length } };
+    const region = matches[0]; // Exactly one match on this branch.
+    if (region.problem !== undefined)
+        return { problem: { kind: "not-replaceable", tag: region.tag } };
+    return { region };
+}
+/**
+ * Replace INNER content only: the addressed element, its handle and every surrounding byte survive.
+ * The region must be safely located in this exact html string; this helper performs no policy check.
+ */
+export function replaceRegionInner({ html, region, fragment }, _options = {}) {
+    return html.slice(0, region.innerStart) + fragment + html.slice(region.innerEnd);
+}
+/** The end of the whitespace run adjoining an element, in either direction. */
+function whitespaceRun(html, from, direction) {
+    let cursor = from;
+    while (/\s/.test(html[direction === 1 ? cursor : cursor - 1] ?? ""))
+        cursor += direction;
+    return cursor;
+}
+/**
+ * Move a WHOLE safely located element, carrying trailing whitespace (or leading whitespace at EOF).
+ * Refuse self/descendant destinations. Both regions must have been resolved from this exact source.
+ * Everything else retains its original bytes and order; an adjacent move may return identical HTML.
+ */
+export function moveRegion({ html, moving, target, placement }, _options = {}) {
+    if (moving.start === target.start)
+        return { problem: "self" };
+    if (target.start > moving.start && target.end <= moving.end)
+        return { problem: "into-itself" };
+    let cutStart = moving.start;
+    const cutEnd = whitespaceRun(html, moving.end, 1);
+    if (cutEnd === moving.end)
+        cutStart = whitespaceRun(html, moving.start, -1);
+    const element = html.slice(moving.start, moving.end);
+    const gap = cutEnd > moving.end ? html.slice(moving.end, cutEnd) : html.slice(cutStart, moving.start);
+    const without = html.slice(0, cutStart) + html.slice(cutEnd);
+    const anchor = placement === "before" ? target.start : target.end;
+    const at = anchor >= cutEnd ? anchor - (cutEnd - cutStart) : anchor;
+    const piece = placement === "before" ? element + gap : gap + element;
+    return { html: without.slice(0, at) + piece + without.slice(at) };
+}
+const HEADING_PATTERN = /<h[1-6]\b[^>]*>([\s\S]*?)<\/h[1-6]>/i;
+/**
+ * Derive a stable handle from the first heading, stripping inline tags and truncating to 48 chars.
+ * Never suggest positional handles: moving sections must not change their addresses. Collisions,
+ * absent headings and empty slugs get no suggestion; the host chooses its own slugification policy.
+ */
+export function suggestRegionHandle({ inner, taken }, { slugify }) {
+    const heading = HEADING_PATTERN.exec(inner);
+    if (!heading)
+        return undefined;
+    const slug = slugify(heading[1].replace(/<[^>]*>/g, " ")).slice(0, 48).replace(/-+$/g, "");
+    if (slug === "" || taken.has(slug))
+        return undefined;
+    return slug;
+}
+// Stylesheets and metadata need no content address. Requiring nested elements to carry handles
+// would impose a stricter contract than "every top-level section" and make ordinary pages unusable.
+const UNTAGGABLE_TOP_LEVEL_ELEMENTS = new Set(["style", "script", "template", "link", "meta", "base", "title"]);
+/** Find untagged top-level content; reserve each suggestion so a batch never creates duplicates. */
+export function untaggedTopLevelSections({ html, scan }, options) {
+    const taken = new Set(regionHandlesIn({ scan }));
+    const offenders = [];
+    for (const element of scan.topLevel) {
+        if (element.handle !== undefined || UNTAGGABLE_TOP_LEVEL_ELEMENTS.has(element.tag))
+            continue;
+        const inner = html.slice(element.innerStart, element.innerEnd);
+        const suggestedHandle = suggestRegionHandle({ inner, taken }, options);
+        if (suggestedHandle !== undefined)
+            taken.add(suggestedHandle);
+        offenders.push({ tag: element.tag, suggestedHandle });
+    }
+    return offenders;
+}
+/** Count every discovered handle, including duplicates and unsafe regions. */
+function countHandles(scan) {
+    const counts = new Map();
+    for (const { handle } of scan.regions)
+        counts.set(handle, (counts.get(handle) ?? 0) + 1);
+    return counts;
+}
+/** Report newly worsened ambiguity, once per handle in after's source order; existing duplicates stay editable. */
+export function handlesMadeAmbiguous({ before, after }, _options = {}) {
+    const was = countHandles(before);
+    const offenders = [];
+    for (const [handle, count] of countHandles(after)) {
+        if (count > 1 && count > (was.get(handle) ?? 0))
+            offenders.push(handle);
+    }
+    return offenders;
+}
+/** All handles in source order, preserving duplicates, empty values and legacy grammar. */
+export function regionHandlesIn({ scan }, _options = {}) {
+    return scan.regions.map((region) => region.handle);
+}
+//# sourceMappingURL=edit.js.map

package/dist/html/index.d.ts

@@ -9,4 +9,6 @@
  */
 export type { HtmlDocumentStore, HtmlRegionParser, HtmlRegionTargetDeps, HtmlRegionTargetOptions, ParsedRegion, } from "./regions.js";
 export { AGENT_ELEMENT_ATTRIBUTE, createHtmlRegionTarget, isValidRegionHandle, } from "./regions.js";
+export type { HtmlRegionScan, HtmlTopLevelElement, RegionHandleOptions, RegionLookup, RegionLookupProblem, RegionMoveProblem, ScannedRegion, UntaggedSection, } from "./edit.js";
+export { handlesMadeAmbiguous, locateRegion, moveRegion, regionHandlesIn, replaceRegionInner, suggestRegionHandle, untaggedTopLevelSections, } from "./edit.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/html/index.js

@@ -1,2 +1,3 @@
 export { AGENT_ELEMENT_ATTRIBUTE, createHtmlRegionTarget, isValidRegionHandle, } from "./regions.js";
+export { handlesMadeAmbiguous, locateRegion, moveRegion, regionHandlesIn, replaceRegionInner, suggestRegionHandle, untaggedTopLevelSections, } from "./edit.js";
 //# sourceMappingURL=index.js.map

package/dist/html/node/index.d.ts

@@ -6,5 +6,6 @@
  * `./parse5-region-parser.ts` for the implementation and its findings.
  * See docs/decisions/DR-001-conservative-region-detection.md.
  */
-export { createParse5RegionParser, isValidRegionHandle } from "./parse5-region-parser.js";
+export { createParse5RegionParser, isValidRegionHandle, scanHtmlRegions } from "./parse5-region-parser.js";
+export type { HtmlRegionScan, HtmlTopLevelElement, ScannedRegion } from "../edit.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/html/node/index.js

@@ -6,5 +6,5 @@
  * `./parse5-region-parser.ts` for the implementation and its findings.
  * See docs/decisions/DR-001-conservative-region-detection.md.
  */
-export { createParse5RegionParser, isValidRegionHandle } from "./parse5-region-parser.js";
+export { createParse5RegionParser, isValidRegionHandle, scanHtmlRegions } from "./parse5-region-parser.js";
 //# sourceMappingURL=index.js.map

package/dist/html/node/parse5-region-parser.d.ts

@@ -1,11 +1,23 @@
+import type { HtmlRegionScan } from "../edit.js";
 import { isValidRegionHandle, type HtmlRegionParser } from "../regions.js";
+/**
+ * Scan once without throwing for malformed markup: unsafe regions carry their own problem, while
+ * unaccounted-for source handles produce documentProblem. Every offset indexes the untouched input.
+ * Comments/raw-text bodies are blanked by parse5's own locations before the raw-mention check.
+ * @example const scan = scanHtmlRegions({ html: '<section data-agent-element="hero">Hi</section>' });
+ * @complexity One parse and node walk, plus source-order sorting: O(n + r log r) for n source code
+ * units and r discovered elements. Masked ranges are disjoint, so blanking is linear in source size.
+ */
+export declare function scanHtmlRegions({ html: html_ }: {
+    readonly html: string;
+}, _options?: Record<string, never>): HtmlRegionScan;
 /**
  * Build the parse5-backed `HtmlRegionParser`. Stateless — a single instance is safe to share as a
  * module-level singleton across every call, per `./regions.js`'s injected-port contract.
  *
  * @returns a parser ready to hand to `createHtmlRegionTarget`, with `checkWellFormed` always
  * present even though the generic parser port allows implementations to omit it.
- * @complexity 1 (delegates entirely to `analyzeDocument`)
+ * @complexity 1 (delegates to `scanHtmlRegions`)
  */
 export declare function createParse5RegionParser(): HtmlRegionParser & Required<Pick<HtmlRegionParser, "checkWellFormed">>;
 export { isValidRegionHandle };