@benz-ai-x/dsh-md-preview 0.2.6 → 0.3.0

package/lib/index.js

@@ -146,24 +146,7 @@ let MdPreviewService = (() => {
 		* @throws RemoteError with a stable MdPreview failure code.
 		*/
 		async read(sessionId, path, signal) {
-			if (path.trim().length === 0) throw failure("md-preview/bad-request", "mdPreview/read requires a non-empty path");
-			if (!isAllowedExtension(path, this.config.allowedExtensions)) throw failure("md-preview/unsupported-extension", `mdPreview/read refuses non-previewable path "${path}"`);
-			const session = this.ctx.sessions.get(sessionId);
-			if (session === void 0) throw failure("md-preview/unknown-session", `mdPreview/read cannot resolve session "${sessionId}"`);
-			const cwd = session.header.cwd;
-			if (cwd === void 0) throw failure("md-preview/no-workspace", `mdPreview/read session "${sessionId}" has no working directory`);
-			const root = await this.resolveWorkspacePath(cwd, signal);
-			let target;
-			try {
-				target = await this.resolveWorkspacePath(path, signal, cwd);
-			} catch (error) {
-				if (signal.aborted) throw error;
-				throw failure("md-preview/not-found", `mdPreview/read cannot resolve path "${path}"`);
-			}
-			if (!this.ctx.fs.contains(root, target)) throw failure("md-preview/forbidden", "mdPreview/read refuses paths outside the session workspace");
-			const info = await this.ctx.fs.stat(target, signal);
-			if (info === void 0) throw failure("md-preview/not-found", `mdPreview/read cannot find "${path}"`);
-			if (info.type !== "file") throw failure("md-preview/unsupported-extension", `mdPreview/read target "${path}" is not a regular file`);
+			const { target, info } = await this.resolveWorkspaceTarget(sessionId, path, signal, "read");
 			if (info.size !== void 0 && info.size > this.config.maxBytes) throw failure("md-preview/too-large", `mdPreview/read refuses "${path}" above the configured byte cap`);
 			let content;
 			try {
@@ -192,24 +175,7 @@ let MdPreviewService = (() => {
 		* @throws RemoteError with a stable MdPreview failure code.
 		*/
 		async write(sessionId, path, content, fingerprint, force, signal) {
-			if (path.trim().length === 0) throw failure("md-preview/bad-request", "mdPreview/write requires a non-empty path");
-			if (!isAllowedExtension(path, this.config.allowedExtensions)) throw failure("md-preview/unsupported-extension", `mdPreview/write refuses non-previewable path "${path}"`);
-			const session = this.ctx.sessions.get(sessionId);
-			if (session === void 0) throw failure("md-preview/unknown-session", `mdPreview/write cannot resolve session "${sessionId}"`);
-			const cwd = session.header.cwd;
-			if (cwd === void 0) throw failure("md-preview/no-workspace", `mdPreview/write session "${sessionId}" has no working directory`);
-			const root = await this.resolveWorkspacePath(cwd, signal);
-			let target;
-			try {
-				target = await this.resolveWorkspacePath(path, signal, cwd);
-			} catch (error) {
-				if (signal.aborted) throw error;
-				throw failure("md-preview/not-found", `mdPreview/write cannot resolve path "${path}"`);
-			}
-			if (!this.ctx.fs.contains(root, target)) throw failure("md-preview/forbidden", "mdPreview/write refuses paths outside the session workspace");
-			const info = await this.ctx.fs.stat(target, signal);
-			if (info === void 0) throw failure("md-preview/not-found", `mdPreview/write cannot find "${path}"`);
-			if (info.type !== "file") throw failure("md-preview/unsupported-extension", `mdPreview/write target "${path}" is not a regular file`);
+			const { target, cwd } = await this.resolveWorkspaceTarget(sessionId, path, signal, "write");
 			if (content.length > this.config.maxBytes) throw failure("md-preview/too-large", `mdPreview/write refuses "${path}" above the configured byte cap`);
 			if (fingerprint === void 0 && !force) throw failure("md-preview/bad-request", "mdPreview/write requires a fingerprint or force");
 			const expected = fingerprint === void 0 ? void 0 : {
@@ -237,12 +203,45 @@ let MdPreviewService = (() => {
 				fingerprint: outcome.version
 			};
 		}
-		/** Resolve one path against the workspace, with a plain not-found mapping. */
-		async resolveWorkspacePath(path, signal, cwd) {
-			return await this.ctx.fs.resolve(path, cwd === void 0 ? { signal } : {
-				cwd,
-				signal
-			});
+		/**
+		* The shared authority preamble of the remote methods: resolve a path to a
+		* live, contained, regular workspace file, or reject it with the stable
+		* failure code. One home for the check order and the aborted-rethrow
+		* convention; `op` only names the calling method in diagnostics.
+		* @param sessionId - owning session; its header cwd roots the resolution.
+		* @param path - path as it appeared in the conversation.
+		* @param signal - caller cancellation carried through every fs call.
+		* @param op - calling method name for diagnostic messages.
+		* @returns the resolved target, its stat info, and the workspace cwd.
+		* @throws RemoteError with a stable MdPreview failure code.
+		*/
+		async resolveWorkspaceTarget(sessionId, path, signal, op) {
+			if (path.trim().length === 0) throw failure("md-preview/bad-request", `mdPreview/${op} requires a non-empty path`);
+			if (!isAllowedExtension(path, this.config.allowedExtensions)) throw failure("md-preview/unsupported-extension", `mdPreview/${op} refuses non-previewable path "${path}"`);
+			const session = this.ctx.sessions.get(sessionId);
+			if (session === void 0) throw failure("md-preview/unknown-session", `mdPreview/${op} cannot resolve session "${sessionId}"`);
+			const cwd = session.header.cwd;
+			if (cwd === void 0) throw failure("md-preview/no-workspace", `mdPreview/${op} session "${sessionId}" has no working directory`);
+			const root = await this.ctx.fs.resolve(cwd, { signal });
+			let target;
+			try {
+				target = await this.ctx.fs.resolve(path, {
+					cwd,
+					signal
+				});
+			} catch (error) {
+				if (signal.aborted) throw error;
+				throw failure("md-preview/not-found", `mdPreview/${op} cannot resolve path "${path}"`);
+			}
+			if (!this.ctx.fs.contains(root, target)) throw failure("md-preview/forbidden", `mdPreview/${op} refuses paths outside the session workspace`);
+			const info = await this.ctx.fs.stat(target, signal);
+			if (info === void 0) throw failure("md-preview/not-found", `mdPreview/${op} cannot find "${path}"`);
+			if (info.type !== "file") throw failure("md-preview/unsupported-extension", `mdPreview/${op} target "${path}" is not a regular file`);
+			return {
+				target,
+				info,
+				cwd
+			};
 		}
 	};
 })();

package/lib/types/client/PreviewOverlay.d.ts

@@ -1,6 +1,5 @@
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
 import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
-import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
 import type { SessionId } from '@deepseek-ai/dsh-session/types';
 import type { MdPreviewFile, MdPreviewWriteResult } from '../protocol.ts';
 import type { MdPreviewState } from './preview-state.ts';
@@ -13,15 +12,15 @@ export interface PreviewOverlayInjected {
     /** Dismiss the panel and drop the target. */
     close(): void;
     /** One bounded read; the transport carries the AbortSignal. */
-    read(sessionId: SessionId, path: string, signal: AbortSignal): Promise<RemoteResult<MdPreviewFile>>;
+    read(sessionId: SessionId, path: string, signal: AbortSignal): Promise<import('@deepseek-ai/dsh-typert-protocol').RemoteResult<MdPreviewFile>>;
     /** One guarded write; `fingerprint` comes from the backing read. */
-    write(sessionId: SessionId, path: string, content: string, fingerprint: string | undefined, force: boolean, signal: AbortSignal): Promise<RemoteResult<MdPreviewWriteResult>>;
+    write(sessionId: SessionId, path: string, content: string, fingerprint: string | undefined, force: boolean, signal: AbortSignal): Promise<import('@deepseek-ai/dsh-typert-protocol').RemoteResult<MdPreviewWriteResult>>;
 }
 /** Full composed panel props. */
 export type PreviewOverlayProps = PropsRuntime<'shell.overlay'> & InjectFace<PreviewOverlayInjected> & PropsLocale<'md-preview'>;
 /**
  * Render the preview panel for the current target.
- * @param props - target hook, read RPC, dismissal, and the locale seat.
+ * @param props - target hook, read/write RPCs, dismissal, and the locale seat.
  * @returns the docked panel, or null while closed.
  */
 export declare function PreviewOverlay({ usePreviewTarget, close, read, write, t }: PreviewOverlayProps): import("react").JSX.Element | null;

package/lib/types/client/preview-session.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The PreviewSession machine: the pure state algebra of one preview target's
+ * lifecycle — content read, edit session, guarded save, prompts. The React
+ * adapter lives beside the panel (use-preview-session.ts); effects and RPC
+ * never enter here. `READ_STARTED` is the single reset point: a new read
+ * begins only when the previous document's whole session is over.
+ */
+import type { MdPreviewFile, MdPreviewWriteResult } from '../protocol.ts';
+/** Content lifecycle of one preview target. */
+export type PreviewSessionContent = {
+    readonly state: 'loading';
+} | {
+    readonly state: 'ready';
+    readonly file: MdPreviewFile;
+} | {
+    readonly state: 'failed';
+    readonly code: string;
+    readonly message: string;
+};
+/** Whole machine state for the panel's current preview target. */
+export interface PreviewSessionState {
+    /** Read lifecycle of the current target. */
+    readonly content: PreviewSessionContent;
+    /** Panel face: rendering the document or editing a draft of it. */
+    readonly face: 'view' | 'edit';
+    /** The edit session's draft; meaningful only while `face` is edit. */
+    readonly draft: string;
+    /** A save is in flight. */
+    readonly saving: boolean;
+    /** The last save met a changed file; the conflict bar is up. */
+    readonly conflicted: boolean;
+    /** The last save failed for a non-conflict reason; the error bar is up. */
+    readonly saveError: {
+        readonly code: string;
+        readonly message: string;
+    } | null;
+    /** The unsaved guard is asking before a close. */
+    readonly unsavedPrompt: boolean;
+    /** The saved toast is showing. */
+    readonly toast: boolean;
+    /** The session asked the shell to close the panel; the adapter acts once. */
+    readonly closeRequested: boolean;
+}
+/** One machine transition. */
+export type PreviewSessionAction = {
+    readonly type: 'READ_STARTED';
+} | {
+    readonly type: 'RETRY_READ';
+} | {
+    readonly type: 'READ_RESOLVED';
+    readonly file: MdPreviewFile;
+} | {
+    readonly type: 'READ_FAILED';
+    readonly code: string;
+    readonly message: string;
+} | {
+    readonly type: 'ENTER_EDIT';
+} | {
+    readonly type: 'EDIT';
+    readonly draft: string;
+} | {
+    readonly type: 'SAVE_STARTED';
+} | {
+    readonly type: 'SAVE_RESOLVED';
+    readonly result: MdPreviewWriteResult;
+} | {
+    readonly type: 'SAVE_CONFLICT';
+} | {
+    readonly type: 'SAVE_FAILED';
+    readonly code: string;
+    readonly message: string;
+} | {
+    readonly type: 'CANCEL_EDIT';
+} | {
+    readonly type: 'REQUEST_CLOSE';
+} | {
+    readonly type: 'DISCARD';
+} | {
+    readonly type: 'KEEP_EDITING';
+} | {
+    readonly type: 'TOAST_EXPIRED';
+};
+/** The pristine state every session starts (and resets) from. */
+export declare function initialPreviewSession(): PreviewSessionState;
+/** Whether the draft differs from the loaded document. */
+export declare function isDirty(state: PreviewSessionState): boolean;
+/** The save-enable policy: something to save (dirty or conflicted), no save in flight. */
+export declare function canSave(state: PreviewSessionState): boolean;
+/**
+ * Apply one transition.
+ * @param state - current machine state.
+ * @param action - the transition.
+ * @returns the next state (transitions are total; guards decline no-ops).
+ */
+export declare function transition(state: PreviewSessionState, action: PreviewSessionAction): PreviewSessionState;
+//# sourceMappingURL=preview-session.d.ts.map

package/lib/types/client/use-preview-session.d.ts

@@ -0,0 +1,36 @@
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { MdPreviewFile, MdPreviewWriteResult } from '../protocol.ts';
+import type { MdPreviewTarget } from './preview-state.ts';
+import { initialPreviewSession } from './preview-session.ts';
+/** The adapter's inputs: the RPCs and dismissal from the plugin's apply world. */
+export interface PanelDocumentSessionDeps {
+    readonly read: (sessionId: SessionId, path: string, signal: AbortSignal) => Promise<RemoteResult<MdPreviewFile>>;
+    readonly write: (sessionId: SessionId, path: string, content: string, fingerprint: string | undefined, force: boolean, signal: AbortSignal) => Promise<RemoteResult<MdPreviewWriteResult>>;
+    readonly close: () => void;
+}
+/** The panel-facing surface: machine state plus intent actions. */
+export interface PanelDocumentSession {
+    readonly state: ReturnType<typeof initialPreviewSession>;
+    readonly canSave: boolean;
+    readonly dirty: boolean;
+    readonly actions: {
+        enterEdit(): void;
+        edit(draft: string): void;
+        save(force: boolean): void;
+        cancelEdit(): void;
+        reload(): void;
+        retryRead(): void;
+        requestClose(): void;
+        discard(): void;
+        keepEditing(): void;
+    };
+}
+/**
+ * Run one PreviewSession for the current preview target.
+ * @param deps - read/write RPCs and the panel dismissal.
+ * @param target - the current preview target; null while the panel is closed.
+ * @returns machine state with derived flags and intent actions.
+ */
+export declare function usePanelDocumentSession(deps: PanelDocumentSessionDeps, target: MdPreviewTarget | null): PanelDocumentSession;
+//# sourceMappingURL=use-preview-session.d.ts.map

package/lib/types/remote.d.ts

@@ -50,7 +50,18 @@ export declare class MdPreviewService extends TypertRemoteService {
      * @throws RemoteError with a stable MdPreview failure code.
      */
     write(sessionId: SessionId, path: string, content: string, fingerprint: string | undefined, force: boolean, signal: AbortSignal): Promise<MdPreviewWriteResult>;
-    /** Resolve one path against the workspace, with a plain not-found mapping. */
-    private resolveWorkspacePath;
+    /**
+     * The shared authority preamble of the remote methods: resolve a path to a
+     * live, contained, regular workspace file, or reject it with the stable
+     * failure code. One home for the check order and the aborted-rethrow
+     * convention; `op` only names the calling method in diagnostics.
+     * @param sessionId - owning session; its header cwd roots the resolution.
+     * @param path - path as it appeared in the conversation.
+     * @param signal - caller cancellation carried through every fs call.
+     * @param op - calling method name for diagnostic messages.
+     * @returns the resolved target, its stat info, and the workspace cwd.
+     * @throws RemoteError with a stable MdPreview failure code.
+     */
+    private resolveWorkspaceTarget;
 }
 //# sourceMappingURL=remote.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benz-ai-x/dsh-md-preview",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "DSH markdown preview: clicking a markdown document in the conversation opens a rendered preview panel docked to the right of the chat.",
   "license": "MIT",
   "repository": {