@benz-ai-x/dsh-md-preview 0.2.7 → 0.4.0

package/lib/index.js

@@ -6,6 +6,12 @@ import z from "@deepseek-ai/schemastery";
 const DEFAULT_MAX_BYTES = 1048576;
 /** Markdown documents are the previewable vocabulary; deployments may widen it. */
 const DEFAULT_ALLOWED_EXTENSIONS = [".md", ".markdown"];
+/** The preview union: readable (and rendered) even though only markdown edits. */
+const DEFAULT_PREVIEW_EXTENSIONS = [
+	".md",
+	".markdown",
+	".txt"
+];
 //#endregion
 //#region src/remote.ts
 var __runInitializers = function(thisArg, initializers, value) {
@@ -64,6 +70,12 @@ function fsErrorCode(error) {
 		if (typeof code === "string") return code;
 	}
 }
+/** Workspace-relative form of an entry target, falling back to its name. */
+function workspaceRelative(rootPath, targetPath, name) {
+	if (targetPath === rootPath) return name;
+	const prefix = rootPath.endsWith("/") ? rootPath : `${rootPath}/`;
+	return targetPath.startsWith(prefix) ? targetPath.slice(prefix.length) : name;
+}
 /** Lowercased dot-prefixed extension of a path, or the empty string. */
 function extensionOf(path) {
 	const name = path.slice(Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\")) + 1);
@@ -83,11 +95,13 @@ let MdPreviewService = (() => {
 	let _instanceExtraInitializers = [];
 	let _read_decorators;
 	let _write_decorators;
+	let _list_decorators;
 	return class MdPreviewService extends _classSuper {
 		static {
 			const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
 			_read_decorators = [Remote];
 			_write_decorators = [Remote];
+			_list_decorators = [Remote];
 			__esDecorate(this, null, _read_decorators, {
 				kind: "method",
 				name: "read",
@@ -110,6 +124,17 @@ let MdPreviewService = (() => {
 				},
 				metadata: _metadata
 			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _list_decorators, {
+				kind: "method",
+				name: "list",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "list" in obj,
+					get: (obj) => obj.list
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
 			if (_metadata) Object.defineProperty(this, Symbol.metadata, {
 				enumerable: true,
 				configurable: true,
@@ -146,7 +171,7 @@ let MdPreviewService = (() => {
 		* @throws RemoteError with a stable MdPreview failure code.
 		*/
 		async read(sessionId, path, signal) {
-			const { target, info } = await this.resolveWorkspaceTarget(sessionId, path, signal, "read");
+			const { target, info } = await this.resolveWorkspaceTarget(sessionId, path, signal, "read", [...this.config.allowedExtensions, ...this.config.previewExtensions]);
 			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 {
@@ -175,7 +200,7 @@ let MdPreviewService = (() => {
 		* @throws RemoteError with a stable MdPreview failure code.
 		*/
 		async write(sessionId, path, content, fingerprint, force, signal) {
-			const { target, cwd } = await this.resolveWorkspaceTarget(sessionId, path, signal, "write");
+			const { target, cwd } = await this.resolveWorkspaceTarget(sessionId, path, signal, "write", this.config.allowedExtensions);
 			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 : {
@@ -204,6 +229,39 @@ let MdPreviewService = (() => {
 			};
 		}
 		/**
+		* List one workspace directory for the browser face; folders sort first,
+		* then entries alphabetize by name. A blank path lists the workspace root.
+		* @param sessionId - owning session; its header cwd roots the listing.
+		* @param path - directory path as the tree spelled it; blank = root.
+		* @param signal - caller cancellation carried through every fs call.
+		* @returns the requested path with its workspace-relative entries.
+		* @throws RemoteError with a stable MdPreview failure code.
+		*/
+		async list(sessionId, path, signal) {
+			const { root, target } = await this.resolveContainedTarget(sessionId, path, signal, "list");
+			const info = await this.ctx.fs.stat(target, signal);
+			if (info === void 0) throw failure("md-preview/not-found", `mdPreview/list cannot find "${path}"`);
+			if (info.type !== "directory") throw failure("md-preview/bad-request", `mdPreview/list requires a directory path, not "${path}"`);
+			let raw;
+			try {
+				raw = await this.ctx.fs.listDir(target, signal);
+			} catch (error) {
+				if (signal.aborted) throw error;
+				throw failure("md-preview/unavailable", `mdPreview/list failed to list "${path}": ${error instanceof Error ? error.message : String(error)}`);
+			}
+			const rootPath = root.displayPath;
+			const entries = raw.map((entry) => ({
+				name: entry.name,
+				type: entry.type,
+				path: workspaceRelative(rootPath, entry.target.displayPath, entry.name)
+			}));
+			entries.sort((a, b) => a.type === b.type || a.type !== "directory" && b.type !== "directory" ? a.name.localeCompare(b.name) : a.type === "directory" ? -1 : 1);
+			return {
+				path: path.trim().length === 0 ? "" : path,
+				entries
+			};
+		}
+		/**
 		* 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
@@ -215,16 +273,38 @@ let MdPreviewService = (() => {
 		* @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) {
+		async resolveWorkspaceTarget(sessionId, path, signal, op, extensions) {
 			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}"`);
+			if (!isAllowedExtension(path, extensions)) throw failure("md-preview/unsupported-extension", `mdPreview/${op} refuses non-previewable path "${path}"`);
+			const contained = await this.resolveContainedTarget(sessionId, path, signal, op);
+			const info = await this.ctx.fs.stat(contained.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 {
+				...contained,
+				info
+			};
+		}
+		/**
+		* The authority middle shared by every method: session → workspace cwd →
+		* root resolve → target resolve (a blank path means the root itself) →
+		* containment. Extension and type checks belong to the callers.
+		* @param sessionId - owning session; its header cwd roots the resolution.
+		* @param path - requested path; blank spells the workspace root.
+		* @param signal - caller cancellation carried through every fs call.
+		* @param op - calling method name for diagnostic messages.
+		* @returns the resolved root, target, and the workspace cwd.
+		* @throws RemoteError with a stable MdPreview failure code.
+		*/
+		async resolveContainedTarget(sessionId, path, signal, op) {
 			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 {
+			if (path.trim().length === 0) target = root;
+			else try {
 				target = await this.ctx.fs.resolve(path, {
 					cwd,
 					signal
@@ -234,12 +314,9 @@ let MdPreviewService = (() => {
 				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 {
+				root,
 				target,
-				info,
 				cwd
 			};
 		}
@@ -251,7 +328,8 @@ let MdPreviewService = (() => {
 /** Standard Schema twin of {@link Config}; defaults live here, not in code. */
 const Config = z.object({
 	maxBytes: z.number().min(1).default(DEFAULT_MAX_BYTES),
-	allowedExtensions: z.array(z.string()).default([...DEFAULT_ALLOWED_EXTENSIONS])
+	allowedExtensions: z.array(z.string()).default([...DEFAULT_ALLOWED_EXTENSIONS]),
+	previewExtensions: z.array(z.string()).default([...DEFAULT_PREVIEW_EXTENSIONS])
 });
 //#endregion
 //#region src/protocol.ts
@@ -284,11 +362,12 @@ const inject = [
 */
 function apply(ctx, config = {
 	maxBytes: DEFAULT_MAX_BYTES,
-	allowedExtensions: [...DEFAULT_ALLOWED_EXTENSIONS]
+	allowedExtensions: [...DEFAULT_ALLOWED_EXTENSIONS],
+	previewExtensions: [...DEFAULT_PREVIEW_EXTENSIONS]
 }) {
 	ctx.plugin(MdPreviewService, config);
 }
 //#endregion
-export { Config, DEFAULT_ALLOWED_EXTENSIONS, DEFAULT_MAX_BYTES, MD_PREVIEW_FAILURE_CODES, MdPreviewService, apply, inject, isAllowedExtension, name };
+export { Config, DEFAULT_ALLOWED_EXTENSIONS, DEFAULT_MAX_BYTES, DEFAULT_PREVIEW_EXTENSIONS, MD_PREVIEW_FAILURE_CODES, MdPreviewService, apply, inject, isAllowedExtension, name };
 
 //# sourceMappingURL=index.js.map

package/lib/typert/remote-client.js

@@ -24,48 +24,31 @@ const writeResult$schema = z.object({
 	path: z.string(),
 	fingerprint: z.string()
 });
+const listPath$schema = z.string();
+const listEntry$schema = z.object({
+	name: z.string(),
+	type: z.enum([
+		"file",
+		"directory",
+		"other"
+	]),
+	path: z.string()
+});
+const listResult$schema = z.object({
+	path: z.string(),
+	entries: z.array(listEntry$schema)
+});
 /** The MdPreview contribution mounted by this package's browser entry. */
 const TYPERT_REMOTE = {
 	package: "@benz-ai-x/dsh-md-preview",
-	descriptors: [{
-		id: "@benz-ai-x/dsh-md-preview#mdPreview/read",
-		service: "mdPreview",
-		namespace: "mdPreview",
-		method: "read",
-		invocation: { kind: "direct" },
-		parameters: [{
-			name: "sessionId",
-			wire: "sessionId",
-			source: "json",
-			codec: {
-				mode: "strict",
-				typeSymbol: "@deepseek-ai/dsh-session/types#SessionId",
-				schema: readSessionId$schema
-			}
-		}, {
-			name: "path",
-			wire: "path",
-			source: "json",
-			codec: {
-				mode: "strict",
-				typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/read:path",
-				schema: readPath$schema
-			}
-		}],
-		cancellation: { parameter: "signal" },
-		result: {
-			mode: "strict",
-			typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/read:result",
-			schema: readResult$schema
-		}
-	}, {
-		id: "@benz-ai-x/dsh-md-preview#mdPreview/write",
-		service: "mdPreview",
-		namespace: "mdPreview",
-		method: "write",
-		invocation: { kind: "direct" },
-		parameters: [
-			{
+	descriptors: [
+		{
+			id: "@benz-ai-x/dsh-md-preview#mdPreview/read",
+			service: "mdPreview",
+			namespace: "mdPreview",
+			method: "read",
+			invocation: { kind: "direct" },
+			parameters: [{
 				name: "sessionId",
 				wire: "sessionId",
 				source: "json",
@@ -74,55 +57,121 @@ const TYPERT_REMOTE = {
 					typeSymbol: "@deepseek-ai/dsh-session/types#SessionId",
 					schema: readSessionId$schema
 				}
-			},
-			{
+			}, {
 				name: "path",
 				wire: "path",
 				source: "json",
 				codec: {
 					mode: "strict",
-					typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/write:path",
+					typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/read:path",
 					schema: readPath$schema
 				}
-			},
-			{
-				name: "content",
-				wire: "content",
-				source: "json",
-				codec: {
-					mode: "strict",
-					typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/write:content",
-					schema: writeContent$schema
+			}],
+			cancellation: { parameter: "signal" },
+			result: {
+				mode: "strict",
+				typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/read:result",
+				schema: readResult$schema
+			}
+		},
+		{
+			id: "@benz-ai-x/dsh-md-preview#mdPreview/write",
+			service: "mdPreview",
+			namespace: "mdPreview",
+			method: "write",
+			invocation: { kind: "direct" },
+			parameters: [
+				{
+					name: "sessionId",
+					wire: "sessionId",
+					source: "json",
+					codec: {
+						mode: "strict",
+						typeSymbol: "@deepseek-ai/dsh-session/types#SessionId",
+						schema: readSessionId$schema
+					}
+				},
+				{
+					name: "path",
+					wire: "path",
+					source: "json",
+					codec: {
+						mode: "strict",
+						typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/write:path",
+						schema: readPath$schema
+					}
+				},
+				{
+					name: "content",
+					wire: "content",
+					source: "json",
+					codec: {
+						mode: "strict",
+						typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/write:content",
+						schema: writeContent$schema
+					}
+				},
+				{
+					name: "fingerprint",
+					wire: "fingerprint",
+					source: "json",
+					codec: {
+						mode: "strict",
+						typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/write:fingerprint",
+						schema: writeFingerprint$schema
+					}
+				},
+				{
+					name: "force",
+					wire: "force",
+					source: "json",
+					codec: {
+						mode: "strict",
+						typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/write:force",
+						schema: writeForce$schema
+					}
 				}
-			},
-			{
-				name: "fingerprint",
-				wire: "fingerprint",
+			],
+			cancellation: { parameter: "signal" },
+			result: {
+				mode: "strict",
+				typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/write:result",
+				schema: writeResult$schema
+			}
+		},
+		{
+			id: "@benz-ai-x/dsh-md-preview#mdPreview/list",
+			service: "mdPreview",
+			namespace: "mdPreview",
+			method: "list",
+			invocation: { kind: "direct" },
+			parameters: [{
+				name: "sessionId",
+				wire: "sessionId",
 				source: "json",
 				codec: {
 					mode: "strict",
-					typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/write:fingerprint",
-					schema: writeFingerprint$schema
+					typeSymbol: "@deepseek-ai/dsh-session/types#SessionId",
+					schema: readSessionId$schema
 				}
-			},
-			{
-				name: "force",
-				wire: "force",
+			}, {
+				name: "path",
+				wire: "path",
 				source: "json",
 				codec: {
 					mode: "strict",
-					typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/write:force",
-					schema: writeForce$schema
+					typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/list:path",
+					schema: listPath$schema
 				}
+			}],
+			cancellation: { parameter: "signal" },
+			result: {
+				mode: "strict",
+				typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/list:result",
+				schema: listResult$schema
 			}
-		],
-		cancellation: { parameter: "signal" },
-		result: {
-			mode: "strict",
-			typeSymbol: "@benz-ai-x/dsh-md-preview#mdPreview/write:result",
-			schema: writeResult$schema
 		}
-	}]
+	]
 };
 //#endregion
 export { TYPERT_REMOTE, TYPERT_REMOTE as default };

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

@@ -1,10 +1,9 @@
 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';
-/** Read/write RPCs and panel dismissal, created in the plugin's apply world. */
+import type { MdPreviewFile, MdPreviewListResult, MdPreviewWriteResult } from '../protocol.ts';
+import type { MdPreviewState, MdPreviewTarget } from './preview-state.ts';
+/** Read/write/list RPCs and panel dismissal, created in the plugin's apply world. */
 export interface PreviewOverlayInjected {
     hooks: {
         /** Current preview target; null while the panel is closed. */
@@ -12,17 +11,21 @@ export interface PreviewOverlayInjected {
     };
     /** Dismiss the panel and drop the target. */
     close(): void;
+    /** Set the preview target (the browser face's file-open handoff). */
+    setTarget(target: MdPreviewTarget | null): 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>>;
+    /** One workspace directory listing; blank path lists the root. */
+    list(sessionId: SessionId, path: string, signal: AbortSignal): Promise<import('@deepseek-ai/dsh-typert-protocol').RemoteResult<MdPreviewListResult>>;
 }
 /** 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;
+export declare function PreviewOverlay({ usePreviewTarget, close, setTarget, read, write, list, t }: PreviewOverlayProps): import("react").JSX.Element | null;
 //# sourceMappingURL=PreviewOverlay.d.ts.map

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

@@ -0,0 +1,23 @@
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { MdPreviewListResult } from '../protocol.ts';
+/** Listing RPC and the file-open handoff, created in the plugin's apply world. */
+export interface WorkspaceBrowserProps {
+    /** Owning session whose workspace the tree roots at. */
+    sessionId: SessionId;
+    /** One directory listing; the transport carries the AbortSignal. */
+    list(sessionId: SessionId, path: string, signal: AbortSignal): Promise<RemoteResult<MdPreviewListResult>>;
+    /** Open one file as the panel's preview target. */
+    onOpenFile(path: string): void;
+    /** Workspace-relative path of the current preview target, if any. */
+    currentPath: string | null;
+    /** Locale seat. */
+    t(key: string): string;
+}
+/**
+ * Render the workspace tree for one session.
+ * @param props - session identity, listing RPC, file-open handoff, locale seat.
+ * @returns the tree element.
+ */
+export declare function WorkspaceBrowser({ sessionId, list, onOpenFile, currentPath, t }: WorkspaceBrowserProps): import("react").JSX.Element;
+//# sourceMappingURL=WorkspaceBrowser.d.ts.map

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

@@ -8,6 +8,7 @@ export declare const zh: {
     'panel.loading': string;
     'panel.empty': string;
     'panel.error': string;
+    'panel.unsupported': string;
     'panel.retry': string;
     'panel.edit': string;
     'panel.save': string;
@@ -21,6 +22,12 @@ export declare const zh: {
     'panel.unsaved.title': string;
     'panel.unsaved.discard': string;
     'panel.unsaved.keep': string;
+    'browse.open': string;
+    'browse.back': string;
+    'browse.loading': string;
+    'browse.empty': string;
+    'browse.error': string;
+    'browse.retry': string;
     'chip.preview': string;
     'chip.open': string;
     'action.label': string;

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/preview-state.d.ts

@@ -13,6 +13,8 @@ export declare function createPreviewStore(): import("@deepseek-ai/dsh-client-st
 export declare function basename(path: string): string;
 /** Whether the client treats a produced path as a previewable markdown document. */
 export declare function isPreviewable(path: string): boolean;
+/** Whether a path may enter an edit session (the markdown-only editable set). */
+export declare function isEditable(path: string): boolean;
 /** Produced paths of one turn split into previewable and externally-opened groups, first-seen order preserved. */
 export declare function splitPreviewable(paths: readonly string[]): {
     previewable: string[];

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/config.d.ts

@@ -4,8 +4,11 @@ import z from '@deepseek-ai/schemastery';
 export interface Config {
     /** Largest file size the service will read and return, in bytes. */
     maxBytes: number;
-    /** Extensions (lowercased, dot-prefixed) eligible for preview. */
+    /** Extensions (lowercased, dot-prefixed) eligible for editing. */
     allowedExtensions: string[];
+    /** Extensions (lowercased, dot-prefixed) eligible for preview (a superset
+     * of the editable set — plain-text members render but never edit). */
+    previewExtensions: string[];
 }
 /** Standard Schema twin of {@link Config}; defaults live here, not in code. */
 export declare const Config: z<Config>;

package/lib/types/constants.d.ts

@@ -3,4 +3,6 @@
 export declare const DEFAULT_MAX_BYTES = 1048576;
 /** Markdown documents are the previewable vocabulary; deployments may widen it. */
 export declare const DEFAULT_ALLOWED_EXTENSIONS: readonly [".md", ".markdown"];
+/** The preview union: readable (and rendered) even though only markdown edits. */
+export declare const DEFAULT_PREVIEW_EXTENSIONS: readonly [".md", ".markdown", ".txt"];
 //# sourceMappingURL=constants.d.ts.map