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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benz-ai-x/dsh-md-preview",
-  "version": "0.2.7",
+  "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": {