@jini-ai/vibecoding 0.4.0

package/dist/core/target.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @module core/target
+ *
+ * `EditTarget` — the one seam between this package's loop and whatever is being authored.
+ *
+ * Four operations cover the artifact (list / read / replace / snapshot), plus `restore` as
+ * snapshot's counterpart and `validate` as the guard around `replace`. That set was arrived at by
+ * tracing two shipped AI app-builders end to end and then trying to break it: creation, deletion,
+ * ordering, cross-part moves and binary parts were all predicted to leak through and none of them
+ * did. `replace` being an upsert absorbs creation; deletion and ordering turn out to be host
+ * concerns that no model-facing edit protocol needs to express.
+ *
+ * ## Why `validate` exists, and why it takes the whole prospective artifact
+ *
+ * Neither reference implementation validates writes at all. They get away with it because their
+ * unit is a whole file, and **a malformed file cannot corrupt another file's syntax**. That
+ * property does not survive the move to sub-document parts: a tagged region lives inside one
+ * shared document, so a single unbalanced tag corrupts everything after it. Nothing in either
+ * codebase solves this, so there was nothing to copy — it is the one genuinely new piece here.
+ *
+ * It receives the **whole prospective artifact**, not the part in isolation, because a fragment
+ * that is well-formed on its own can still break the document it lands in — a table cell outside a
+ * table, a region that closes a parent's tag. Validating the part alone would pass both.
+ *
+ * ## What is deliberately absent
+ *
+ * There are no verbs for running processes, installing dependencies, or building. Those are real
+ * needs for a file-tree host and they belong to a separate execution layer — putting them here
+ * would make the port undescribable for hosts that have no such tier, which is precisely the
+ * over-fitting this seam exists to prevent. Their absence is a design decision, not a gap.
+ */
+import type { PartId, PartRef, Snapshot, ValidationResult } from "./types.js";
+/**
+ * The host-supplied artifact port.
+ *
+ * Implementations are expected to be small: a file-tree host maps parts to files, a
+ * single-document host maps them to addressable regions. Nothing here assumes a filesystem, a
+ * DOM, or a framework.
+ */
+export interface EditTarget {
+    /**
+     * Every part a model may currently be asked to rewrite.
+     *
+     * This is the allowlist. A part omitted here is structurally unaddressable rather than merely
+     * discouraged — which is where scope discipline actually comes from. Prompt severity is not a
+     * substitute, and measurably is not one: a shipped builder with three prompt variants enforces
+     * identical scope rules with wildly different tone, because the constraint lives in the
+     * addressing, not the wording.
+     */
+    listParts(): Promise<readonly PartRef[]>;
+    /** Current content of one part. Rejects if `id` was not published by `listParts`. */
+    readPart(args: {
+        readonly id: PartId;
+    }): Promise<string>;
+    /**
+     * Write one part's content, creating it if absent — this is an **upsert**.
+     *
+     * Callers must not invoke this directly when a `validate` implementation exists; go through the
+     * apply loop, which validates first. Implementations should assume `content` is model-authored
+     * and therefore arbitrary.
+     */
+    replacePart(args: {
+        readonly id: PartId;
+        readonly content: string;
+    }): Promise<void>;
+    /** Capture every part's content. See `Snapshot` — data only, never execution state. */
+    snapshot(): Promise<Snapshot>;
+    /**
+     * Restore previously captured content.
+     *
+     * Returns once the data is back. Any downstream execution state is the host's to re-sync
+     * afterwards; this call makes no claim about it.
+     */
+    restore(args: {
+        readonly snapshot: Snapshot;
+    }): Promise<void>;
+    /**
+     * Decide whether a prospective change may be committed.
+     *
+     * Called with the artifact **as it would be** if `id` were replaced by `content`. A host whose
+     * parts cannot corrupt one another (a file tree, typically) may return `{ ok: true }`
+     * unconditionally; the cost of the hook is then a function call.
+     *
+     * A rejection's `reason` is fed to the model as its next turn, so it should describe the defect
+     * in terms the model can act on.
+     */
+    validate(candidate: {
+        readonly id: PartId;
+        readonly content: string;
+    }): Promise<ValidationResult>;
+}
+//# sourceMappingURL=target.d.ts.map

package/dist/core/target.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=target.js.map

package/dist/core/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @module core/types
+ *
+ * The vocabulary of a conversational authoring session, deliberately independent of *what* is
+ * being authored.
+ *
+ * The whole design rests on one observation: every AI app-builder differs at exactly one place —
+ * the artifact being edited. One tool edits a file tree; another edits a single markup document.
+ * The conversation, the streaming, the undo, and the preview are the same in all of them. So this
+ * package owns the loop and knows nothing about the target, which reaches it as a small port
+ * (see `./target.ts`).
+ *
+ * Terminology: an artifact is made of **parts**. A part is the unit a model may be asked to
+ * rewrite — a file for a file-tree host, a tagged region for a single-document host. Parts are
+ * addressed by an opaque `PartId` that the host publishes; a caller never supplies a selector or a
+ * path of its own devising.
+ */
+/**
+ * An opaque handle to one editable part, minted and published by the host.
+ *
+ * It is an **allowlist entry, not a query**. A model or caller may only name an id the host has
+ * already listed, which is what keeps a model-authored string from becoming a path traversal or an
+ * arbitrary DOM selector. Hosts that expose filesystem paths or CSS selectors as ids are
+ * responsible for validating them at the boundary before publishing them.
+ */
+export type PartId = string;
+/** One editable part as advertised to the model, without its content. */
+export interface PartRef {
+    /** The host-published handle used to read or replace this part. */
+    readonly id: PartId;
+    /**
+     * Optional host-meaningful category (e.g. a language, a region role). Purely descriptive —
+     * the loop never branches on it, it exists so a host can shape its own prompt.
+     */
+    readonly kind?: string;
+    /**
+     * Optional human-facing label. Host-authored and therefore **untrusted** for display: treat it
+     * as text, never as markup.
+     */
+    readonly label?: string;
+}
+/**
+ * A point-in-time copy of every part's content.
+ *
+ * Deliberately a flat id → content map and nothing more. Two consequences worth stating, because
+ * the reference implementation this shape was taken from conflates them:
+ *
+ * 1. **A snapshot restores DATA, never an execution environment.** A host with downstream state —
+ *    a dev server, a build, an installed dependency tree — re-syncs itself *after* `restore`
+ *    returns. If this type implied "and everything depending on these parts works again," it would
+ *    be promising something it cannot deliver for any host but the simplest.
+ * 2. It carries no ordering and no tree structure. A host that needs those reconstructs them from
+ *    its own ids, which it minted and therefore understands.
+ */
+export interface Snapshot {
+    /** Identifies this snapshot within a session. Assigned by the caller that took it. */
+    readonly id: string;
+    /** Every part's content at capture time, keyed by `PartId`. */
+    readonly parts: Readonly<Record<PartId, string>>;
+}
+/** A host's verdict on a prospective change, returned by `EditTarget.validate`. */
+export type ValidationResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    /**
+     * Why the change was refused, phrased for the **model** rather than for a log. This string
+     * is fed back as the next turn's input, so it should name the defect concretely
+     * (e.g. "unclosed <section> — the document no longer parses") rather than say "invalid".
+     */
+    readonly reason: string;
+};
+/** What happened to one `replace` attempt. */
+export type ApplyOutcome = {
+    readonly status: "applied";
+    readonly id: PartId;
+} | {
+    readonly status: "rejected";
+    readonly id: PartId;
+    readonly reason: string;
+} | {
+    readonly status: "failed";
+    readonly id: PartId;
+    readonly error: Error;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.js

@@ -0,0 +1,19 @@
+/**
+ * @module core/types
+ *
+ * The vocabulary of a conversational authoring session, deliberately independent of *what* is
+ * being authored.
+ *
+ * The whole design rests on one observation: every AI app-builder differs at exactly one place —
+ * the artifact being edited. One tool edits a file tree; another edits a single markup document.
+ * The conversation, the streaming, the undo, and the preview are the same in all of them. So this
+ * package owns the loop and knows nothing about the target, which reaches it as a small port
+ * (see `./target.ts`).
+ *
+ * Terminology: an artifact is made of **parts**. A part is the unit a model may be asked to
+ * rewrite — a file for a file-tree host, a tagged region for a single-document host. Parts are
+ * addressed by an opaque `PartId` that the host publishes; a caller never supplies a selector or a
+ * path of its own devising.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/html/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module html
+ *
+ * The single-document `EditTarget`: parts are tagged regions of one HTML document.
+ *
+ * Framework-free like `/core` — the HTML parser arrives as an injected port rather than a
+ * dependency, so this entry point stays usable from a server, a worker or a browser without
+ * dragging a parser into any of them.
+ */
+export type { HtmlDocumentStore, HtmlRegionParser, HtmlRegionTargetDeps, HtmlRegionTargetOptions, ParsedRegion, } from "./regions.js";
+export { AGENT_ELEMENT_ATTRIBUTE, createHtmlRegionTarget, isValidRegionHandle, } from "./regions.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/html/index.js

@@ -0,0 +1,2 @@
+export { AGENT_ELEMENT_ATTRIBUTE, createHtmlRegionTarget, isValidRegionHandle, } from "./regions.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,10 @@
+/**
+ * @module html/node
+ *
+ * The Node-only `HtmlRegionParser` implementation for `../regions.js`'s injected port — parse5,
+ * because that dependency is the one thing keeping `./html` itself framework- and runtime-free. See
+ * `./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";
+//# sourceMappingURL=index.d.ts.map

package/dist/html/node/index.js

@@ -0,0 +1,10 @@
+/**
+ * @module html/node
+ *
+ * The Node-only `HtmlRegionParser` implementation for `../regions.js`'s injected port — parse5,
+ * because that dependency is the one thing keeping `./html` itself framework- and runtime-free. See
+ * `./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";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,12 @@
+import { isValidRegionHandle, type HtmlRegionParser } from "../regions.js";
+/**
+ * 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`)
+ */
+export declare function createParse5RegionParser(): HtmlRegionParser & Required<Pick<HtmlRegionParser, "checkWellFormed">>;
+export { isValidRegionHandle };
+//# sourceMappingURL=parse5-region-parser.d.ts.map

package/dist/html/node/parse5-region-parser.js

@@ -0,0 +1,213 @@
+/**
+ * @module html/node/parse5-region-parser
+ *
+ * The `HtmlRegionParser` (`../regions.js`) has no implementation anywhere until this file — this is
+ * it: a spec-compliant WHATWG HTML parser (parse5, the same one jsdom depends on), Node-only because
+ * parse5 is Node-only, which is why this lives behind `./html/node` rather than the dependency-free
+ * `./html` entry `regions.ts` itself ships from.
+ *
+ * ## Fragment, not document
+ *
+ * A host's "one HTML document" (per `regions.ts`'s own module doc) may genuinely be a whole page,
+ * but the shape this was built against is inner content only — a string meant to be spliced into an
+ * existing container, not a standalone `<html>` page. `parse5.parseFragment` (the same algorithm
+ * browsers use for `Element.innerHTML`) is the correct entry point for that shape, parsed against a
+ * `<div>` context element: a generic block container, matching how a real host embeds this content.
+ * Getting this choice right is not cosmetic — the fragment context materially changes recovery
+ * behavior (verified empirically; see the section below), so a `<template>` context (parse5's
+ * own default when none is given) would UNDER-detect a real failure mode this module exists to
+ * catch.
+ *
+ * ## — a tagged element the parser could not reliably locate must never be silently dropped
+ *
+ * `regions.ts`'s own contract states the requirement (`findRegions`'s doc: "must report ALL of
+ * them... a parser that filters them out silently defeats the allowlist check"). Silently omitting
+ * an unlocatable region is actively dangerous, not merely incomplete: the omitted handle vanishes
+ * from `listParts`'s next call, and the region's own multiset check (`regions.ts`'s `validate`) then
+ * reports the *next*, unrelated edit to that document as "removes existing handle" — a permanent
+ * lockout with a reason that misdescribes the actual defect, because nothing was removed; the parser
+ * lost track of something still in the DOM.
+ *
+ * **This was verified empirically against real parse5 output before being implemented — not
+ * inferred from parse5's docs alone.** Two distinct mechanisms were confirmed reachable:
+ *
+ * 1. **A located-but-incomplete node.** parse5's own docs state `sourceCodeLocation` is `undefined`
+ * for elements the parser implicitly created during tree correction; concretely, this shows up as
+ * a tagged element whose `sourceCodeLocation.endTag` is missing — an implicitly-closed element at
+ * EOF, or (structurally, always) a tagged void element (`<img>`, `<br>`,...), which has no
+ * content model and therefore can never have a closing tag to locate.
+ * 2. **A node dropped from the tree entirely — no location to inspect because no node exists.**
+ * Confirmed with a tagged `<td>` used outside a `<table>`, parsed with a `<div>` fragment context:
+ * the HTML5 "in body" insertion mode's table-tag handling is a spec-mandated "parse error, ignore
+ * the token" — the element (and its `data-agent-element` attribute) never enters the tree at all.
+ * Neither `sourceCodeLocationInfo` nor `onParseError` flags this case on its own (verified: this
+ * fixture produces zero `onParseError` entries), which is why this module cross-checks the raw
+ * source text's occurrence count against what the tree walk actually found, independent of
+ * parse5's own error stream.
+ *
+ * Both mechanisms are handled uniformly: `findRegions` throws (never returns a silently-shortened
+ * list), and `checkWellFormed` reports the same problem through the port's ordinary rejection
+ * channel so `regions.ts`'s `validate` can surface it as a model-facing reason before `findRegions`
+ * is ever reached a second time for the same prospective document.
+ *
+ * ## `checkWellFormed` is a courtesy diagnostic, not the safety mechanism
+ *
+ * Per the port's own doc: "omit the method entirely if the parser cannot distinguish a malformed
+ * document from a recovered one." parse5 genuinely cannot always tell, so `checkWellFormed` is
+ * honest about that — ordinary spec-compliant recovery that produces no `onParseError` entry (e.g.
+ * an implied `</p>` before a following block element) is allowed to pass. Only two things fail it:
+ * a location problem (above), or at least one genuine `onParseError` entry, phrased for the
+ * model. The handle-multiset check in `regions.ts`'s `validate` remains the actual security
+ * property; this method exists to give the model a better reason sooner, not to replace that check.
+ * See docs/decisions/DR-001-conservative-region-detection.md.
+ */
+import { defaultTreeAdapter, html, parseFragment } from "parse5";
+import { AGENT_ELEMENT_ATTRIBUTE, isValidRegionHandle } from "../regions.js";
+/**
+ * HTML5 void elements — no content model, so they can never have a closing tag for parse5 to
+ * locate. Tagging one with `data-agent-element` is a structural impossibility for a "region" (a
+ * span of editable inner content), not a parser-recovery accident, so it gets a distinct message.
+ */
+const VOID_ELEMENTS = new Set([
+    "area",
+    "base",
+    "br",
+    "col",
+    "embed",
+    "hr",
+    "img",
+    "input",
+    "link",
+    "meta",
+    "param",
+    "source",
+    "track",
+    "wbr",
+]);
+/** Matches `data-agent-element` as an attribute *name* only — deliberately not the value or its
+ * quoting style, so it survives single-quoted, double-quoted and unquoted attribute forms alike.
+ *
+ * This is a plain substring/regex scan of the raw source, the same cost/precision tradeoff
+ * `withFormGuardrail` ( Decision 8) makes for its own guardrail: a comment or script-text
+ * mention of the attribute name can inflate the count and cause an over-eager rejection, but that
+ * false positive is a safe failure mode (the model is asked to retry), whereas the false negative
+ * this check exists to catch — a genuinely dropped region — is not.
+ * See docs/decisions/DR-001-conservative-region-detection.md.
+ */
+const RAW_HANDLE_ATTRIBUTE_RE = new RegExp(`\\b${AGENT_ELEMENT_ATTRIBUTE}\\s*=`, "gi");
+function attributeValue(element, name) {
+    return element.attrs.find((a) => a.name === name)?.value;
+}
+/** Yields every element node in the tree, in document order, recursing into `<template>` content. */
+function* walkElements(node) {
+    if ("tagName" in node)
+        yield node;
+    const children = "content" in node ? node.content.childNodes : "childNodes" in node ? node.childNodes : undefined;
+    if (children === undefined)
+        return;
+    for (const child of children)
+        yield* walkElements(child);
+}
+/** Fresh `<div>` fragment-context element — see this module's doc for why `<div>`, not the default. */
+function divFragmentContext() {
+    return defaultTreeAdapter.createElement("div", html.NS.HTML, []);
+}
+/** A parse-error entry, phrased for the model rather than left as parse5's bare kebab-case code. */
+function describeParseError(error) {
+    return `${error.code.replace(/-/g, " ")} near character ${error.startOffset}`;
+}
+/**
+ * One parse pass, shared by `findRegions` and `checkWellFormed` so both methods judge the same
+ * parse5 run rather than parsing the document twice with a chance of disagreeing.
+ *
+ * @complexity Linear in document size: one parse5 pass plus one tree walk plus one regex scan.
+ */
+function analyzeDocument(html_) {
+    const parseErrorReasons = [];
+    const fragment = parseFragment(divFragmentContext(), html_, {
+        sourceCodeLocationInfo: true,
+        onParseError: (error) => parseErrorReasons.push(describeParseError(error)),
+    });
+    const regions = [];
+    let locationProblem;
+    for (const element of walkElements(fragment)) {
+        const handle = attributeValue(element, AGENT_ELEMENT_ATTRIBUTE);
+        if (handle === undefined)
+            continue;
+        if (locationProblem !== undefined)
+            continue; // Already failed; stop accumulating regions.
+        const location = element.sourceCodeLocation;
+        if (location === null || location === undefined || location.startTag === undefined) {
+            locationProblem =
+                `a "${AGENT_ELEMENT_ATTRIBUTE}" region ("${handle}") could not be located in the document — ` +
+                    "the parser's error-recovery rules likely dropped or repositioned it. Rewrite the document " +
+                    "so this element is reachable in ordinary document structure (for example, not a table-only " +
+                    "tag used outside a <table>).";
+            continue;
+        }
+        if (location.endTag === undefined) {
+            locationProblem = VOID_ELEMENTS.has(element.tagName)
+                ? `"${handle}" tags a <${element.tagName}> element, which is void and has no inner content — ` +
+                    `void elements cannot be a ${AGENT_ELEMENT_ATTRIBUTE} region`
+                : `a "${AGENT_ELEMENT_ATTRIBUTE}" region ("${handle}") has no closing tag the parser could ` +
+                    "locate — its content boundaries cannot be determined safely. Close the tag explicitly.";
+            continue;
+        }
+        regions.push({
+            handle,
+            innerStart: location.startTag.endOffset,
+            innerEnd: location.endTag.startOffset,
+            ...(attributeValue(element, "data-agent-role") === undefined
+                ? {}
+                : { role: attributeValue(element, "data-agent-role") }),
+            ...(attributeValue(element, "data-agent-label") === undefined
+                ? {}
+                : { label: attributeValue(element, "data-agent-label") }),
+        });
+    }
+    if (locationProblem === undefined) {
+        const rawMentions = html_.match(RAW_HANDLE_ATTRIBUTE_RE)?.length ?? 0;
+        if (rawMentions > regions.length) {
+            locationProblem =
+                `the source mentions ${AGENT_ELEMENT_ATTRIBUTE} ${rawMentions} time(s) but only ` +
+                    `${regions.length} could be located in the parsed document — the parser's error-recovery ` +
+                    "rules likely dropped one entirely (a common cause: a table-only tag, such as <td>, used " +
+                    "outside a <table>). Rewrite the document so every tagged element sits in ordinary, " +
+                    "non-table-recovery document structure.";
+        }
+    }
+    return locationProblem === undefined
+        ? { regions, parseErrorReasons }
+        : { regions, locationProblem, parseErrorReasons };
+}
+/**
+ * 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`)
+ */
+export function createParse5RegionParser() {
+    return {
+        findRegions({ html: html_ }) {
+            const { regions, locationProblem } = analyzeDocument(html_);
+            if (locationProblem !== undefined)
+                throw new Error(locationProblem);
+            return regions;
+        },
+        checkWellFormed({ html: html_ }) {
+            const { locationProblem, parseErrorReasons } = analyzeDocument(html_);
+            if (locationProblem !== undefined)
+                return { ok: false, reason: locationProblem };
+            if (parseErrorReasons.length > 0) {
+                return { ok: false, reason: `the document does not parse cleanly: ${parseErrorReasons.join("; ")}` };
+            }
+            return { ok: true };
+        },
+    };
+}
+// Re-exported so a caller can reuse the same grammar this parser's handles are checked against
+// without importing `../regions.js` directly for one symbol.
+export { isValidRegionHandle };
+//# sourceMappingURL=parse5-region-parser.js.map

package/dist/html/regions.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @module html/regions
+ *
+ * An `EditTarget` whose parts are **tagged regions of one HTML document** — the shape a
+ * single-document host needs, as opposed to the file tree a multi-file host edits.
+ *
+ * This is the target the port was designed against but never had an implementation for, and it is
+ * where `validate` stops being a formality: a file cannot corrupt another file's syntax, but a
+ * region shares one document with every other region, so one unbalanced tag corrupts everything
+ * after it.
+ *
+ * ## Addressing reuses `data-agent-element`, deliberately
+ *
+ * Handles are the existing `data-agent-element` convention (`@jini-ai/agentic`'s
+ * `element-handles.ts`), including its handle grammar — lowercase words joined by single hyphens,
+ * bounded length, and no quote, bracket, backslash or whitespace. That grammar exists so a handle
+ * cannot break out of the attribute selector it gets interpolated into, and it serves equally well
+ * here: a `PartId` a model can name is a string a model authored.
+ *
+ * Minting a new product-specific attribute was considered and rejected twice over — the convention
+ * already exists with `region` as a defined role, and a product-named attribute could not live in
+ * this workspace anyway.
+ *
+ * ## THE SECURITY PROPERTY: a model may not extend its own allowlist
+ *
+ * `listParts` is an allowlist, and an allowlist a model can write to is not an allowlist. If a model
+ * may edit region `hero`, and it writes `data-agent-element="anything"` inside `hero`, then the very
+ * next `listParts()` publishes `anything` as addressable — the model has granted itself a new part
+ * without the host ever deciding to. Every subsequent turn inherits the expanded surface.
+ *
+ * So `validate` refuses any candidate whose prospective document does not carry **exactly the same
+ * multiset of handles** as the current one. That covers all three ways this breaks: a handle
+ * invented, a handle deleted, and a handle duplicated (which would make an id ambiguous and let one
+ * write land somewhere the host did not intend). Neither reference implementation has an equivalent
+ * check, because neither has sub-document parts — there was nothing to copy.
+ *
+ * ## Writes are byte-preserving outside the edited region
+ *
+ * `replacePart` is a string splice across the region's inner offsets: everything outside those
+ * offsets is carried through untouched, byte for byte. This is a deliberate departure from the
+ * visual editor studied for this design, which re-parses, regenerates and pretty-prints the whole
+ * file on every write — semantically faithful, but it reformats the document out from under the
+ * author, and it does so even to files it failed to parse. A host that stores author-written HTML
+ * cannot accept that.
+ *
+ * ## The parser is injected, not imported
+ *
+ * This package is `"runtime": "universal"`, and no HTML parser exists anywhere in this workspace, so
+ * hard-wiring one would either make this module Node-only or push a parser into every browser
+ * bundle. It arrives as a port instead — the same choice, for the same reason, that `EditTarget`
+ * itself is a port. A browser host can satisfy it with `DOMParser`; a server host with whatever it
+ * already depends on.
+ */
+import type { EditTarget } from "../core/target.js";
+/** The attribute that publishes a region's handle. Mirrors `@jini-ai/agentic`'s convention. */
+export declare const AGENT_ELEMENT_ATTRIBUTE = "data-agent-element";
+/** Whether `handle` is a syntactically valid region handle. */
+export declare function isValidRegionHandle({ handle }: {
+    readonly handle: string;
+}): boolean;
+/** One tagged region located in a document, as reported by the injected parser. */
+export interface ParsedRegion {
+    /** The `data-agent-element` value. */
+    readonly handle: string;
+    /** The `data-agent-role` value, if the markup carries one. */
+    readonly role?: string;
+    /** The `data-agent-label` value, if present. Page-authored and therefore untrusted for display. */
+    readonly label?: string;
+    /** Index of the first character of the region's INNER content. */
+    readonly innerStart: number;
+    /** Index one past the last character of the region's inner content. */
+    readonly innerEnd: number;
+}
+/**
+ * The host-supplied HTML parser.
+ *
+ * Implementations must report regions in document order with accurate inner offsets — every write
+ * this module performs is a splice across those offsets, so an incorrect offset corrupts the
+ * document silently.
+ */
+export interface HtmlRegionParser {
+    /**
+     * Locate every element carrying `data-agent-element`.
+     *
+     * Must report ALL of them, including duplicates and handles that fail `isValidRegionHandle` —
+     * this module needs to *see* invalid and duplicated handles in order to refuse them. A parser
+     * that filters them out silently defeats the allowlist check.
+     */
+    findRegions(args: {
+        readonly html: string;
+    }): readonly ParsedRegion[];
+    /**
+     * Optional structural check on a whole document.
+     *
+     * Return a reason phrased for the MODEL, since it is fed back as the next turn's input. Omit the
+     * method entirely if the parser cannot distinguish a malformed document from a recovered one —
+     * that is honest, and the handle-set check below still catches the damage that matters most.
+     */
+    checkWellFormed?(args: {
+        readonly html: string;
+    }): {
+        readonly ok: true;
+    } | {
+        readonly ok: false;
+        readonly reason: string;
+    };
+}
+/** Where the document itself lives. The host owns storage; this module never assumes one. */
+export interface HtmlDocumentStore {
+    read(): Promise<string>;
+    write(args: {
+        readonly html: string;
+    }): Promise<void>;
+}
+export interface HtmlRegionTargetOptions {
+    /**
+     * Reject a proposed region body larger than this many characters.
+     *
+     * Content is model-authored and arrives over a network boundary; without a bound, one turn can
+     * grow the stored document without limit. Defaults to 256 KiB, generous for a page region.
+     */
+    readonly maxPartLength?: number;
+}
+export interface HtmlRegionTargetDeps {
+    readonly store: HtmlDocumentStore;
+    readonly parser: HtmlRegionParser;
+}
+/**
+ * Build an `EditTarget` over the tagged regions of one HTML document.
+ *
+ * @param deps - document storage and an HTML parser, both host-supplied.
+ * @param options - optional region size limit, separate from the required ports.
+ * @returns a target ready to hand to `applyEdit`/`applyEdits` or to `createEditHistory`.
+ * @complexity 4
+ */
+export declare function createHtmlRegionTarget(deps: HtmlRegionTargetDeps, options?: HtmlRegionTargetOptions): EditTarget;
+//# sourceMappingURL=regions.d.ts.map