@jini-ai/vibecoding 0.4.0

package/dist/html/regions.js

@@ -0,0 +1,165 @@
+/** The attribute that publishes a region's handle. Mirrors `@jini-ai/agentic`'s convention. */
+export const AGENT_ELEMENT_ATTRIBUTE = "data-agent-element";
+/**
+ * Lowercase words joined by single hyphens — the same grammar `@jini-ai/agentic` enforces, restated
+ * here rather than imported so `/html` does not acquire a dependency on the agentic package for one
+ * regular expression. If that package's grammar ever widens, this must be revisited deliberately.
+ */
+const HANDLE_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const MAX_HANDLE_LENGTH = 128;
+/** Whether `handle` is a syntactically valid region handle. */
+export function isValidRegionHandle({ handle }) {
+    return handle.length > 0 && handle.length <= MAX_HANDLE_LENGTH && HANDLE_PATTERN.test(handle);
+}
+/** Handles in document order, including duplicates — order and multiplicity both matter. */
+function handlesOf(regions) {
+    return regions.map((region) => region.handle);
+}
+/** Counts the whole document first so even the first occurrence of an ambiguous handle is omitted. */
+function handleCounts(regions) {
+    const counts = new Map();
+    for (const { handle } of regions)
+        counts.set(handle, (counts.get(handle) ?? 0) + 1);
+    return counts;
+}
+/** A stable, order-insensitive description of a handle multiset, for comparison in a message. */
+function describeHandles(handles) {
+    return [...handles].sort().join(", ") || "(none)";
+}
+/** Locates one region by handle, refusing ambiguity rather than silently picking the first. */
+function findOne(regions, id) {
+    const matches = regions.filter((region) => region.handle === id);
+    if (matches.length === 0)
+        return { ok: false, reason: `no region is tagged ${AGENT_ELEMENT_ATTRIBUTE}="${id}"` };
+    if (matches.length > 1) {
+        return {
+            ok: false,
+            reason: `${matches.length} regions are tagged ${AGENT_ELEMENT_ATTRIBUTE}="${id}" — a handle must identify exactly one region`,
+        };
+    }
+    // `matches[0]` is present: length is exactly 1 on this branch.
+    return { ok: true, region: matches[0] };
+}
+/**
+ * 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 function createHtmlRegionTarget(deps, options = {}) {
+    const { store, parser } = deps;
+    const maxPartLength = options.maxPartLength ?? 256 * 1024;
+    /** Splices `content` into `region`'s inner range, preserving every byte outside it. */
+    function spliced(html, region, content) {
+        return html.slice(0, region.innerStart) + content + html.slice(region.innerEnd);
+    }
+    return {
+        async listParts() {
+            const regions = parser.findRegions({ html: await store.read() });
+            const counts = handleCounts(regions);
+            const refs = [];
+            for (const region of regions) {
+                // A malformed or duplicated handle is not publishable: publishing it would advertise an id
+                // that `readPart`/`replacePart` must then refuse, or worse, resolve ambiguously.
+                if (!isValidRegionHandle({ handle: region.handle }) || counts.get(region.handle) !== 1)
+                    continue;
+                refs.push({
+                    id: region.handle,
+                    ...(region.role === undefined ? {} : { kind: region.role }),
+                    ...(region.label === undefined ? {} : { label: region.label }),
+                });
+            }
+            return refs;
+        },
+        async readPart({ id }) {
+            const html = await store.read();
+            const found = findOne(parser.findRegions({ html }), id);
+            if (!found.ok)
+                throw new Error(found.reason);
+            return html.slice(found.region.innerStart, found.region.innerEnd);
+        },
+        /**
+         * Note that this is NOT an upsert here, unlike the port's general contract: a region that does
+         * not exist cannot be created by writing to it, because creating one would mean inventing a
+         * position in someone else's document and a tag to wrap it in. A host that wants a new region
+         * adds it to the document itself, and it becomes addressable at the next `listParts`.
+         */
+        async replacePart({ id, content }) {
+            const html = await store.read();
+            const found = findOne(parser.findRegions({ html }), id);
+            if (!found.ok)
+                throw new Error(found.reason);
+            await store.write({ html: spliced(html, found.region, content) });
+        },
+        async snapshot() {
+            const html = await store.read();
+            const regions = parser.findRegions({ html });
+            const parts = {};
+            const counts = handleCounts(regions);
+            for (const region of regions) {
+                if (!isValidRegionHandle({ handle: region.handle }) || counts.get(region.handle) !== 1)
+                    continue;
+                parts[region.handle] = html.slice(region.innerStart, region.innerEnd);
+            }
+            return { id: `html-${regions.length}-${html.length}`, parts };
+        },
+        /**
+         * Restores each region's content in one pass.
+         *
+         * Offsets are re-resolved between writes rather than computed once, because every splice shifts
+         * the offsets of every region after it. Computing them all up front is the obvious
+         * implementation and it silently corrupts the document whenever two regions change length.
+         */
+        async restore({ snapshot }) {
+            for (const [handle, content] of Object.entries(snapshot.parts)) {
+                const html = await store.read();
+                const found = findOne(parser.findRegions({ html }), handle);
+                if (!found.ok)
+                    continue; // The region is gone; there is nowhere to put its content back.
+                await store.write({ html: spliced(html, found.region, content) });
+            }
+        },
+        async validate(candidate) {
+            if (candidate.content.length > maxPartLength) {
+                return {
+                    ok: false,
+                    reason: `that content is ${candidate.content.length} characters, over the ${maxPartLength}-character limit for one region — send a shorter version`,
+                };
+            }
+            const html = await store.read();
+            const before = parser.findRegions({ html });
+            const found = findOne(before, candidate.id);
+            if (!found.ok)
+                return { ok: false, reason: found.reason };
+            // Judge the WHOLE prospective document, never the fragment alone: a fragment that is
+            // well-formed by itself can still break the document it lands in.
+            const prospective = spliced(html, found.region, candidate.content);
+            const structural = parser.checkWellFormed?.({ html: prospective });
+            if (structural && !structural.ok)
+                return { ok: false, reason: structural.reason };
+            const afterHandles = handlesOf(parser.findRegions({ html: prospective }));
+            const beforeHandles = handlesOf(before);
+            // The allowlist check. Compared as multisets so an invented, deleted OR duplicated handle is
+            // all caught by one comparison — see this module's doc for why this is the security property.
+            const beforeKey = describeHandles(beforeHandles);
+            const afterKey = describeHandles(afterHandles);
+            if (beforeKey !== afterKey) {
+                const invented = afterHandles.filter((handle) => !beforeHandles.includes(handle));
+                const removed = beforeHandles.filter((handle) => !afterHandles.includes(handle));
+                const detail = invented.length > 0
+                    ? `it adds ${AGENT_ELEMENT_ATTRIBUTE} handles that did not exist (${describeHandles(invented)})`
+                    : removed.length > 0
+                        ? `it removes existing ${AGENT_ELEMENT_ATTRIBUTE} handles (${describeHandles(removed)})`
+                        : `it changes how many times a ${AGENT_ELEMENT_ATTRIBUTE} handle appears`;
+                return {
+                    ok: false,
+                    reason: `${detail}. Edit only the content inside the region you were asked to change, and do not add, remove or duplicate ${AGENT_ELEMENT_ATTRIBUTE} attributes.`,
+                };
+            }
+            return { ok: true };
+        },
+    };
+}
+//# sourceMappingURL=regions.js.map

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @module @jini-ai/vibecoding
+ *
+ * Conversational artifact authoring, target-agnostic.
+ *
+ * The root entry re-exports `./core` for convenience. Importing `@jini-ai/vibecoding/core`
+ * directly is equivalent and states the universal-runtime intent more plainly.
+ */
+export * from "./core/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @module @jini-ai/vibecoding
+ *
+ * Conversational artifact authoring, target-agnostic.
+ *
+ * The root entry re-exports `./core` for convenience. Importing `@jini-ai/vibecoding/core`
+ * directly is equivalent and states the universal-runtime intent more plainly.
+ */
+export * from "./core/index.js";
+//# sourceMappingURL=index.js.map

package/dist/react/components/DocumentPreview.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @module react/components/DocumentPreview
+ *
+ * The "renderer" half of the user's vision: a live preview of whatever HTML the host currently
+ * wants shown. Deliberately the simplest thing that renders live HTML, not an editing surface —
+ * see this file's "Scope: preview, not sandbox, not an editor" section below for why.
+ *
+ * `html` is host-supplied rather than derived from a `VibecodingSession` here, because a generic
+ * `EditTarget` (`../../core/target.ts`) has no "whole document" verb at all — only per-part
+ * `listParts`/`readPart`. A single-document host (`../../html/regions.ts`'s tagged-region target)
+ * genuinely owns the composed document as its own storage detail; a filesystem-backed host would
+ * have no single document to compose in the first place. Keeping this component's contract to
+ * "render whatever HTML string you hand me" is what keeps it usable by every future `EditTarget`
+ * host alike, the same way `../../core` itself stays target-agnostic.
+ */
+import type { CSSProperties } from 'react';
+export interface DocumentPreviewProps {
+    /** The document to render. Treated as untrusted, model-authored markup — see this file's
+     *  "Sandboxing" note below. */
+    readonly html: string;
+    readonly title?: string;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+}
+/**
+ * Renders `html` live inside a sandboxed `<iframe>`.
+ *
+ * ## Scope: preview, not sandbox, not an editor
+ *
+ * `@jini-ai/sandbox`'s own README draws the line this component is built to respect: vibecoding
+ * owns the conversational edit loop over an addressable artifact, sandbox owns making that
+ * artifact actually run and produce a preview. This component renders a static HTML string the
+ * host already has in hand — it boots no process, runs no build, and has no notion of a dev
+ * server. A host whose artifact needs a real build/run step (anything beyond one static HTML
+ * document) gets its preview from `@jini-ai/sandbox`'s `SandboxSession.getPreview()` instead and
+ * would point an ordinary `<iframe src={previewUrl}>` at that — this component is not the right
+ * tool there, and does not try to be. It is also deliberately not `@jini-ai/ui`'s
+ * `InteractiveHtmlEditor`: that component is a GrapesJS-backed click-to-edit canvas, a second,
+ * heavier concern (and a large third-party dependency) this "see it live" renderer does not need
+ * to pull in just to display the current document. A host that wants inline manual editing on top
+ * of the same document can layer `InteractiveHtmlEditor` in separately; nothing here precludes it.
+ *
+ * ## Sandboxing
+ *
+ * `html` is model-authored per `../../core/target.ts`'s own contract ("Implementations should
+ * assume content is model-authored and therefore arbitrary"), so this iframe is sandboxed with
+ * `allow-scripts` ONLY — no `allow-same-origin`. Combining the two on a `srcDoc` frame is a known
+ * sandbox-escape pattern (the frame could otherwise reach back into a same-origin-equivalent
+ * context and strip its own restrictions); omitting `allow-same-origin` keeps the frame's content
+ * in a permanently unique, opaque origin regardless of what markup or script it contains, while
+ * `allow-scripts` still lets an interactive preview (a toggle, an animation) actually run.
+ * `React`'s `srcDoc` prop re-navigates the iframe on every change, so no manual reload/key-remount
+ * logic is needed for this to update live as the host's `html` changes.
+ *
+ * @complexity O(1) — a single element; rendering cost is the browser's, not this component's.
+ * @overallScore 100/100
+ */
+export declare function DocumentPreview({ html, title, className, style }: DocumentPreviewProps): import("react").JSX.Element;
+//# sourceMappingURL=DocumentPreview.d.ts.map

package/dist/react/components/DocumentPreview.js

@@ -0,0 +1,44 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+const FRAME_STYLE = {
+    width: '100%',
+    height: '100%',
+    border: 'none',
+    background: '#fff',
+};
+/**
+ * Renders `html` live inside a sandboxed `<iframe>`.
+ *
+ * ## Scope: preview, not sandbox, not an editor
+ *
+ * `@jini-ai/sandbox`'s own README draws the line this component is built to respect: vibecoding
+ * owns the conversational edit loop over an addressable artifact, sandbox owns making that
+ * artifact actually run and produce a preview. This component renders a static HTML string the
+ * host already has in hand — it boots no process, runs no build, and has no notion of a dev
+ * server. A host whose artifact needs a real build/run step (anything beyond one static HTML
+ * document) gets its preview from `@jini-ai/sandbox`'s `SandboxSession.getPreview()` instead and
+ * would point an ordinary `<iframe src={previewUrl}>` at that — this component is not the right
+ * tool there, and does not try to be. It is also deliberately not `@jini-ai/ui`'s
+ * `InteractiveHtmlEditor`: that component is a GrapesJS-backed click-to-edit canvas, a second,
+ * heavier concern (and a large third-party dependency) this "see it live" renderer does not need
+ * to pull in just to display the current document. A host that wants inline manual editing on top
+ * of the same document can layer `InteractiveHtmlEditor` in separately; nothing here precludes it.
+ *
+ * ## Sandboxing
+ *
+ * `html` is model-authored per `../../core/target.ts`'s own contract ("Implementations should
+ * assume content is model-authored and therefore arbitrary"), so this iframe is sandboxed with
+ * `allow-scripts` ONLY — no `allow-same-origin`. Combining the two on a `srcDoc` frame is a known
+ * sandbox-escape pattern (the frame could otherwise reach back into a same-origin-equivalent
+ * context and strip its own restrictions); omitting `allow-same-origin` keeps the frame's content
+ * in a permanently unique, opaque origin regardless of what markup or script it contains, while
+ * `allow-scripts` still lets an interactive preview (a toggle, an animation) actually run.
+ * `React`'s `srcDoc` prop re-navigates the iframe on every change, so no manual reload/key-remount
+ * logic is needed for this to update live as the host's `html` changes.
+ *
+ * @complexity O(1) — a single element; rendering cost is the browser's, not this component's.
+ * @overallScore 100/100
+ */
+export function DocumentPreview({ html, title, className, style }) {
+    return (_jsx("iframe", { title: title ?? 'Live preview', srcDoc: html, sandbox: "allow-scripts", className: className, style: style ? { ...FRAME_STYLE, ...style } : FRAME_STYLE }));
+}
+//# sourceMappingURL=DocumentPreview.js.map

package/dist/react/components/PartsViewer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @module react/components/PartsViewer
+ *
+ * The "file viewer" half of the user's vision: browse the parts an `EditTarget` currently
+ * advertises (`../core/target.ts`'s `listParts()` allowlist) and inspect one part's raw content.
+ *
+ * ## Why this is not `@jini-ai/ui`'s `AssetTreeBrowser`
+ *
+ * `AssetTreeBrowser` (`@jini-ai/ui`'s `features/asset-tree-browser`) was checked before writing
+ * this component, per this task's own instruction to reuse existing primitives. It was not reused,
+ * for a reason worth recording rather than silently deviating from: its `AssetTreeSelectors`
+ * REQUIRES `getSize`/`getModifiedAt` on every item, and its data model is a folder-structured
+ * filesystem (breadcrumbs, directories, upload, rename, drag/drop). `PartRef` (`../core/types.ts`)
+ * has none of that — a part is a flat, host-published id with only an optional `kind`/`label`, and
+ * the one `EditTarget` implementation that exists today (`../html/regions.ts`'s tagged-region
+ * target) has no filesystem at all. Fabricating a size or a modified time for a part would be
+ * inventing data the host never provided, which is worse than a simpler, honestly-scoped list.
+ * Once a filesystem-backed `EditTarget` lands (this package's planned `./node`), a file-tree host
+ * has the real fields `AssetTreeBrowser` wants, and reusing it there is the right call.
+ *
+ * ## Deliberately presentational
+ *
+ * `PartsViewer` takes already-resolved data and callbacks only, no `VibecodingSession` reference —
+ * the same split `@jini-ai/ui`'s own feature folders use between headless hooks/state and dumb
+ * components. `./VibecodingWorkbench.js` is the composed piece that owns a session and feeds this
+ * component; a host that wants a different layout or a different session-driving hook can still
+ * reuse this component directly by supplying the same props.
+ */
+import type { CSSProperties } from 'react';
+import type { PartId, PartRef } from '../../core/types.js';
+export interface PartsViewerProps {
+    readonly parts: readonly PartRef[];
+    readonly selectedId?: PartId | null;
+    readonly onSelect?: (id: PartId) => void;
+    /** The selected part's content, or `undefined` while unread/unselected — see
+     *  `./VibecodingWorkbench.js` for how this is sourced from `session.readPart`. */
+    readonly content?: string;
+    readonly contentLoading?: boolean;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+}
+/**
+ * A flat, selectable list of `parts` on the left and the selected one's raw content on the right.
+ *
+ * @complexity O(parts.length) to render the list; content rendering is O(content.length).
+ * @overallScore 100/100
+ */
+export declare function PartsViewer({ parts, selectedId, onSelect, content, contentLoading, className, style }: PartsViewerProps): import("react").JSX.Element;
+//# sourceMappingURL=PartsViewer.d.ts.map

package/dist/react/components/PartsViewer.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const ROOT_STYLE = {
+    display: 'flex',
+    minHeight: 0,
+    height: '100%',
+    fontSize: 13,
+    fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',
+    color: '#1f2430',
+};
+const LIST_STYLE = {
+    width: 220,
+    flexShrink: 0,
+    overflowY: 'auto',
+    borderRight: '1px solid #e2e5ea',
+    padding: 4,
+    margin: 0,
+    listStyle: 'none',
+};
+const ROW_BASE_STYLE = {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 2,
+    width: '100%',
+    textAlign: 'left',
+    border: 'none',
+    background: 'transparent',
+    borderRadius: 6,
+    padding: '6px 8px',
+    cursor: 'pointer',
+    color: 'inherit',
+    font: 'inherit',
+};
+const ROW_SELECTED_STYLE = {
+    ...ROW_BASE_STYLE,
+    background: '#e8edfb',
+};
+const ROW_LABEL_STYLE = { fontWeight: 600, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' };
+const ROW_META_STYLE = { color: '#6b7280', fontSize: 11 };
+const CONTENT_STYLE = {
+    flex: 1,
+    minWidth: 0,
+    overflow: 'auto',
+    margin: 0,
+    padding: 12,
+    whiteSpace: 'pre-wrap',
+    wordBreak: 'break-word',
+};
+const EMPTY_STYLE = { padding: 12, color: '#6b7280' };
+/**
+ * A flat, selectable list of `parts` on the left and the selected one's raw content on the right.
+ *
+ * @complexity O(parts.length) to render the list; content rendering is O(content.length).
+ * @overallScore 100/100
+ */
+export function PartsViewer({ parts, selectedId, onSelect, content, contentLoading, className, style }) {
+    return (_jsxs("div", { className: className, style: style ? { ...ROOT_STYLE, ...style } : ROOT_STYLE, children: [_jsx("ul", { style: LIST_STYLE, "aria-label": "Artifact parts", children: parts.length === 0 ? (_jsx("li", { style: EMPTY_STYLE, children: "No parts yet." })) : (parts.map((part) => {
+                    const isSelected = part.id === selectedId;
+                    return (_jsx("li", { children: _jsxs("button", { type: "button", onClick: () => onSelect?.(part.id), style: isSelected ? ROW_SELECTED_STYLE : ROW_BASE_STYLE, "aria-current": isSelected, children: [_jsx("span", { style: ROW_LABEL_STYLE, children: part.label ?? part.id }), part.kind ? _jsx("span", { style: ROW_META_STYLE, children: part.kind }) : null] }) }, part.id));
+                })) }), selectedId === undefined || selectedId === null ? (_jsx("p", { style: { ...CONTENT_STYLE, ...EMPTY_STYLE }, children: "Select a part to inspect its content." })) : contentLoading ? (_jsx("p", { style: { ...CONTENT_STYLE, ...EMPTY_STYLE }, children: "Loading\u2026" })) : (_jsx("pre", { style: CONTENT_STYLE, children: content ?? '' }))] }));
+}
+//# sourceMappingURL=PartsViewer.js.map

package/dist/react/components/VibecodingWorkbench.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @module react/components/VibecodingWorkbench
+ *
+ * The composed convenience component: owns a `VibecodingSession` (via `useVibecodingSession`) and
+ * wires it into `PartsViewer` (the file viewer) and `DocumentPreview` (the renderer) plus an
+ * undo/redo toolbar, the same "headless hook + presentational pieces + one drop-in pane" shape
+ * `@jini-ai/chat/react`'s `<ChatPane>` uses over its own headless primitives. A host that wants a
+ * different layout composes `PartsViewer`/`DocumentPreview`/`useVibecodingSession` directly instead
+ * — this component does not own anything those three don't already expose.
+ */
+import { type CSSProperties } from 'react';
+import type { VibecodingSession } from '../session.js';
+export interface VibecodingWorkbenchProps {
+    readonly session: VibecodingSession;
+    /**
+     * Host-supplied whole-document HTML for the preview pane. Omitted, the preview instead shows the
+     * SELECTED part's own content — see `./DocumentPreview.js`'s doc for why a generic `EditTarget`
+     * has no "whole document" verb this component could read on its own. A host built on the
+     * `html` region target (`../../html/regions.ts`) already holds the composed document as its own
+     * `HtmlDocumentStore` state and is the natural place to supply this.
+     */
+    readonly documentHtml?: string;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+}
+/**
+ * A ready-to-drop-in pane combining the file viewer, the live renderer, and undo/redo controls
+ * over one `session`.
+ *
+ * Selection is local UI state, not part of `VibecodingSession` — a session describes the artifact,
+ * not which part a particular viewer happens to have open, and a host rendering two workbenches
+ * over the same session (unlikely today, but not precluded) should not have them fight over one
+ * shared selection.
+ *
+ * @complexity O(parts.length) to render the viewer; content fetches are cached — see `../session.js`.
+ */
+export declare function VibecodingWorkbench({ session, documentHtml, className, style }: VibecodingWorkbenchProps): import("react").JSX.Element;
+//# sourceMappingURL=VibecodingWorkbench.d.ts.map

package/dist/react/components/VibecodingWorkbench.js

@@ -0,0 +1,96 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * @module react/components/VibecodingWorkbench
+ *
+ * The composed convenience component: owns a `VibecodingSession` (via `useVibecodingSession`) and
+ * wires it into `PartsViewer` (the file viewer) and `DocumentPreview` (the renderer) plus an
+ * undo/redo toolbar, the same "headless hook + presentational pieces + one drop-in pane" shape
+ * `@jini-ai/chat/react`'s `<ChatPane>` uses over its own headless primitives. A host that wants a
+ * different layout composes `PartsViewer`/`DocumentPreview`/`useVibecodingSession` directly instead
+ * — this component does not own anything those three don't already expose.
+ */
+import { useEffect, useState } from 'react';
+import { useVibecodingSession } from '../use-vibecoding-session.js';
+import { PartsViewer } from './PartsViewer.js';
+import { DocumentPreview } from './DocumentPreview.js';
+const ROOT_STYLE = {
+    display: 'flex',
+    flexDirection: 'column',
+    height: '100%',
+    minHeight: 0,
+    border: '1px solid #e2e5ea',
+    borderRadius: 8,
+    overflow: 'hidden',
+    background: '#fff',
+};
+const TOOLBAR_STYLE = {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 8,
+    padding: '6px 10px',
+    borderBottom: '1px solid #e2e5ea',
+    fontSize: 12,
+    fontFamily: 'ui-sans-serif, system-ui, sans-serif',
+    color: '#374151',
+};
+const BUTTON_STYLE = {
+    font: 'inherit',
+    border: '1px solid #d0d5dd',
+    background: '#fff',
+    borderRadius: 6,
+    padding: '3px 10px',
+    cursor: 'pointer',
+};
+const BUTTON_DISABLED_STYLE = { ...BUTTON_STYLE, opacity: 0.5, cursor: 'default' };
+const ERROR_STYLE = { color: '#b42318', marginLeft: 'auto' };
+const BODY_STYLE = { display: 'flex', flex: 1, minHeight: 0 };
+const PANE_STYLE = { flex: 1, minWidth: 0, minHeight: 0, borderRight: '1px solid #e2e5ea' };
+const PREVIEW_PANE_STYLE = { flex: 1, minWidth: 0, minHeight: 0 };
+/**
+ * A ready-to-drop-in pane combining the file viewer, the live renderer, and undo/redo controls
+ * over one `session`.
+ *
+ * Selection is local UI state, not part of `VibecodingSession` — a session describes the artifact,
+ * not which part a particular viewer happens to have open, and a host rendering two workbenches
+ * over the same session (unlikely today, but not precluded) should not have them fight over one
+ * shared selection.
+ *
+ * @complexity O(parts.length) to render the viewer; content fetches are cached — see `../session.js`.
+ */
+export function VibecodingWorkbench({ session, documentHtml, className, style }) {
+    const { parts, partContent, canUndo, canRedo, lastError, readPart, undo, redo } = useVibecodingSession({ session });
+    const [selectedId, setSelectedId] = useState(null);
+    const [selectedContent, setSelectedContent] = useState(undefined);
+    const [contentLoading, setContentLoading] = useState(false);
+    // Re-fetches on part-list or cache changes so a chat-driven edit or history replay to
+    // the currently open part shows up immediately: `readPart` resolves from `session`'s cache
+    // (already updated by `applyEdits`/`undo`/`redo` themselves — see `../session.js`), so this is a
+    // cache hit, not a host round trip, whenever the edit is what triggered the re-render.
+    useEffect(() => {
+        if (selectedId === null) {
+            setSelectedContent(undefined);
+            return;
+        }
+        let cancelled = false;
+        setContentLoading(true);
+        readPart({ id: selectedId })
+            .then((content) => {
+            if (!cancelled)
+                setSelectedContent(content);
+        })
+            .catch(() => {
+            // `lastError` on the session snapshot already surfaces this — see `useVibecodingSession`'s
+            // own doc for why a rejection here is not rethrown into an unhandled effect error.
+        })
+            .finally(() => {
+            if (!cancelled)
+                setContentLoading(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [selectedId, readPart, parts, partContent]);
+    const previewHtml = documentHtml ?? selectedContent ?? '';
+    return (_jsxs("div", { className: className, style: style ? { ...ROOT_STYLE, ...style } : ROOT_STYLE, children: [_jsxs("div", { style: TOOLBAR_STYLE, children: [_jsx("button", { type: "button", style: canUndo ? BUTTON_STYLE : BUTTON_DISABLED_STYLE, disabled: !canUndo, onClick: () => void undo(), children: "Undo" }), _jsx("button", { type: "button", style: canRedo ? BUTTON_STYLE : BUTTON_DISABLED_STYLE, disabled: !canRedo, onClick: () => void redo(), children: "Redo" }), lastError ? _jsx("span", { style: ERROR_STYLE, children: lastError }) : null] }), _jsxs("div", { style: BODY_STYLE, children: [_jsx("div", { style: PANE_STYLE, children: _jsx(PartsViewer, { parts: parts, selectedId: selectedId, onSelect: setSelectedId, ...(selectedContent !== undefined ? { content: selectedContent } : {}), contentLoading: contentLoading, style: { height: '100%' } }) }), _jsx("div", { style: PREVIEW_PANE_STYLE, children: _jsx(DocumentPreview, { html: previewHtml }) })] })] }));
+}
+//# sourceMappingURL=VibecodingWorkbench.js.map

package/dist/react/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @module react
+ *
+ * The chat + preview surface: a `VibecodingSession` (a subscribable wrapper over `../core`'s
+ * `EditTarget`/`EditHistory`), the `@jini-ai/core`-registrable tool set that drives it from chat,
+ * and the presentational React pieces — `PartsViewer` (file viewer), `DocumentPreview` (renderer),
+ * and `VibecodingWorkbench` (both, composed). See this package's README for the three-piece shape
+ * this entry point exists to fill in, and each exported module's own doc for its design rationale.
+ *
+ * React (and `react-dom`, transitively via these components) is an **optional peer dependency** —
+ * see this package's `package.json` — so importing `../core` or `../html` alone never pulls React
+ * in. Only a consumer of this `./react` subpath needs it installed.
+ */
+export type { VibecodingSession, VibecodingSessionOptions, VibecodingSessionSnapshot, ApplyEditsResult } from './session.js';
+export { createVibecodingSession } from './session.js';
+export type { VibecodingSessionArgs } from './session.js';
+export type { UseVibecodingSessionResult } from './use-vibecoding-session.js';
+export { useVibecodingSession } from './use-vibecoding-session.js';
+export type { UseVibecodingSessionArgs } from './use-vibecoding-session.js';
+export type { CreateVibecodingToolRegistrationsOptions, VibecodingToolRunner, } from './tools.js';
+export type { VibecodingToolArgs } from './tools.js';
+export { VIBECODING_TOOL_IDS, createVibecodingToolRegistrations, createVibecodingToolRunner, } from './tools.js';
+export type { PartsViewerProps } from './components/PartsViewer.js';
+export { PartsViewer } from './components/PartsViewer.js';
+export type { DocumentPreviewProps } from './components/DocumentPreview.js';
+export { DocumentPreview } from './components/DocumentPreview.js';
+export type { VibecodingWorkbenchProps } from './components/VibecodingWorkbench.js';
+export { VibecodingWorkbench } from './components/VibecodingWorkbench.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.js

@@ -0,0 +1,7 @@
+export { createVibecodingSession } from './session.js';
+export { useVibecodingSession } from './use-vibecoding-session.js';
+export { VIBECODING_TOOL_IDS, createVibecodingToolRegistrations, createVibecodingToolRunner, } from './tools.js';
+export { PartsViewer } from './components/PartsViewer.js';
+export { DocumentPreview } from './components/DocumentPreview.js';
+export { VibecodingWorkbench } from './components/VibecodingWorkbench.js';
+//# sourceMappingURL=index.js.map