@jini-ai/vibecoding 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+## 0.4.0 — 2026-10-02
+
+### BREAKING
+
+- Pure kernel containment and isolated HTML/React entries remain; shared ports and public object-argument contracts replace local vocabulary.
+- Distribution includes runtime output, release documentation and required assets only. Process records and per-job neutrality checks are no longer part of the package surface.
+
+## Unreleased
+
+- Fixed compilation against the current core contracts: tool input errors use `{ message }`,
+  and registry integration tests use object arguments for registry creation and listing.
+  The parse5 factory return type now exposes its always-present `checkWellFormed` method.
+  Error messages and parser behavior are unchanged.
+
+- Integration follow-up: reconciled the `./core`, `./html`, `./html/node` and `./react`
+  surfaces, including HTML parser/storage ports, session/history, discoverable tool registrations,
+  direct tool runner, React hook and preview components. Export metadata and optional React peers
+  were already present and are retained. No version change or new dependency is required.
+- BREAKING: `createVibecodingSession({ target }, { historyOptions })` separates required ports
+  from optional tuning. `VibecodingSessionOptions` now contains only history tuning; the required
+  target lives in the new `VibecodingSessionArgs` type. `useVibecodingSession`,
+  `createVibecodingToolRegistrations` and `createVibecodingToolRunner` receive `{ session }`.
+- BREAKING: session subscriptions, part reads, edit batches and snapshot rewinds take named
+  objects; labels are in the optional second object. Hook actions share these method types.
+  The runner uses `run({ toolId, input })`. Tool wire schemas and React component props are unchanged.
+- Fixed session caching for repeated part ids and reverse-order undo. Selected previews now
+  refresh after history replay. Added regression, composition, export-map and whole-source
+  neutrality tests, and migrated the existing React test fixtures and README API examples.
+- Integration status supersedes the earlier React ownership note below: the cleared React
+  directory and its dependent calls are now migrated. Tests, typechecks, builds and pack checks
+  remain **not run (owner directive)**; no runtime correctness or release readiness is claimed.
+
+- BREAKING: `applyEdit`, `applyEdits`, `correctionsFor`, `createEditHistory`, and
+  `isValidRegionHandle` accept named required arguments. `createHtmlRegionTarget`
+  receives optional settings as its second object, separate from storage and parser ports.
+- BREAKING: `EditTarget.readPart`, `replacePart`, and `restore`, `EditHistory.transaction`
+  and `restore`, `HtmlRegionParser.findRegions` and `checkWellFormed`, and
+  `HtmlDocumentStore.write` accept named object arguments. Transaction labels belong
+  to the optional second object. Export names and edit/history behavior are preserved.
+- Updated core/HTML behavior tests and added a package neutrality guard. Verification
+  is deferred by owner directive. The pre-existing React worktree remains unchanged;
+  its dependent calls require migration before package verification or release.

package/README.md

@@ -0,0 +1,154 @@
+# @jini-ai/vibecoding
+
+Conversational artifact authoring — the loop that turns "make the hero blue" into a validated,
+undoable change, without knowing what kind of artifact it is editing.
+
+## The idea
+
+Every AI app-builder differs at exactly one place: **what is being edited**. One 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 the artifact reaches it through one small port:
+
+```ts
+interface EditTarget {
+  listParts(): Promise<readonly PartRef[]>;      // the allowlist
+  readPart({ id }): Promise<string>;
+  replacePart({ id, content }): Promise<void>;   // upsert
+  snapshot(): Promise<Snapshot>;
+  restore({ snapshot }): Promise<void>;
+  validate(candidate): Promise<ValidationResult>;
+}
+```
+
+A file-tree host maps parts to files. A single-document host maps them to addressable regions.
+Neither reimplements the loop.
+
+## Layout
+
+| entry | runtime | contents |
+| --- | --- | --- |
+| `.` | universal | re-exports `./core` |
+| `./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 |
+
+`./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
+`./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.
+
+### `./react`
+
+The chat + preview surface over any `EditTarget`: `createVibecodingSession` (a subscribable
+wrapper over `./core`'s loop, built for `useSyncExternalStore`), `createVibecodingToolRegistrations`
+/`createVibecodingToolRunner` (the same session exposed as `@jini-ai/core` `ToolDescriptor`s a chat
+surface discovers through a registry rather than a hardcoded list), and three React pieces —
+`PartsViewer` (the file viewer), `DocumentPreview` (the live renderer, a sandboxed iframe — not an
+editor, and not `@jini-ai/sandbox`'s job; see that component's own doc), and `VibecodingWorkbench`
+(both composed). See `src/react/index.ts` and each module's own doc comment for the design
+rationale behind every one of those pieces.
+
+## Three decisions worth knowing before changing anything
+
+**1. `listParts` is an allowlist, and that is where scope discipline comes from.**
+A part not listed is structurally unaddressable rather than merely discouraged. Prompt severity is
+not a substitute for this — one shipped builder ships three prompt variants that enforce identical
+scope rules with wildly different tone, over an identical mechanism. The constraint lives in the
+addressing.
+
+**2. `validate` receives the whole prospective artifact, and it is the one piece with no upstream.**
+Neither reference implementation validates writes at all, because their unit is a whole file and a
+malformed file cannot corrupt another file's syntax. Sub-document parts lose that property: one
+unbalanced tag corrupts everything after it. It takes the whole prospective artifact rather than the
+part alone because a fragment that is well-formed in isolation can still break the document it lands
+in. A rejection's `reason` is written for the model and fed back as its next turn — that is what
+closes the loop between validation and correction.
+
+**3. `snapshot` restores data, never an execution environment.**
+The reference implementation this shape came from also replays setup commands on rewind to restart
+its dev server. That is execution resync, and it is the host's job, after `restore` returns. Folding
+it in here would promise something this package cannot deliver for any host but the simplest.
+
+There are deliberately **no verbs for running processes, installing dependencies, or building**.
+Those are real needs for a file-tree host and belong to a separate execution layer. Their absence is
+a decision, not a gap.
+
+## Usage
+
+```ts
+import { applyEdits, correctionsFor } from "@jini-ai/vibecoding/core";
+
+const outcomes = await applyEdits({ target, edits: proposals });
+const corrections = correctionsFor({ outcomes });
+if (corrections.length > 0) {
+  // Feed these back as the model's next turn.
+}
+```
+
+Every proposal gets an outcome — a rejection or a write failure does not abandon the batch, so a
+host can report precisely which parts landed. Write failures surface as `failed` rather than being
+logged and forgotten.
+
+## Object API
+
+Functions with inputs take a required object followed, when needed, by an optional object.
+Dependencies are explicit ports in the required object. Methods with no inputs stay zero-argument;
+React components keep their props and framework callbacks keep the framework's signature.
+
+| API | Call shape |
+| --- | --- |
+| Single edit | `applyEdit({ target, edit })` |
+| Batch edits and feedback | `applyEdits({ target, edits })`, `correctionsFor({ outcomes })` |
+| History | `createEditHistory({ target }, { limit })` |
+| Transaction / snapshot rewind | `history.transaction({ work }, { label })`, `history.restore({ snapshot })` |
+| HTML target | `createHtmlRegionTarget({ store, parser }, { maxPartLength })` |
+| 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 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 })` |
+| Direct tool runner | `createVibecodingToolRunner({ session })`, `runner.run({ toolId, input })` |
+
+`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
+`label` still belong to the same tool input object.
+
+```ts
+import { createHtmlRegionTarget, type HtmlDocumentStore } from '@jini-ai/vibecoding/html';
+import { createParse5RegionParser } from '@jini-ai/vibecoding/html/node';
+import {
+  createVibecodingSession, createVibecodingToolRunner, VIBECODING_TOOL_IDS,
+} from '@jini-ai/vibecoding/react';
+
+let html = '<section data-agent-element="hero">Hello</section>';
+const store: HtmlDocumentStore = {
+  read: async () => html,
+  write: async ({ html: next }) => { html = next; },
+};
+const target = createHtmlRegionTarget({ store, parser: createParse5RegionParser() });
+const session = createVibecodingSession({ target }, { historyOptions: { limit: 25 } });
+const runner = createVibecodingToolRunner({ session });
+await runner.run({
+  toolId: VIBECODING_TOOL_IDS.PROPOSE_EDITS,
+  input: { edits: [{ id: 'hero', content: 'Hello again' }], label: 'Greeting' },
+});
+await session.undo();
+```
+
+The parser import above is for a Node host. Browser hosts inject a browser-compatible
+`HtmlRegionParser` through the same port. Storage paths, persistence and product configuration
+belong to the host. Integration verification is deferred by owner directive; see
+[INTEGRATION-REPORT.md](./INTEGRATION-REPORT.md) for the source review and pending commands.
+
+## Design decisions
+
+- [Ambiguous region detection refuses rather than dropping a handle](docs/decisions/DR-001-conservative-region-detection.md).

package/dist/core/apply.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @module core/apply
+ *
+ * Validate-then-commit: the only sanctioned path from a model's proposed content to a real write.
+ *
+ * Two failure behaviours here are deliberate corrections of what the reference implementations do,
+ * and both were observed in their source rather than inferred:
+ *
+ * - **A write failure is never swallowed.** One builder wraps both its directory-create and its
+ *   file-write in `try/catch` blocks that only log, then returns normally — so the action is
+ *   marked complete whether or not anything reached disk, while its *shell* actions do surface
+ *   failures. That asymmetry looks accidental. Here a failed write becomes a `failed` outcome the
+ *   caller must handle.
+ * - **Per-part outcomes are collected and returned, not aggregated into a single boolean.** This is
+ *   the one thing the second reference implementation does better than the first, and it is what
+ *   lets a host stream partial progress and tell the model precisely which parts landed.
+ */
+import type { EditTarget } from "./target.js";
+import type { ApplyOutcome, PartId } from "./types.js";
+/** One proposed change: replace `id`'s content with `content`. */
+export interface ProposedEdit {
+    readonly id: PartId;
+    readonly content: string;
+}
+/**
+ * Validate one proposed edit and, if the host accepts it, commit it.
+ *
+ * @param requiredArgs - the host's artifact port and the model's proposed replacement.
+ * @returns what happened — applied, rejected by `validate`, or failed while validating or writing.
+ * @complexity 3
+ */
+export declare function applyEdit({ target, edit }: {
+    readonly target: EditTarget;
+    readonly edit: ProposedEdit;
+}): Promise<ApplyOutcome>;
+/**
+ * Apply several proposed edits in order, one at a time.
+ *
+ * Sequential on purpose: `validate` is defined over the whole prospective artifact, so two edits
+ * validated concurrently would each be judged against a state that never existed. A rejected or
+ * failed edit does **not** halt the rest — every proposal gets an outcome, so the caller can report
+ * precisely which parts landed rather than abandoning the batch at the first problem.
+ *
+ * @param requiredArgs - the host's artifact port and proposals, applied in the given order.
+ * @returns one outcome per proposal, positionally aligned with `edits`.
+ * @complexity 2
+ */
+export declare function applyEdits({ target, edits }: {
+    readonly target: EditTarget;
+    readonly edits: readonly ProposedEdit[];
+}): Promise<readonly ApplyOutcome[]>;
+/**
+ * The subset of outcomes a host should feed back to the model as its next turn.
+ *
+ * Rejections carry a reason written for the model; write failures carry an error message. Both are
+ * things the model can act on, and neither reaches it unless the host asks for them here — which
+ * is what closes the loop between validation and correction.
+ *
+ * @param requiredArgs - results from `applyEdits`.
+ * @returns one `{ id, reason }` per non-applied outcome, in input order.
+ * @complexity 3
+ */
+export declare function correctionsFor({ outcomes }: {
+    readonly outcomes: readonly ApplyOutcome[];
+}): readonly {
+    readonly id: PartId;
+    readonly reason: string;
+}[];
+//# sourceMappingURL=apply.d.ts.map

package/dist/core/apply.js

@@ -0,0 +1,69 @@
+/** Normalizes an unknown thrown value into an `Error`, preserving a non-Error as its message. */
+function toError(thrown) {
+    return thrown instanceof Error ? thrown : new Error(String(thrown));
+}
+/**
+ * Validate one proposed edit and, if the host accepts it, commit it.
+ *
+ * @param requiredArgs - the host's artifact port and the model's proposed replacement.
+ * @returns what happened — applied, rejected by `validate`, or failed while validating or writing.
+ * @complexity 3
+ */
+export async function applyEdit({ target, edit }) {
+    try {
+        // Validation is a host port too: a failed parser/read must produce an outcome so the batch
+        // can continue, and must never reach the write for this proposal.
+        const verdict = await target.validate({ id: edit.id, content: edit.content });
+        if (!verdict.ok) {
+            return { status: "rejected", id: edit.id, reason: verdict.reason };
+        }
+        await target.replacePart({ id: edit.id, content: edit.content });
+    }
+    catch (thrown) {
+        return { status: "failed", id: edit.id, error: toError(thrown) };
+    }
+    return { status: "applied", id: edit.id };
+}
+/**
+ * Apply several proposed edits in order, one at a time.
+ *
+ * Sequential on purpose: `validate` is defined over the whole prospective artifact, so two edits
+ * validated concurrently would each be judged against a state that never existed. A rejected or
+ * failed edit does **not** halt the rest — every proposal gets an outcome, so the caller can report
+ * precisely which parts landed rather than abandoning the batch at the first problem.
+ *
+ * @param requiredArgs - the host's artifact port and proposals, applied in the given order.
+ * @returns one outcome per proposal, positionally aligned with `edits`.
+ * @complexity 2
+ */
+export async function applyEdits({ target, edits }) {
+    const outcomes = [];
+    for (const edit of edits) {
+        outcomes.push(await applyEdit({ target, edit }));
+    }
+    return outcomes;
+}
+/**
+ * The subset of outcomes a host should feed back to the model as its next turn.
+ *
+ * Rejections carry a reason written for the model; write failures carry an error message. Both are
+ * things the model can act on, and neither reaches it unless the host asks for them here — which
+ * is what closes the loop between validation and correction.
+ *
+ * @param requiredArgs - results from `applyEdits`.
+ * @returns one `{ id, reason }` per non-applied outcome, in input order.
+ * @complexity 3
+ */
+export function correctionsFor({ outcomes }) {
+    const corrections = [];
+    for (const outcome of outcomes) {
+        if (outcome.status === "rejected") {
+            corrections.push({ id: outcome.id, reason: outcome.reason });
+        }
+        else if (outcome.status === "failed") {
+            corrections.push({ id: outcome.id, reason: outcome.error.message });
+        }
+    }
+    return corrections;
+}
+//# sourceMappingURL=apply.js.map

package/dist/core/history.d.ts

@@ -0,0 +1,144 @@
+/**
+ * @module core/history
+ *
+ * Operation-level undo and redo, layered strictly **on top of** `EditTarget` — it adds no verb to
+ * that port. A history records the before/after content of every part a transaction touched, which
+ * it learns by calling `readPart` immediately before each `replacePart`. Nothing here needs the
+ * host to implement anything new.
+ *
+ * ## Why this tier exists at all, given `snapshot`/`restore`
+ *
+ * `snapshot`/`restore` is a whole-artifact rewind: it answers "put everything back the way it was."
+ * It cannot answer "undo the last thing," which is the operation a person actually reaches for, and
+ * it has no notion of redo. One shipped builder has exactly this gap — a rewind-to-snapshot feature
+ * and no undo stack at all, so stepping back one edit means stepping back every edit since the last
+ * capture. A second builder has both tiers, with transaction batching, and is the better model.
+ *
+ * ## Three decisions worth stating, because each could reasonably have gone the other way
+ *
+ * 1. **Undo and redo bypass `validate`.** `validate` judges a candidate against the whole
+ *    prospective artifact (see `./target.ts`). Rewinding a transaction that touched three parts
+ *    necessarily passes through two intermediate states that never existed as committed states, and
+ *    validating those would reject a legitimate rewind — a half-restored document is exactly the
+ *    kind of thing `validate` is built to refuse. The state being restored was already committed
+ *    once, so it needs no second opinion. Applying a *new* edit still goes through `applyEdit`, and
+ *    that path is unchanged.
+ *
+ * 2. **A rewind is itself undoable, and so is a snapshot restore.** `restore` below diffs the
+ *    target snapshot against current content and records the result as an ordinary transaction, so
+ *    the two tiers share one stack and a mis-aimed rewind is recoverable. Borrowed deliberately:
+ *    the alternative — a restore that silently discards whatever it overwrote — turns the safety
+ *    feature into the most destructive button in the product.
+ *
+ * 3. **A transaction that throws still commits its partial entry, then rethrows.** Whatever reached
+ *    the artifact before the throw is real, and the only thing worse than a partial write is a
+ *    partial write nobody can undo. Note that `applyEdits` does not throw — it returns `failed`
+ *    outcomes — so this path is genuinely exceptional rather than routine.
+ *
+ * ## The one thing this tier cannot do
+ *
+ * `replacePart` is an upsert, and `EditTarget` deliberately has no delete verb, so **undoing the
+ * creation of a part cannot remove it** — the best available inverse is writing empty content back.
+ * Each change records `existedBefore` so a host that *can* delete may consult the entry and finish
+ * the job properly. Pretending otherwise would be the more dangerous choice: a caller would believe
+ * a part had gone away while it was still listed and still readable.
+ */
+import type { EditTarget } from "./target.js";
+import type { PartId, Snapshot } from "./types.js";
+/** What one part looked like before and after a single transaction touched it. */
+export interface PartChange {
+    readonly id: PartId;
+    /** Content prior to the change. Empty when the part did not exist — see `existedBefore`. */
+    readonly before: string;
+    /** Content written by the change. */
+    readonly after: string;
+    /**
+     * Whether the part existed before this change.
+     *
+     * `false` means the transaction created it, and undo therefore cannot fully invert it — see this
+     * module's doc. A host with its own delete capability can use this flag to do better.
+     */
+    readonly existedBefore: boolean;
+}
+/** One undoable step: every part change a single transaction produced, in the order applied. */
+export interface HistoryEntry {
+    /** Optional caller-supplied description, e.g. the model turn that produced it. Untrusted text. */
+    readonly label?: string;
+    /** Part changes in application order. Undo replays these in reverse. */
+    readonly changes: readonly PartChange[];
+}
+/** Tuning for `createEditHistory`. */
+export interface EditHistoryOptions {
+    /**
+     * Maximum number of undoable entries retained. Oldest are dropped first.
+     *
+     * Bounded because every entry holds full copies of the content it touched, so an unbounded stack
+     * in a long authoring session grows with total bytes written rather than with artifact size.
+     * Defaults to 50.
+     */
+    readonly limit?: number;
+}
+/** An operation-level undo/redo stack over one `EditTarget`. */
+export interface EditHistory {
+    /**
+     * Run `work` against a recording view of the target, committing everything it changed as one
+     * undoable entry.
+     *
+     * The target handed to `work` is a transparent wrapper: pass it to `applyEdit`/`applyEdits`
+     * exactly as you would the real one. Grouping is what makes a multi-part model turn undo as a
+     * single step rather than as N unrelated ones.
+     *
+     * A transaction that changes nothing records nothing, so a rejected model turn leaves no empty
+     * step for a user to click past. Committing also clears the redo stack, which is the standard
+     * rule: once you branch off the redo path, the abandoned future is no longer reachable.
+     */
+    transaction<T>(requiredArgs: {
+        readonly work: (recording: EditTarget) => Promise<T>;
+    }, optionalArgs?: {
+        readonly label?: string;
+    }): Promise<T>;
+    /** Whether `undo` would do anything. */
+    canUndo(): boolean;
+    /** Whether `redo` would do anything. */
+    canRedo(): boolean;
+    /**
+     * Revert the most recent entry, writing each part's `before` content in reverse order.
+     *
+     * @returns the entry that was reverted, or `null` when there is nothing to undo.
+     */
+    undo(): Promise<HistoryEntry | null>;
+    /**
+     * Re-apply the most recently undone entry, writing each part's `after` content in order.
+     *
+     * @returns the entry that was re-applied, or `null` when there is nothing to redo.
+     */
+    redo(): Promise<HistoryEntry | null>;
+    /**
+     * Restore a snapshot as an **undoable** step rather than a destructive one.
+     *
+     * Current content is captured first and recorded as the `before` side, so the rewind can itself
+     * be undone. Parts present now but absent from the snapshot are left alone — there is no delete
+     * verb to remove them with (see this module's doc).
+     *
+     * @returns the entry recorded, or `null` when the snapshot already matches current content.
+     */
+    restore(args: {
+        readonly snapshot: Snapshot;
+    }): Promise<HistoryEntry | null>;
+    /** Undoable entries, oldest first. For rendering a history UI; do not mutate. */
+    entries(): readonly HistoryEntry[];
+    /** Discard both stacks. */
+    clear(): void;
+}
+/**
+ * Create an undo/redo stack over one target.
+ *
+ * @param requiredArgs - the host's artifact port; used for reads and replaying changes.
+ * @param options - see `EditHistoryOptions`.
+ * @returns a history whose `transaction` wrapper is the only thing callers need to adopt.
+ * @complexity 4
+ */
+export declare function createEditHistory({ target }: {
+    readonly target: EditTarget;
+}, options?: EditHistoryOptions): EditHistory;
+//# sourceMappingURL=history.d.ts.map

package/dist/core/history.js

@@ -0,0 +1,132 @@
+/** Reads a part's current content, reporting absence rather than throwing. */
+async function readCurrent(target, id) {
+    try {
+        return { content: await target.readPart({ id }), existed: true };
+    }
+    catch {
+        return { content: "", existed: false };
+    }
+}
+/**
+ * Create an undo/redo stack over one target.
+ *
+ * @param requiredArgs - the host's artifact port; used for reads and replaying changes.
+ * @param options - see `EditHistoryOptions`.
+ * @returns a history whose `transaction` wrapper is the only thing callers need to adopt.
+ * @complexity 4
+ */
+export function createEditHistory({ target }, options = {}) {
+    const limit = options.limit ?? 50;
+    const undoStack = [];
+    const redoStack = [];
+    let transactionOpen = false;
+    function push(entry) {
+        undoStack.push(entry);
+        while (undoStack.length > limit)
+            undoStack.shift();
+        redoStack.length = 0;
+    }
+    /**
+     * Replay part contents directly, deliberately skipping `validate` — see this module's doc for
+     * why an intermediate state of a multi-part rewind must not be judged.
+     */
+    async function replay(changes, side) {
+        for (const change of changes) {
+            await target.replacePart({ id: change.id, content: side === "before" ? change.before : change.after });
+        }
+    }
+    return {
+        async transaction({ work }, { label } = {}) {
+            if (transactionOpen) {
+                throw new Error("a transaction is already open — overlapping transactions would interleave their changes into one another's entries");
+            }
+            transactionOpen = true;
+            const changes = [];
+            const recording = {
+                listParts: () => target.listParts(),
+                readPart: (args) => target.readPart(args),
+                snapshot: () => target.snapshot(),
+                restore: (args) => target.restore(args),
+                validate: (candidate) => target.validate(candidate),
+                async replacePart({ id, content }) {
+                    const current = await readCurrent(target, id);
+                    await target.replacePart({ id, content });
+                    // A write that changed nothing is not a step a person can meaningfully undo.
+                    if (current.existed && current.content === content)
+                        return;
+                    changes.push({
+                        id,
+                        before: current.content,
+                        after: content,
+                        existedBefore: current.existed,
+                    });
+                },
+            };
+            try {
+                return await work(recording);
+            }
+            finally {
+                transactionOpen = false;
+                // Committed even when `work` threw: partial writes already reached the artifact, and the
+                // caller needs them to be undoable.
+                if (changes.length > 0)
+                    push(label === undefined ? { changes } : { label, changes });
+            }
+        },
+        canUndo: () => undoStack.length > 0,
+        canRedo: () => redoStack.length > 0,
+        async undo() {
+            // Peeked, not popped: a `replacePart` that throws partway through leaves the earlier parts
+            // already rewound, and popping first would strand that half-applied entry in NEITHER stack —
+            // the artifact changed and the history API could no longer reach it. Same principle decision
+            // 3 in this module's doc states for `transaction`. Moving between stacks only after a clean
+            // replay means a failed undo is simply retryable: replaying `before` again rewrites the
+            // parts that already landed with the content they already hold (a no-op) and retries the one
+            // that failed.
+            const entry = undoStack[undoStack.length - 1];
+            if (!entry)
+                return null;
+            await replay([...entry.changes].reverse(), "before");
+            undoStack.pop();
+            redoStack.push(entry);
+            return entry;
+        },
+        async redo() {
+            // Peeked for the same reason as `undo` above, in the other direction.
+            const entry = redoStack[redoStack.length - 1];
+            if (!entry)
+                return null;
+            await replay(entry.changes, "after");
+            redoStack.pop();
+            undoStack.push(entry);
+            return entry;
+        },
+        async restore({ snapshot }) {
+            const changes = [];
+            for (const [id, after] of Object.entries(snapshot.parts)) {
+                const current = await readCurrent(target, id);
+                if (current.existed && current.content === after)
+                    continue;
+                changes.push({ id, before: current.content, after, existedBefore: current.existed });
+            }
+            if (changes.length === 0)
+                return null;
+            // Recorded BEFORE the replay, not after. A restore that throws on its second part has still
+            // changed the first, and pushing afterwards left those writes with no undo record at all —
+            // the destructive-restore failure mode decision 2 in this module's doc exists to prevent,
+            // reached by a different route. The `before` sides were captured above and are correct
+            // regardless of how far the replay got: undoing a partially-applied restore rewrites every
+            // listed part with the content it had before, which is a no-op for the ones never reached.
+            const entry = { label: `restore ${snapshot.id}`, changes };
+            push(entry);
+            await replay(changes, "after");
+            return entry;
+        },
+        entries: () => [...undoStack],
+        clear() {
+            undoStack.length = 0;
+            redoStack.length = 0;
+        },
+    };
+}
+//# sourceMappingURL=history.js.map

package/dist/core/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @module core
+ *
+ * The framework-free half of `@jini-ai/vibecoding`: the authoring loop and the artifact port it
+ * drives. No React, no Node built-ins, no DOM — so a server, a worker or a CLI can import this
+ * without acquiring a UI dependency.
+ *
+ * That separation is enforced by the same rule that governs the rest of this workspace, and it is
+ * not theoretical: a sibling consolidation was measured and abandoned precisely because a Node
+ * HTTP server imports a framework-free chat package directly, and folding a React layer into it
+ * would have forced React onto that server.
+ */
+export type { ApplyOutcome, PartId, PartRef, Snapshot, ValidationResult, } from "./types.js";
+export type { EditTarget } from "./target.js";
+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";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

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