@jini-ai/vibecoding 0.6.11 → 0.6.15-rc.1

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.6.13
+
+### Patch Changes
+
+- 506196f: BREAKING (host composition): two native effects are now injected by the host instead of loaded from a sibling
+  domain (guard L1 / SI-domain clean-up). No default is provided because a default would reintroduce exactly
+  that edge.
+
+  - `@jini-ai/vibecoding` node: `openFileTreeProject` (and the node store/paths inputs) require
+    `filesystem: ProjectFilesystemPort` (`createReader`, `withFileLock`, `writeFileAtomicAsync`,
+    `writeJsonFileAtomicAsync`). Bind the existing `@jini-ai/platform` implementations in the host's composition root (see the `ProjectFilesystemPort` doc example).
+    Hosts that only use `@jini-ai/vibecoding/html*` are unaffected.
+  - `@jini-ai/integrations` saved requests: `SavedRequestDeps` requires `executeCredentialedRequest`;
+    pass `makeCredentialedRequest` from `@jini-ai/integrations/credentialed-http` so auditing and redaction stay bound
+    to that owner.
+
+- Updated dependencies [7479159]
+- Updated dependencies [c31264d]
+- Updated dependencies [0728914]
+- Updated dependencies [6ecbdb2]
+- Updated dependencies [63bacc5]
+  - @jini-ai/core@0.6.13
+
+## 0.6.12
+
+### Patch Changes
+
+- Updated dependencies
+  - @jini-ai/platform@0.6.12
+  - @jini-ai/core@0.6.12
+
 ## 0.6.11
 
 ### Patch Changes

package/README.md

@@ -159,10 +159,20 @@ belong to the host. Integration verification is deferred by owner directive; see
 ## Local app projects
 
 ```ts
-import { openFileTreeProject } from '@jini-ai/vibecoding/node';
+import { openFileTreeProject, type ProjectFilesystemPort } from '@jini-ai/vibecoding/node';
+import { createGuardedFileReader, createNodeGuardedReaderFilesystem, withFileLock,
+  writeFileAtomicAsync, writeJsonFileAtomicAsync } from '@jini-ai/platform/fs';
 import { createVibecodingSession } from '@jini-ai/vibecoding/session';
 
+// The host binds the existing platform owners once at composition.
+const filesystem: ProjectFilesystemPort = {
+  createReader: (input, options = {}) => createGuardedFileReader({
+    ...input, filesystem: createNodeGuardedReaderFilesystem({}),
+  }, options),
+  withFileLock, writeFileAtomicAsync, writeJsonFileAtomicAsync,
+};
 const project = await openFileTreeProject({
+  filesystem,
   root: appDirectory,
   stateDir: privateHostStateDirectory, // outside appDirectory: dev servers must never serve history
   policy: { allows: ({ relativePath }) => allowedAppPath(relativePath) },

package/dist/core/index.d.ts

@@ -17,4 +17,5 @@ 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';
+export type { ProjectFilesystemPort } from './project-filesystem.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/project-filesystem.d.ts

@@ -0,0 +1,36 @@
+import type { DenyRules, GuardedFileReader, GuardedReaderLimits } from '@jini-ai/core/filesystem';
+/** Filesystem capabilities required by the local project adapter. Composition binds the existing
+ * platform implementations so containment, locking and atomic writes keep a single owner.
+ * @example const filesystem: ProjectFilesystemPort = { createReader, withFileLock, writeFileAtomicAsync, writeJsonFileAtomicAsync };
+ */
+export interface ProjectFilesystemPort {
+    createReader(required: {
+        rootPath: string;
+        denyRules: DenyRules;
+        limits: GuardedReaderLimits;
+    }, options?: {
+        excludedListingDirs?: ReadonlySet<string>;
+    }): GuardedFileReader;
+    withFileLock<T>(required: {
+        lockPath: string;
+        run: () => Promise<T>;
+    }, options?: {
+        staleMs?: number;
+        createParent?: boolean;
+    }): Promise<T>;
+    writeFileAtomicAsync(required: {
+        filePath: string;
+        content: string | Uint8Array;
+    }, options?: {
+        createParent?: boolean;
+        refuseSymlink?: boolean;
+        defaultMode?: number;
+    }): Promise<void>;
+    writeJsonFileAtomicAsync(required: {
+        filePath: string;
+        data: unknown;
+    }, options?: {
+        createParent?: boolean;
+    }): Promise<void>;
+}
+//# sourceMappingURL=project-filesystem.d.ts.map

package/dist/core/project-filesystem.js

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

package/dist/core/session.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @module session
+ *
+ * `VibecodingSession` — the framework-free stateful object over
+ * `./core`'s `EditTarget` + `EditHistory`. Everything else in `./react` (the hook, the tool
+ * registrations, the presentational components) reads and drives an artifact through this seam
+ * rather than touching `EditTarget`/`EditHistory` directly, for one reason: a tool call arrives
+ * from the chat's execution path, not from a React event handler, so the thing tool handlers call
+ * into cannot be React state — it has to be a plain, subscribable object a `useSyncExternalStore`
+ * hook can also read. This module is React-free and exported with the tools from `./session`.
+ *
+ * ## Why part content is cached rather than re-read on every render
+ *
+ * `EditTarget.readPart` is a host call — for the `html` target it is cheap (a string slice), but
+ * the port makes no such promise for every target (a filesystem or sandbox-backed host could hit a
+ * network round trip per part). Re-reading every listed part's content on every `refresh()` would
+ * turn "the operator opened the file viewer" into an O(part count) fan-out of host calls, and
+ * nothing here can assume that count stays small — see `./target.ts`'s own doc on why
+ * `listParts` is the allowlist, not a bound on its size. So `refresh()` only calls `listParts()`;
+ * content is fetched lazily, per id, through `readPart()`, and cached. Every mutating operation
+ * below (`applyEdits`, `undo`, `redo`, `restoreSnapshot`) in a default session knows the exact before/after
+ * content it just wrote — `./apply.ts`'s `ProposedEdit`, `./history.ts`'s
+ * `PartChange.before`/`.after` — so the cache is updated from that data directly instead of
+ * re-reading the part it just wrote back from the host. Project sessions clear caches instead:
+ * their history entries hold revision pointers, and external tools may have changed file bytes.
+ */
+import type { ApplyOutcome, PartId, PartRef, Snapshot } from './types.js';
+import type { EditTarget } from './target.js';
+import { type ProposedEdit } from './apply.js';
+import { type EditHistory, type EditHistoryOptions, type HistoryEntry } from './history.js';
+export interface VibecodingSessionArgs {
+    /** The host's artifact port. See `./target.ts`. */
+    readonly target: EditTarget;
+}
+export interface VibecodingSessionOptions {
+    /** Forwarded to `createEditHistory`. See `./history.ts`'s `EditHistoryOptions`. */
+    readonly historyOptions?: EditHistoryOptions;
+    /** A project supplies its guarded pointer history instead of a per-file stack. */
+    readonly history?: EditHistory;
+    /** Whole-turn mutation; owns its history recording and returns aligned outcomes. */
+    readonly applyTurn?: (input: {
+        readonly edits: readonly ProposedEdit[];
+    }, options?: {
+        readonly label?: string;
+    }) => Promise<readonly ApplyOutcome[]>;
+}
+/**
+ * Immutable, point-in-time read of a session. `getSnapshot()` returns the same object reference
+ * until something actually changes — required for `useSyncExternalStore`, which re-renders a
+ * subscriber whenever the reference it reads changes, not whenever it is merely called again.
+ */
+export interface VibecodingSessionSnapshot {
+    /** `'idle'` until the first `refresh()` resolves; `'error'` reflects the most recent failure, not
+     *  a permanently wedged session — a subsequent successful call returns it to `'ready'`. */
+    readonly status: 'idle' | 'loading' | 'ready' | 'error';
+    /** Every part the host currently advertises, in `EditTarget.listParts()`'s own order. */
+    readonly parts: readonly PartRef[];
+    /** Cached content, keyed by part id. A part absent from this map has not been read yet — see
+     *  this module's doc for why content is lazy rather than eagerly fetched for every part. */
+    readonly partContent: ReadonlyMap<PartId, string>;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    /** The most recent operation's failure message, if any. Cleared by the next successful call. */
+    readonly lastError: string | undefined;
+}
+export interface ApplyEditsResult {
+    readonly outcomes: readonly ApplyOutcome[];
+    /** See `./apply.ts`'s `correctionsFor` — the subset a caller feeds back to the model. */
+    readonly corrections: readonly {
+        readonly id: PartId;
+        readonly reason: string;
+    }[];
+}
+export interface VibecodingSession {
+    /** The underlying port, for a caller (or test) that needs it directly — e.g. to read the whole
+     *  document a host-specific target stores, which is outside this generic session's vocabulary. */
+    readonly target: EditTarget;
+    /** The underlying undo/redo stack, for a caller that needs `.entries()` for a history UI. */
+    readonly history: EditHistory;
+    getSnapshot(): VibecodingSessionSnapshot;
+    /** Returns an unsubscribe function; the React hook adapts this object API for React. */
+    subscribe(args: {
+        readonly listener: () => void;
+    }): () => void;
+    /** Re-lists parts from the host. Does not re-read content — see this module's doc. */
+    refresh(): Promise<void>;
+    /** Cached content for `id`, fetching once from the host on first request. */
+    readPart(args: {
+        readonly id: PartId;
+    }): Promise<string>;
+    /** Applies `edits` as one undoable transaction and updates the cache from the edits themselves. */
+    applyEdits(requiredArgs: {
+        readonly edits: readonly ProposedEdit[];
+    }, optionalArgs?: {
+        readonly label?: string;
+    }): Promise<ApplyEditsResult>;
+    undo(): Promise<HistoryEntry | null>;
+    redo(): Promise<HistoryEntry | null>;
+    takeSnapshot(): Promise<Snapshot>;
+    restoreSnapshot(args: {
+        readonly snapshot: Snapshot;
+    }): Promise<HistoryEntry | null>;
+}
+/**
+ * Builds a session over `target`, with private history by default or injected project history.
+ * Injected applyTurn owns whole-turn recording; this session owns notifications and cache invalidation.
+ *
+ * The returned session starts in `'idle'` with no parts listed — call `refresh()` (or let
+ * `useVibecodingSession` do it on mount) to populate it. Nothing here triggers I/O eagerly, so
+ * constructing a session has no side effect a caller needs to clean up.
+ *
+ * @complexity Construction is O(1). See each method for its own cost.
+ */
+export declare function createVibecodingSession({ target }: VibecodingSessionArgs, options?: VibecodingSessionOptions): VibecodingSession;
+//# sourceMappingURL=session.d.ts.map

package/dist/core/session.js

@@ -0,0 +1,178 @@
+import { applyEdits as applyEditsToTarget, correctionsFor } from './apply.js';
+import { createEditHistory } from './history.js';
+const READY_ERROR = undefined;
+/**
+ * Builds a session over `target`, with private history by default or injected project history.
+ * Injected applyTurn owns whole-turn recording; this session owns notifications and cache invalidation.
+ *
+ * The returned session starts in `'idle'` with no parts listed — call `refresh()` (or let
+ * `useVibecodingSession` do it on mount) to populate it. Nothing here triggers I/O eagerly, so
+ * constructing a session has no side effect a caller needs to clean up.
+ *
+ * @complexity Construction is O(1). See each method for its own cost.
+ */
+export function createVibecodingSession({ target }, options = {}) {
+    const history = options.history ?? createEditHistory({ target }, options.historyOptions);
+    // Project turns write through revision pointers, so cached part content is never reusable after them.
+    const applyTurn = options.applyTurn;
+    const listeners = new Set();
+    const partContent = new Map();
+    let current = {
+        status: 'idle',
+        parts: [],
+        partContent,
+        canUndo: history.canUndo(),
+        canRedo: history.canRedo(),
+        lastError: READY_ERROR,
+    };
+    /** Replaces `current` with a fresh object carrying `patch`, then notifies subscribers. A fresh
+     *  `partContent` Map reference is handed out only when the map's contents actually changed
+     *  (callers pass a new Map in `patch` for that case); reusing the same Map reference otherwise
+     *  is what keeps an unrelated status change (e.g. `'loading'` -> `'ready'`) from invalidating a
+     *  component's memoized read of `partContent`. */
+    function commit(patch) {
+        current = { ...current, ...patch };
+        for (const listener of listeners)
+            listener();
+    }
+    /**
+     * Runs `work`, tagging the session `'loading'` -> `'ready'`/`'error'` and always returning
+     * control to the caller — a rejection is recorded as `lastError` AND rethrown, so a component
+     * can render `lastError` passively while a tool handler that needs to fail loudly still can.
+     *
+     * `work` returns its data `patch` alongside its `result` rather than calling `commit` itself, so
+     * the success path here can fold that patch into the SAME commit as the `'ready'` status
+     * transition — one notification per operation instead of two, which matters to a
+     * `useSyncExternalStore` subscriber re-rendering on every commit.
+     */
+    async function run(work) {
+        commit({ status: 'loading' });
+        try {
+            const { result, patch } = await work();
+            commit({ ...patch, status: 'ready', lastError: READY_ERROR });
+            return result;
+        }
+        catch (thrown) {
+            const message = thrown instanceof Error ? thrown.message : String(thrown);
+            if (applyTurn)
+                partContent.clear();
+            commit({ status: 'error', lastError: message, partContent: new Map(partContent), canUndo: history.canUndo(), canRedo: history.canRedo() });
+            throw thrown;
+        }
+    }
+    /** Mirrors a replayed change in the cache. Undoing creation keeps empty content because the
+     *  target's upsert port has no delete operation; see `./history.ts`. */
+    function cacheChange(change, side) {
+        partContent.set(change.id, side === 'after' ? change.after : change.before);
+    }
+    /** Mirrors a recorded snapshot restore in the cache and re-reads the part list it may have grown. */
+    async function restoredPatch(entry) {
+        if (applyTurn)
+            partContent.clear();
+        else
+            for (const change of entry.changes)
+                cacheChange(change, 'after');
+        const parts = await target.listParts();
+        return { parts, partContent: new Map(partContent), canUndo: history.canUndo(), canRedo: history.canRedo() };
+    }
+    return {
+        target,
+        history,
+        getSnapshot: () => current,
+        subscribe({ listener }) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        refresh: () => run(async () => {
+            const parts = await target.listParts();
+            if (applyTurn)
+                partContent.clear();
+            const known = new Set(parts.map((p) => p.id));
+            // Drop cached content for parts the host no longer lists — stale content for an
+            // unaddressable id would otherwise linger forever with nothing to invalidate it.
+            for (const id of partContent.keys())
+                if (!known.has(id))
+                    partContent.delete(id);
+            return {
+                result: undefined,
+                patch: { parts, partContent: new Map(partContent), canUndo: history.canUndo(), canRedo: history.canRedo() },
+            };
+        }),
+        readPart: ({ id }) => run(async () => {
+            const cached = applyTurn ? undefined : partContent.get(id);
+            if (cached !== undefined)
+                return { result: cached, patch: {} };
+            if (applyTurn)
+                partContent.clear();
+            const content = await target.readPart({ id });
+            partContent.set(id, content);
+            return { result: content, patch: { partContent: new Map(partContent), canUndo: history.canUndo(), canRedo: history.canRedo() } };
+        }),
+        applyEdits: ({ edits }, options = {}) => run(async () => {
+            const outcomes = await (applyTurn
+                ? applyTurn({ edits }, options)
+                : history.transaction({ work: (recording) => applyEditsToTarget({ target: recording, edits }) }, options));
+            if (applyTurn)
+                partContent.clear();
+            // Outcomes are aligned with proposals, including repeated ids. Matching only by id
+            // would cache the first proposal instead of the last successful write for that part.
+            // This pass is O(edits.length), with no additional reads through the target port.
+            for (const [index, outcome] of outcomes.entries()) {
+                if (outcome.status !== 'applied')
+                    continue;
+                const edit = edits[index];
+                if (edit && !applyTurn)
+                    partContent.set(edit.id, edit.content);
+            }
+            const parts = await target.listParts();
+            return {
+                result: { outcomes, corrections: correctionsFor({ outcomes }) },
+                patch: {
+                    parts,
+                    partContent: new Map(partContent),
+                    canUndo: history.canUndo(),
+                    canRedo: history.canRedo(),
+                },
+            };
+        }),
+        undo: () => run(async () => {
+            const entry = await history.undo();
+            if (!entry)
+                return { result: entry, patch: {} };
+            // Undo replays in reverse order. Repeated ids must leave the earliest before value
+            // cached, matching what history wrote to the target.
+            if (applyTurn)
+                partContent.clear();
+            else
+                for (const change of [...entry.changes].reverse())
+                    cacheChange(change, 'before');
+            const parts = applyTurn ? await target.listParts() : current.parts;
+            return {
+                result: entry,
+                patch: { parts, partContent: new Map(partContent), canUndo: history.canUndo(), canRedo: history.canRedo() },
+            };
+        }),
+        redo: () => run(async () => {
+            const entry = await history.redo();
+            if (!entry)
+                return { result: entry, patch: {} };
+            if (applyTurn)
+                partContent.clear();
+            else
+                for (const change of entry.changes)
+                    cacheChange(change, 'after');
+            const parts = applyTurn ? await target.listParts() : current.parts;
+            return {
+                result: entry,
+                patch: { parts, partContent: new Map(partContent), canUndo: history.canUndo(), canRedo: history.canRedo() },
+            };
+        }),
+        takeSnapshot: () => run(async () => ({ result: await target.snapshot(), patch: {} })),
+        restoreSnapshot: ({ snapshot }) => run(async () => {
+            const entry = await history.restore({ snapshot });
+            // A restore that already matched records no entry and changes nothing to mirror.
+            return { result: entry, patch: entry ? await restoredPatch(entry) : {} };
+        }),
+    };
+}
+//# sourceMappingURL=session.js.map

package/dist/node/index.d.ts

@@ -3,4 +3,5 @@ export { openFileTreeProject } from './project.js';
 export type { OpenFileTreeProjectInput, OpenFileTreeProjectOptions } from './project.js';
 export type { FileTreePolicy } from './paths.js';
 export * from '../core/project.js';
+export type { ProjectFilesystemPort } from '../core/project-filesystem.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/node/paths.d.ts

@@ -1,3 +1,4 @@
+import type { ProjectFilesystemPort } from '../core/project-filesystem.js';
 import { type ProjectLimits } from '../core/project.js';
 export interface FileTreePolicy {
     /** Host authority intersects mandatory exclusions, including for external captures. */
@@ -30,15 +31,16 @@ export declare function canonicalPath({ relativePath, maxDepth }: {
 export declare function assertCandidatePaths({ paths }: {
     paths: readonly string[];
 }, _options?: {}): void;
-/** Platform owns physical containment and bounded traversal; this adapter adds project policy.
+/** The injected reader owns physical containment and bounded traversal; this adapter adds project policy.
  * @complexity Construction O(1); path checks O(depth), listing bounded by configured limits.
  */
-export declare function createProjectPaths({ root, policy, limits }: {
+export declare function createProjectPaths({ root, policy, limits, filesystem }: {
     root: string;
     policy: FileTreePolicy;
     limits: ProjectLimits;
+    filesystem: ProjectFilesystemPort;
 }, _options?: {}): {
-    reader: import("@jini-ai/platform/fs").GuardedFileReader;
+    reader: import("@jini-ai/core/filesystem").GuardedFileReader;
     check: ({ relativePath }: {
         relativePath: string;
     }) => string;

package/dist/node/paths.js

@@ -1,4 +1,3 @@
-import { createGuardedFileReader, createNodeGuardedReaderFilesystem } from '@jini-ai/platform/fs';
 import { ProjectError } from '../core/project.js';
 export const DEFAULT_PROJECT_LIMITS = {
     maxFiles: 2_000, maxFileBytes: 2 * 1024 * 1024, maxTreeBytes: 64 * 1024 * 1024,
@@ -65,11 +64,11 @@ export function assertCandidatePaths({ paths }, _options = {}) {
         }
     }
 }
-/** Platform owns physical containment and bounded traversal; this adapter adds project policy.
+/** The injected reader owns physical containment and bounded traversal; this adapter adds project policy.
  * @complexity Construction O(1); path checks O(depth), listing bounded by configured limits.
  */
-export function createProjectPaths({ root, policy, limits }, _options = {}) {
-    const reader = createGuardedFileReader({ rootPath: root, filesystem: createNodeGuardedReaderFilesystem({}),
+export function createProjectPaths({ root, policy, limits, filesystem }, _options = {}) {
+    const reader = filesystem.createReader({ rootPath: root,
         denyRules: { segments: EXCLUDED, filenamePatterns: [/^\.env/i, ATOMIC_TEMP] },
         limits: { maxFileBytes: limits.maxFileBytes, binarySniffBytes: 1024,
             maxListedFiles: limits.maxFiles + 1, maxWalkDepth: limits.maxDepth, maxWalkEntries: limits.maxFiles * (limits.maxDepth + 1) },

package/dist/node/project.d.ts

@@ -1,6 +1,9 @@
+import type { ProjectFilesystemPort } from '../core/project-filesystem.js';
 import { type FileTreeProject, type ProjectLimits, type ProjectValidator } from '../core/project.js';
 import { type FileTreePolicy } from './paths.js';
 export interface OpenFileTreeProjectInput {
+    /** Native effects are supplied by the host composition root. */
+    readonly filesystem: ProjectFilesystemPort;
     readonly root: string;
     /** Private host-owned directory outside the watched and served application tree. */
     readonly stateDir: string;

package/dist/node/project.js

@@ -1,5 +1,5 @@
 import { createEditHistory } from '../core/history.js';
-import { FsFilePathError } from '@jini-ai/platform/fs';
+import { FsFilePathError } from '@jini-ai/core/filesystem';
 import { ProjectError } from '../core/project.js';
 import { assertCandidatePaths, createProjectPaths, projectLimits } from './paths.js';
 import { createProjectStore, prepareDirectories, revisionToken } from './store.js';
@@ -117,8 +117,8 @@ export async function openFileTreeProject(input, options = {}) {
         throw new TypeError('historyLimit must be positive');
     try {
         const directories = await prepareDirectories(input);
-        const paths = createProjectPaths({ root: directories.root, policy: input.policy, limits });
-        const store = createProjectStore({ ...directories, paths, limits });
+        const paths = createProjectPaths({ root: directories.root, policy: input.policy, limits, filesystem: input.filesystem });
+        const store = createProjectStore({ ...directories, paths, limits, filesystem: input.filesystem });
         const project = assembleProject({ store, paths, limits, historyLimit, validator: input.validator });
         await project.capture();
         return project;

package/dist/node/store.d.ts

@@ -1,3 +1,4 @@
+import type { ProjectFilesystemPort } from '../core/project-filesystem.js';
 import { type ProjectLimits, type RevisionToken } from '../core/project.js';
 import { type ProjectPaths } from './paths.js';
 export interface ManifestFile {
@@ -30,6 +31,7 @@ export interface StoreInput {
     stateDir: string;
     paths: ProjectPaths;
     limits: ProjectLimits;
+    filesystem: ProjectFilesystemPort;
 }
 export interface StoreOptions {
     /** Internal deterministic process-crash seam; never needed by the public factory. */
@@ -55,7 +57,7 @@ export declare function prepareDirectories({ root, stateDir }: {
 /** Content-addressed persistence and idempotent roll-forward. Call mutations inside locked().
  * @complexity O(bytes + files log files + files × depth²) for capture; memory bounded by maxTreeBytes.
  */
-export declare function createProjectStore({ root, stateDir, paths, limits }: StoreInput, options?: StoreOptions): {
+export declare function createProjectStore({ root, stateDir, paths, limits, filesystem }: StoreInput, options?: StoreOptions): {
     readCurrent: () => Promise<Current | null>;
     manifest: ({ revisionId }: {
         revisionId: string;

package/dist/node/store.js

@@ -1,7 +1,6 @@
 import * as fs from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
-import { withFileLock, writeFileAtomicAsync, writeJsonFileAtomicAsync } from '@jini-ai/platform/fs';
 import { ProjectError } from '../core/project.js';
 import { assertCandidatePaths, portablePathKey } from './paths.js';
 function fingerprint(info) {
@@ -169,7 +168,7 @@ export async function prepareDirectories({ root, stateDir }, _options = {}) {
 /** Content-addressed persistence and idempotent roll-forward. Call mutations inside locked().
  * @complexity O(bytes + files log files + files × depth²) for capture; memory bounded by maxTreeBytes.
  */
-export function createProjectStore({ root, stateDir, paths, limits }, options = {}) {
+export function createProjectStore({ root, stateDir, paths, limits, filesystem }, options = {}) {
     const currentPath = resolve(stateDir, 'current.json');
     const objectPath = (hash) => { assertHash(hash); return resolve(stateDir, 'objects', hash); };
     const manifestPath = (hash) => { assertHash(hash); return resolve(stateDir, 'manifests', `${hash}.json`); };
@@ -223,7 +222,7 @@ export function createProjectStore({ root, stateDir, paths, limits }, options =
         if (existing)
             await manifest({ revisionId });
         else
-            await writeJsonFileAtomicAsync({ filePath: manifestPath(revisionId), data: value }, { createParent: true });
+            await filesystem.writeJsonFileAtomicAsync({ filePath: manifestPath(revisionId), data: value }, { createParent: true });
         await checkpoint('manifest');
         return revisionId;
     }
@@ -232,7 +231,7 @@ export function createProjectStore({ root, stateDir, paths, limits }, options =
         if (exists)
             await object({ file });
         else
-            await writeFileAtomicAsync({ filePath: objectPath(file.hash), content: bytes }, { createParent: true });
+            await filesystem.writeFileAtomicAsync({ filePath: objectPath(file.hash), content: bytes }, { createParent: true });
     }
     async function observations({ files }) {
         const result = Object.create(null);
@@ -348,12 +347,12 @@ export function createProjectStore({ root, stateDir, paths, limits }, options =
         for (const file of writes)
             await removeBlockingFolder({ path: file.path, before });
         for (const file of writes) {
-            await writeFileAtomicAsync({ filePath: await regularPath({ paths, path: file.path }), content: bytes.get(file.path) }, { createParent: true, refuseSymlink: true, defaultMode: 0o644 });
+            await filesystem.writeFileAtomicAsync({ filePath: await regularPath({ paths, path: file.path }), content: bytes.get(file.path) }, { createParent: true, refuseSymlink: true, defaultMode: 0o644 });
             await checkpoint('write');
         }
         await prune({ before, after });
         const settled = { ...current, pending: null, observed: await observations(after) };
-        await writeJsonFileAtomicAsync({ filePath: currentPath, data: settled });
+        await filesystem.writeJsonFileAtomicAsync({ filePath: currentPath, data: settled });
         await checkpoint('clear');
         return settled;
     }
@@ -435,7 +434,7 @@ export function createProjectStore({ root, stateDir, paths, limits }, options =
             throw new ProjectError({ code: 'LIMIT', message: 'generation exhausted' });
         const next = { version: 1, root, revision: revisionId, generation: (current?.generation ?? 0) + 1,
             pending: captured ? null : { from: current?.revision ?? null }, observed: captured ?? {} };
-        await writeJsonFileAtomicAsync({ filePath: currentPath, data: next });
+        await filesystem.writeJsonFileAtomicAsync({ filePath: currentPath, data: next });
         await checkpoint('journal');
         return captured ? next : materialize({ current: next });
     }
@@ -444,7 +443,7 @@ export function createProjectStore({ root, stateDir, paths, limits }, options =
         if (JSON.stringify(current.observed) === JSON.stringify(observed))
             return current;
         const next = { ...current, observed };
-        await writeJsonFileAtomicAsync({ filePath: currentPath, data: next });
+        await filesystem.writeJsonFileAtomicAsync({ filePath: currentPath, data: next });
         return next;
     }
     /** Both stacks pin manifests and blobs. Expired snapshots do not pin storage indefinitely. */
@@ -459,7 +458,7 @@ export function createProjectStore({ root, stateDir, paths, limits }, options =
     }
     return {
         readCurrent, manifest, object, prepare, scan, select, collect, preflight, observe, readWorkingFile,
-        locked: (run) => withFileLock({ lockPath: resolve(stateDir, 'project.lock'), run }, { staleMs: Infinity, createParent: true }),
+        locked: (run) => filesystem.withFileLock({ lockPath: resolve(stateDir, 'project.lock'), run }, { staleMs: Infinity, createParent: true }),
         recover,
     };
 }

package/dist/react/session.d.ts

@@ -1,3 +1,4 @@
 /** Compatibility re-export; the implementation is framework-free. */
-export * from "../session.js";
+export * from "../core/session.js";
+export * from "../tools.js";
 //# sourceMappingURL=session.d.ts.map

package/dist/react/session.js

@@ -1,3 +1,4 @@
 /** Compatibility re-export; the implementation is framework-free. */
-export * from "../session.js";
+export * from "../core/session.js";
+export * from "../tools.js";
 //# sourceMappingURL=session.js.map

package/dist/session.d.ts

@@ -1,116 +1,4 @@
-/**
- * @module session
- *
- * `VibecodingSession` — the framework-free stateful object over
- * `./core`'s `EditTarget` + `EditHistory`. Everything else in `./react` (the hook, the tool
- * registrations, the presentational components) reads and drives an artifact through this seam
- * rather than touching `EditTarget`/`EditHistory` directly, for one reason: a tool call arrives
- * from the chat's execution path, not from a React event handler, so the thing tool handlers call
- * into cannot be React state — it has to be a plain, subscribable object a `useSyncExternalStore`
- * hook can also read. This module is React-free and exported with the tools from `./session`.
- *
- * ## Why part content is cached rather than re-read on every render
- *
- * `EditTarget.readPart` is a host call — for the `html` target it is cheap (a string slice), but
- * the port makes no such promise for every target (a filesystem or sandbox-backed host could hit a
- * network round trip per part). Re-reading every listed part's content on every `refresh()` would
- * turn "the operator opened the file viewer" into an O(part count) fan-out of host calls, and
- * nothing here can assume that count stays small — see `./core/target.ts`'s own doc on why
- * `listParts` is the allowlist, not a bound on its size. So `refresh()` only calls `listParts()`;
- * content is fetched lazily, per id, through `readPart()`, and cached. Every mutating operation
- * below (`applyEdits`, `undo`, `redo`, `restoreSnapshot`) in a default session knows the exact before/after
- * content it just wrote — `./core/apply.ts`'s `ProposedEdit`, `./core/history.ts`'s
- * `PartChange.before`/`.after` — so the cache is updated from that data directly instead of
- * re-reading the part it just wrote back from the host. Project sessions clear caches instead:
- * their history entries hold revision pointers, and external tools may have changed file bytes.
- */
-import type { ApplyOutcome, PartId, PartRef, Snapshot } from './core/types.js';
-import type { EditTarget } from './core/target.js';
-import { type ProposedEdit } from './core/apply.js';
-import { type EditHistory, type EditHistoryOptions, type HistoryEntry } from './core/history.js';
-export interface VibecodingSessionArgs {
-    /** The host's artifact port. See `./core/target.ts`. */
-    readonly target: EditTarget;
-}
-export interface VibecodingSessionOptions {
-    /** Forwarded to `createEditHistory`. See `./core/history.ts`'s `EditHistoryOptions`. */
-    readonly historyOptions?: EditHistoryOptions;
-    /** A project supplies its guarded pointer history instead of a per-file stack. */
-    readonly history?: EditHistory;
-    /** Whole-turn mutation; owns its history recording and returns aligned outcomes. */
-    readonly applyTurn?: (input: {
-        readonly edits: readonly ProposedEdit[];
-    }, options?: {
-        readonly label?: string;
-    }) => Promise<readonly ApplyOutcome[]>;
-}
-/**
- * Immutable, point-in-time read of a session. `getSnapshot()` returns the same object reference
- * until something actually changes — required for `useSyncExternalStore`, which re-renders a
- * subscriber whenever the reference it reads changes, not whenever it is merely called again.
- */
-export interface VibecodingSessionSnapshot {
-    /** `'idle'` until the first `refresh()` resolves; `'error'` reflects the most recent failure, not
-     *  a permanently wedged session — a subsequent successful call returns it to `'ready'`. */
-    readonly status: 'idle' | 'loading' | 'ready' | 'error';
-    /** Every part the host currently advertises, in `EditTarget.listParts()`'s own order. */
-    readonly parts: readonly PartRef[];
-    /** Cached content, keyed by part id. A part absent from this map has not been read yet — see
-     *  this module's doc for why content is lazy rather than eagerly fetched for every part. */
-    readonly partContent: ReadonlyMap<PartId, string>;
-    readonly canUndo: boolean;
-    readonly canRedo: boolean;
-    /** The most recent operation's failure message, if any. Cleared by the next successful call. */
-    readonly lastError: string | undefined;
-}
-export interface ApplyEditsResult {
-    readonly outcomes: readonly ApplyOutcome[];
-    /** See `./core/apply.ts`'s `correctionsFor` — the subset a caller feeds back to the model. */
-    readonly corrections: readonly {
-        readonly id: PartId;
-        readonly reason: string;
-    }[];
-}
-export interface VibecodingSession {
-    /** The underlying port, for a caller (or test) that needs it directly — e.g. to read the whole
-     *  document a host-specific target stores, which is outside this generic session's vocabulary. */
-    readonly target: EditTarget;
-    /** The underlying undo/redo stack, for a caller that needs `.entries()` for a history UI. */
-    readonly history: EditHistory;
-    getSnapshot(): VibecodingSessionSnapshot;
-    /** Returns an unsubscribe function; the React hook adapts this object API for React. */
-    subscribe(args: {
-        readonly listener: () => void;
-    }): () => void;
-    /** Re-lists parts from the host. Does not re-read content — see this module's doc. */
-    refresh(): Promise<void>;
-    /** Cached content for `id`, fetching once from the host on first request. */
-    readPart(args: {
-        readonly id: PartId;
-    }): Promise<string>;
-    /** Applies `edits` as one undoable transaction and updates the cache from the edits themselves. */
-    applyEdits(requiredArgs: {
-        readonly edits: readonly ProposedEdit[];
-    }, optionalArgs?: {
-        readonly label?: string;
-    }): Promise<ApplyEditsResult>;
-    undo(): Promise<HistoryEntry | null>;
-    redo(): Promise<HistoryEntry | null>;
-    takeSnapshot(): Promise<Snapshot>;
-    restoreSnapshot(args: {
-        readonly snapshot: Snapshot;
-    }): Promise<HistoryEntry | null>;
-}
-/**
- * Builds a session over `target`, with private history by default or injected project history.
- * Injected applyTurn owns whole-turn recording; this session owns notifications and cache invalidation.
- *
- * The returned session starts in `'idle'` with no parts listed — call `refresh()` (or let
- * `useVibecodingSession` do it on mount) to populate it. Nothing here triggers I/O eagerly, so
- * constructing a session has no side effect a caller needs to clean up.
- *
- * @complexity Construction is O(1). See each method for its own cost.
- */
-export declare function createVibecodingSession({ target }: VibecodingSessionArgs, options?: VibecodingSessionOptions): VibecodingSession;
+/** Compatibility path; the framework-free session is shared with the React integration. */
+export * from "./core/session.js";
 export * from "./tools.js";
 //# sourceMappingURL=session.d.ts.map

package/dist/session.js

@@ -1,179 +1,4 @@
-import { applyEdits as applyEditsToTarget, correctionsFor } from './core/apply.js';
-import { createEditHistory } from './core/history.js';
-const READY_ERROR = undefined;
-/**
- * Builds a session over `target`, with private history by default or injected project history.
- * Injected applyTurn owns whole-turn recording; this session owns notifications and cache invalidation.
- *
- * The returned session starts in `'idle'` with no parts listed — call `refresh()` (or let
- * `useVibecodingSession` do it on mount) to populate it. Nothing here triggers I/O eagerly, so
- * constructing a session has no side effect a caller needs to clean up.
- *
- * @complexity Construction is O(1). See each method for its own cost.
- */
-export function createVibecodingSession({ target }, options = {}) {
-    const history = options.history ?? createEditHistory({ target }, options.historyOptions);
-    // Project turns write through revision pointers, so cached part content is never reusable after them.
-    const applyTurn = options.applyTurn;
-    const listeners = new Set();
-    const partContent = new Map();
-    let current = {
-        status: 'idle',
-        parts: [],
-        partContent,
-        canUndo: history.canUndo(),
-        canRedo: history.canRedo(),
-        lastError: READY_ERROR,
-    };
-    /** Replaces `current` with a fresh object carrying `patch`, then notifies subscribers. A fresh
-     *  `partContent` Map reference is handed out only when the map's contents actually changed
-     *  (callers pass a new Map in `patch` for that case); reusing the same Map reference otherwise
-     *  is what keeps an unrelated status change (e.g. `'loading'` -> `'ready'`) from invalidating a
-     *  component's memoized read of `partContent`. */
-    function commit(patch) {
-        current = { ...current, ...patch };
-        for (const listener of listeners)
-            listener();
-    }
-    /**
-     * Runs `work`, tagging the session `'loading'` -> `'ready'`/`'error'` and always returning
-     * control to the caller — a rejection is recorded as `lastError` AND rethrown, so a component
-     * can render `lastError` passively while a tool handler that needs to fail loudly still can.
-     *
-     * `work` returns its data `patch` alongside its `result` rather than calling `commit` itself, so
-     * the success path here can fold that patch into the SAME commit as the `'ready'` status
-     * transition — one notification per operation instead of two, which matters to a
-     * `useSyncExternalStore` subscriber re-rendering on every commit.
-     */
-    async function run(work) {
-        commit({ status: 'loading' });
-        try {
-            const { result, patch } = await work();
-            commit({ ...patch, status: 'ready', lastError: READY_ERROR });
-            return result;
-        }
-        catch (thrown) {
-            const message = thrown instanceof Error ? thrown.message : String(thrown);
-            if (applyTurn)
-                partContent.clear();
-            commit({ status: 'error', lastError: message, partContent: new Map(partContent), canUndo: history.canUndo(), canRedo: history.canRedo() });
-            throw thrown;
-        }
-    }
-    /** Mirrors a replayed change in the cache. Undoing creation keeps empty content because the
-     *  target's upsert port has no delete operation; see `./core/history.ts`. */
-    function cacheChange(change, side) {
-        partContent.set(change.id, side === 'after' ? change.after : change.before);
-    }
-    /** Mirrors a recorded snapshot restore in the cache and re-reads the part list it may have grown. */
-    async function restoredPatch(entry) {
-        if (applyTurn)
-            partContent.clear();
-        else
-            for (const change of entry.changes)
-                cacheChange(change, 'after');
-        const parts = await target.listParts();
-        return { parts, partContent: new Map(partContent), canUndo: history.canUndo(), canRedo: history.canRedo() };
-    }
-    return {
-        target,
-        history,
-        getSnapshot: () => current,
-        subscribe({ listener }) {
-            listeners.add(listener);
-            return () => listeners.delete(listener);
-        },
-        refresh: () => run(async () => {
-            const parts = await target.listParts();
-            if (applyTurn)
-                partContent.clear();
-            const known = new Set(parts.map((p) => p.id));
-            // Drop cached content for parts the host no longer lists — stale content for an
-            // unaddressable id would otherwise linger forever with nothing to invalidate it.
-            for (const id of partContent.keys())
-                if (!known.has(id))
-                    partContent.delete(id);
-            return {
-                result: undefined,
-                patch: { parts, partContent: new Map(partContent), canUndo: history.canUndo(), canRedo: history.canRedo() },
-            };
-        }),
-        readPart: ({ id }) => run(async () => {
-            const cached = applyTurn ? undefined : partContent.get(id);
-            if (cached !== undefined)
-                return { result: cached, patch: {} };
-            if (applyTurn)
-                partContent.clear();
-            const content = await target.readPart({ id });
-            partContent.set(id, content);
-            return { result: content, patch: { partContent: new Map(partContent), canUndo: history.canUndo(), canRedo: history.canRedo() } };
-        }),
-        applyEdits: ({ edits }, options = {}) => run(async () => {
-            const outcomes = await (applyTurn
-                ? applyTurn({ edits }, options)
-                : history.transaction({ work: (recording) => applyEditsToTarget({ target: recording, edits }) }, options));
-            if (applyTurn)
-                partContent.clear();
-            // Outcomes are aligned with proposals, including repeated ids. Matching only by id
-            // would cache the first proposal instead of the last successful write for that part.
-            // This pass is O(edits.length), with no additional reads through the target port.
-            for (const [index, outcome] of outcomes.entries()) {
-                if (outcome.status !== 'applied')
-                    continue;
-                const edit = edits[index];
-                if (edit && !applyTurn)
-                    partContent.set(edit.id, edit.content);
-            }
-            const parts = await target.listParts();
-            return {
-                result: { outcomes, corrections: correctionsFor({ outcomes }) },
-                patch: {
-                    parts,
-                    partContent: new Map(partContent),
-                    canUndo: history.canUndo(),
-                    canRedo: history.canRedo(),
-                },
-            };
-        }),
-        undo: () => run(async () => {
-            const entry = await history.undo();
-            if (!entry)
-                return { result: entry, patch: {} };
-            // Undo replays in reverse order. Repeated ids must leave the earliest before value
-            // cached, matching what history wrote to the target.
-            if (applyTurn)
-                partContent.clear();
-            else
-                for (const change of [...entry.changes].reverse())
-                    cacheChange(change, 'before');
-            const parts = applyTurn ? await target.listParts() : current.parts;
-            return {
-                result: entry,
-                patch: { parts, partContent: new Map(partContent), canUndo: history.canUndo(), canRedo: history.canRedo() },
-            };
-        }),
-        redo: () => run(async () => {
-            const entry = await history.redo();
-            if (!entry)
-                return { result: entry, patch: {} };
-            if (applyTurn)
-                partContent.clear();
-            else
-                for (const change of entry.changes)
-                    cacheChange(change, 'after');
-            const parts = applyTurn ? await target.listParts() : current.parts;
-            return {
-                result: entry,
-                patch: { parts, partContent: new Map(partContent), canUndo: history.canUndo(), canRedo: history.canRedo() },
-            };
-        }),
-        takeSnapshot: () => run(async () => ({ result: await target.snapshot(), patch: {} })),
-        restoreSnapshot: ({ snapshot }) => run(async () => {
-            const entry = await history.restore({ snapshot });
-            // A restore that already matched records no entry and changes nothing to mirror.
-            return { result: entry, patch: entry ? await restoredPatch(entry) : {} };
-        }),
-    };
-}
+/** Compatibility path; the framework-free session is shared with the React integration. */
+export * from "./core/session.js";
 export * from "./tools.js";
 //# sourceMappingURL=session.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/vibecoding",
-  "version": "0.6.11",
+  "version": "0.6.15-rc.1",
   "description": "Conversational artifact authoring: a target-agnostic edit loop — addressable parts, validated replace, operation-level undo/redo, and per-turn snapshot/rewind. Framework-free in `/core`; tagged-region HTML documents behind ./html; filesystem targets behind ./node and the chat/preview surface behind ./react.",
   "license": "Apache-2.0",
   "repository": {
@@ -87,11 +87,11 @@
     "typescript": "^5.9.2",
     "vitest": "^3.2.4",
     "parse5": "^8.0.1",
-    "@jini-ai/core": "0.6.11"
+    "@jini-ai/core": "0.6.15-rc.1",
+    "@jini-ai/platform": "^0.6.15-rc.1"
   },
   "dependencies": {
-    "@jini-ai/platform": "^0.6.11",
-    "@jini-ai/core": "^0.6.11"
+    "@jini-ai/core": "^0.6.15-rc.1"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",