@bendyline/docblocks 0.1.0 → 1.1.0

package/dist/index-TtDaQ3vS.d.ts

@@ -0,0 +1,213 @@
+/**
+ * FileSystemProvider — abstract interface for a virtual filesystem.
+ *
+ * Implementations back onto IndexedDB (for browser-local storage) or
+ * the File System Access API (for native folder access).
+ */
+interface FileEntry {
+    kind: 'file';
+    name: string;
+    path: string;
+}
+interface FolderEntry {
+    kind: 'directory';
+    name: string;
+    path: string;
+}
+type FileSystemEntry = FileEntry | FolderEntry;
+interface FileMeta {
+    name: string;
+    path: string;
+    size: number;
+    lastModified: string;
+}
+interface FileSystemProvider {
+    /** Unique identifier for this provider instance. */
+    readonly id: string;
+    /** Human-readable label (e.g., folder name or "Browser Storage"). */
+    readonly label: string;
+    /** Read the text content of a file. Returns null if the file doesn't exist. */
+    readFile(path: string): Promise<string | null>;
+    /** Write text content to a file, creating it (and parent dirs) if needed. */
+    writeFile(path: string, content: string): Promise<void>;
+    /** Delete a file or empty directory. */
+    delete(path: string): Promise<void>;
+    /** Rename or move an entry. */
+    rename(oldPath: string, newPath: string): Promise<void>;
+    /** List immediate children of a directory. */
+    readDirectory(path: string): Promise<FileSystemEntry[]>;
+    /** Check whether a path exists. */
+    exists(path: string): Promise<boolean>;
+    /** Create a directory (and parents if needed). */
+    createDirectory(path: string): Promise<void>;
+    /** Get metadata for a file. Returns null if not found. */
+    stat(path: string): Promise<FileMeta | null>;
+    /** Read raw binary content. Returns null if not found. */
+    readBinary(path: string): Promise<ArrayBuffer | null>;
+    /** Write raw binary content. */
+    writeBinary(path: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+}
+
+/**
+ * DocblocksHostAPI — the contract exposed by the Electron desktop shell
+ * to its renderer process via contextBridge.
+ *
+ * This file is the single source of truth for the host ↔ renderer
+ * bridge. The Electron preload script exposes an implementation matching
+ * this shape; the React renderer calls it through `window.docblocksHost`.
+ */
+
+/** Filesystem operations scoped to a registered absolute root path. */
+interface DocblocksHostFsAPI {
+    readFile(rootPath: string, path: string): Promise<string | null>;
+    writeFile(rootPath: string, path: string, content: string): Promise<void>;
+    delete(rootPath: string, path: string): Promise<void>;
+    rename(rootPath: string, oldPath: string, newPath: string): Promise<void>;
+    readDirectory(rootPath: string, path: string): Promise<FileSystemEntry[]>;
+    exists(rootPath: string, path: string): Promise<boolean>;
+    createDirectory(rootPath: string, path: string): Promise<void>;
+    stat(rootPath: string, path: string): Promise<FileMeta | null>;
+    readBinary(rootPath: string, path: string): Promise<ArrayBuffer | null>;
+    writeBinary(rootPath: string, path: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+    /**
+     * Subscribe to change notifications for a watched root. Returns an
+     * unsubscribe function. The main process uses chokidar under the hood.
+     */
+    watch(rootPath: string, onChange: (path: string) => void): () => void;
+}
+/** Descriptor returned for an Electron-managed workspace (backed by a folder). */
+interface ElectronWorkspaceInfo {
+    id: string;
+    name: string;
+    rootPath: string;
+}
+/** Workspace-management operations exposed to the renderer. */
+interface DocblocksHostWorkspacesAPI {
+    /**
+     * Return the default workspace (creating ~/Documents/DocBlocks on first
+     * call, or the user's configured default).
+     */
+    getDefault(): Promise<ElectronWorkspaceInfo>;
+    /**
+     * Open the native folder picker. Returns null if the user cancels.
+     * The selected folder is registered in the main process whitelist.
+     */
+    pickFolder(): Promise<ElectronWorkspaceInfo | null>;
+    /**
+     * Re-register a previously known workspace so its rootPath is trusted
+     * for subsequent fs calls. Called on app startup for persisted
+     * electron-native workspaces before any fs operation.
+     */
+    register(info: ElectronWorkspaceInfo): Promise<void>;
+    /** Remove a workspace from the trusted whitelist. */
+    unregister(id: string): Promise<void>;
+}
+/** Shell operations — reveal in Finder/Explorer, open external URLs. */
+interface DocblocksHostShellAPI {
+    /** Reveal a file (by absolute path) in the OS file manager. */
+    revealInFolder(absolutePath: string): Promise<void>;
+    /** Open a URL in the default browser. */
+    openExternal(url: string): Promise<void>;
+}
+/** System ffmpeg detection and invocation. */
+interface DocblocksHostFfmpegAPI {
+    /** True if `ffmpeg` is available on PATH (or bundled). */
+    available(): Promise<boolean>;
+    /** Version string from `ffmpeg -version`, or null if unavailable. */
+    version(): Promise<string | null>;
+    /**
+     * Render a markdown file at the given absolute path to MP4 using the
+     * existing squisq-video CLI pipeline. Returns the absolute path to the
+     * produced MP4 file, or throws on failure.
+     */
+    renderVideo(markdownAbsolutePath: string, options: {
+        fps?: number;
+        quality?: 'draft' | 'normal' | 'high';
+    }): Promise<string>;
+}
+/** Auto-updater control. */
+interface DocblocksHostUpdaterAPI {
+    /** Kick off a check; resolves to true if an update is available. */
+    checkForUpdates(): Promise<boolean>;
+    /** Current app version string. */
+    getVersion(): Promise<string>;
+    /**
+     * Quit the app and apply a downloaded update. Should only be called
+     * after an `UpdaterStatus` of kind `'downloaded'` has been observed.
+     */
+    quitAndInstall(): Promise<void>;
+    /**
+     * Subscribe to updater status events. Returns an unsubscribe function.
+     */
+    onStatus(listener: (status: UpdaterStatus) => void): () => void;
+}
+type UpdaterStatus = {
+    kind: 'checking';
+} | {
+    kind: 'available';
+    version: string;
+    releaseNotes?: string;
+    releaseUrl?: string;
+} | {
+    kind: 'not-available';
+} | {
+    kind: 'downloading';
+    percent: number;
+} | {
+    kind: 'downloaded';
+    version: string;
+    releaseNotes?: string;
+    releaseUrl?: string;
+} | {
+    kind: 'error';
+    message: string;
+};
+/** Menu-command events pushed from the main process to the renderer. */
+type MenuCommand = 'file:new' | 'file:openFolder' | 'file:revealWorkspace' | 'file:settings' | 'help:about' | 'help:checkForUpdates' | 'help:viewOnGitHub';
+/** Deep-link event: the user opened a docblocks:// URL or dropped a file. */
+interface OpenRequest {
+    /** For docblocks:// URLs — the full URL string. */
+    url?: string;
+    /** For file drops / open-with — absolute path to the file. */
+    filePath?: string;
+}
+/** Environment metadata provided by the host. */
+interface HostEnvironment {
+    platform: 'darwin' | 'win32' | 'linux';
+    appVersion: string;
+    isDev: boolean;
+}
+/** The full DocBlocks desktop host API. */
+interface DocblocksHostAPI {
+    env: HostEnvironment;
+    fs: DocblocksHostFsAPI;
+    workspaces: DocblocksHostWorkspacesAPI;
+    shell: DocblocksHostShellAPI;
+    ffmpeg: DocblocksHostFfmpegAPI;
+    updater: DocblocksHostUpdaterAPI;
+    /**
+     * Subscribe to menu commands dispatched by the native menu.
+     * Returns an unsubscribe function.
+     */
+    onMenuCommand(listener: (cmd: MenuCommand) => void): () => void;
+    /**
+     * Subscribe to open-file / open-url requests from the OS.
+     * Returns an unsubscribe function.
+     */
+    onOpenRequest(listener: (request: OpenRequest) => void): () => void;
+}
+
+/**
+ * Host bridge — shared types + runtime access for the Electron desktop
+ * host. The renderer calls `getDocblocksHost()` to reach the preload
+ * contextBridge; `isElectronHost()` gates desktop-only UI branches.
+ */
+
+/** True when running inside the Electron desktop shell. */
+declare function isElectronHost(): boolean;
+/** Return the host API, or throw if not running under Electron. */
+declare function getDocblocksHost(): DocblocksHostAPI;
+/** Return the host API, or null if not running under Electron. */
+declare function maybeGetDocblocksHost(): DocblocksHostAPI | null;
+
+export { type DocblocksHostAPI as D, type ElectronWorkspaceInfo as E, type FileEntry as F, type HostEnvironment as H, type MenuCommand as M, type OpenRequest as O, type UpdaterStatus as U, type DocblocksHostFfmpegAPI as a, type DocblocksHostFsAPI as b, type DocblocksHostShellAPI as c, type DocblocksHostUpdaterAPI as d, type DocblocksHostWorkspacesAPI as e, type FileMeta as f, type FileSystemEntry as g, type FileSystemProvider as h, type FolderEntry as i, getDocblocksHost as j, isElectronHost as k, maybeGetDocblocksHost as m };

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 /**
  * @bendyline/docblocks — Core package
  *
- * Re-exports filesystem and workspace modules for convenience.
+ * Re-exports filesystem, workspace, and host modules for convenience.
  */
 export * from './filesystem/index.js';
 export * from './workspace/index.js';
+export * from './host/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -1,8 +1,9 @@
 /**
  * @bendyline/docblocks — Core package
  *
- * Re-exports filesystem and workspace modules for convenience.
+ * Re-exports filesystem, workspace, and host modules for convenience.
  */
 export * from './filesystem/index.js';
 export * from './workspace/index.js';
+export * from './host/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC"}

package/dist/workspace/types.d.ts

@@ -7,9 +7,16 @@ export interface WorkspaceDescriptor {
     id: string;
     /** User-visible label. */
     name: string;
-    /** 'indexeddb' for browser-local storage, 'native' for File System Access API. */
-    type: 'indexeddb' | 'native';
+    /**
+     * Provider kind:
+     * - 'indexeddb' — browser-local storage (web only)
+     * - 'native' — File System Access API (web Chrome/Edge only)
+     * - 'electron-native' — Electron main-process native filesystem
+     */
+    type: 'indexeddb' | 'native' | 'electron-native';
     /** ISO timestamp of last access. */
     lastOpened: string;
+    /** Absolute filesystem path for 'electron-native' workspaces. */
+    rootPath?: string;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/workspace/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/workspace/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,IAAI,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC7B,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;CACpB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/workspace/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,IAAI,EAAE,WAAW,GAAG,QAAQ,GAAG,iBAAiB,CAAC;IACjD,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/docblocks",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "description": "Core data structures and filesystem abstractions for DocBlocks",
   "license": "MIT",
   "author": "Bendyline",
@@ -42,6 +42,11 @@
       "types": "./dist/workspace/index.d.ts",
       "import": "./dist/workspace/index.js",
       "default": "./dist/workspace/index.js"
+    },
+    "./host": {
+      "types": "./dist/host/index.d.ts",
+      "import": "./dist/host/index.js",
+      "default": "./dist/host/index.js"
     }
   },
   "scripts": {
@@ -49,11 +54,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@bendyline/squisq": "1.2.1",
-    "@bendyline/squisq-editor-react": "1.2.1",
-    "@bendyline/squisq-formats": "1.2.1",
-    "@bendyline/squisq-react": "1.1.1",
-    "@bendyline/squisq-video": "1.0.3",
-    "@bendyline/squisq-video-react": "1.0.3"
+    "@bendyline/squisq": "1.3.0",
+    "@bendyline/squisq-editor-react": "1.4.0",
+    "@bendyline/squisq-formats": "1.2.3",
+    "@bendyline/squisq-react": "1.2.0",
+    "@bendyline/squisq-video": "1.0.5",
+    "@bendyline/squisq-video-react": "1.0.5"
   }
 }

package/src/filesystem/electron-provider.ts

@@ -0,0 +1,88 @@
+/**
+ * ElectronFileSystemProvider — implements FileSystemProvider by delegating
+ * to the Electron desktop host's fs IPC bridge. Every operation is scoped
+ * to an absolute root path that the main process validates against a
+ * whitelist of registered workspace roots.
+ *
+ * This file has no Electron dependency — it is a pure IPC client that
+ * relies on the `docblocksHost` global installed by the preload script.
+ */
+
+import type { FileSystemProvider, FileSystemEntry, FileMeta } from './types.js';
+import { maybeGetDocblocksHost } from '../host/index.js';
+import type { DocblocksHostFsAPI } from '../host/types.js';
+
+export { isElectronHost } from '../host/index.js';
+
+function getHostFs(): DocblocksHostFsAPI {
+  const host = maybeGetDocblocksHost();
+  if (!host) {
+    throw new Error(
+      'ElectronFileSystemProvider: docblocksHost is not available — not running under Electron?',
+    );
+  }
+  return host.fs;
+}
+
+export class ElectronFileSystemProvider implements FileSystemProvider {
+  readonly id: string;
+  readonly label: string;
+
+  private readonly rootPath: string;
+
+  constructor(id: string, label: string, rootPath: string) {
+    this.id = id;
+    this.label = label;
+    this.rootPath = rootPath;
+  }
+
+  /** Absolute path this provider is rooted at. */
+  getRootPath(): string {
+    return this.rootPath;
+  }
+
+  readFile(path: string): Promise<string | null> {
+    return getHostFs().readFile(this.rootPath, path);
+  }
+
+  writeFile(path: string, content: string): Promise<void> {
+    return getHostFs().writeFile(this.rootPath, path, content);
+  }
+
+  delete(path: string): Promise<void> {
+    return getHostFs().delete(this.rootPath, path);
+  }
+
+  rename(oldPath: string, newPath: string): Promise<void> {
+    return getHostFs().rename(this.rootPath, oldPath, newPath);
+  }
+
+  readDirectory(path: string): Promise<FileSystemEntry[]> {
+    return getHostFs().readDirectory(this.rootPath, path);
+  }
+
+  exists(path: string): Promise<boolean> {
+    return getHostFs().exists(this.rootPath, path);
+  }
+
+  createDirectory(path: string): Promise<void> {
+    return getHostFs().createDirectory(this.rootPath, path);
+  }
+
+  stat(path: string): Promise<FileMeta | null> {
+    return getHostFs().stat(this.rootPath, path);
+  }
+
+  readBinary(path: string): Promise<ArrayBuffer | null> {
+    return getHostFs().readBinary(this.rootPath, path);
+  }
+
+  writeBinary(path: string, data: ArrayBuffer | Uint8Array): Promise<void> {
+    return getHostFs().writeBinary(this.rootPath, path, data);
+  }
+
+  /** Subscribe to external change notifications under this root. */
+  watch(onChange: (changedPath: string) => void): () => void {
+    return getHostFs().watch(this.rootPath, onChange);
+  }
+}

package/src/filesystem/file-media-provider.ts

@@ -0,0 +1,103 @@
+/**
+ * createFileMediaProvider — per-file media storage following the pandoc /
+ * Word convention: a markdown file `notes.md` gets a sibling folder
+ * `notes_files/` that holds its images, audio, and video.
+ *
+ * Given:
+ *   • `container` — a ContentContainer scoped to the markdown file's
+ *     parent directory (so `readFile('notes_files/image.png')` maps to the
+ *     parent-relative path)
+ *   • `markdownBasename` — e.g. `"notes.md"`
+ *
+ * Returns a MediaProvider that:
+ *   • Writes new media under `{basename}_files/{name}` in the parent dir
+ *   • Returns the folder-qualified path (`notes_files/image.png`) from
+ *     addMedia so the markdown stays portable outside DocBlocks
+ *   • Resolves both bare (`image.png`) and folder-qualified
+ *     (`notes_files/image.png`) references — so legacy markdown and
+ *     exports from other tools both work
+ */
+
+import type { MediaProvider, MediaEntry } from '@bendyline/squisq/schemas';
+import type { ContentContainer } from '@bendyline/squisq/storage';
+
+function stripExt(name: string): string {
+  return name.replace(/\.[^.]+$/, '');
+}
+
+export function createFileMediaProvider(
+  container: ContentContainer,
+  markdownBasename: string,
+): MediaProvider {
+  const folder = stripExt(markdownBasename) + '_files';
+  const prefix = folder + '/';
+  const blobUrlCache = new Map<string, string>();
+
+  function toKey(ref: string): string {
+    const clean = ref.replace(/^\/+/, '');
+    return clean.startsWith(prefix) ? clean : prefix + clean;
+  }
+
+  return {
+    async resolveUrl(ref: string): Promise<string> {
+      const key = toKey(ref);
+      const cached = blobUrlCache.get(key);
+      if (cached) return cached;
+
+      const data = await container.readFile(key);
+      if (!data) return ref;
+
+      const entries = await container.listFiles();
+      const entry = entries.find((e) => e.path === key);
+      const mimeType = entry?.mimeType ?? 'application/octet-stream';
+
+      const url = URL.createObjectURL(new Blob([data], { type: mimeType }));
+      blobUrlCache.set(key, url);
+      return url;
+    },
+
+    async listMedia(): Promise<MediaEntry[]> {
+      const entries = await container.listFiles(prefix);
+      return entries
+        .filter((e) => !e.path.toLowerCase().endsWith('.md'))
+        .map((e) => ({
+          name: e.path,
+          mimeType: e.mimeType,
+          size: e.size,
+        }));
+    },
+
+    async addMedia(
+      name: string,
+      data: ArrayBuffer | Blob | Uint8Array,
+      mimeType: string,
+    ): Promise<string> {
+      const key = toKey(name);
+      const cached = blobUrlCache.get(key);
+      if (cached) {
+        URL.revokeObjectURL(cached);
+        blobUrlCache.delete(key);
+      }
+      const buffer = data instanceof Blob ? new Uint8Array(await data.arrayBuffer()) : data;
+      await container.writeFile(key, buffer, mimeType);
+      return key;
+    },
+
+    async removeMedia(ref: string): Promise<void> {
+      const key = toKey(ref);
+      const cached = blobUrlCache.get(key);
+      if (cached) {
+        URL.revokeObjectURL(cached);
+        blobUrlCache.delete(key);
+      }
+      await container.removeFile(key);
+    },
+
+    dispose(): void {
+      for (const url of blobUrlCache.values()) {
+        URL.revokeObjectURL(url);
+      }
+      blobUrlCache.clear();
+    },
+  };
+}

package/src/filesystem/filesystem-content-container.ts

@@ -0,0 +1,115 @@
+/**
+ * FileSystemContentContainer — a ContentContainer backed by any
+ * FileSystemProvider, scoped to a sub-path (e.g., ".docblocks/media/").
+ *
+ * Used by the Electron desktop app so media lives inside the workspace
+ * folder (visible as regular files) rather than in a separate IndexedDB
+ * origin that only the app can see.
+ */
+
+import type { ContentContainer, ContentEntry } from '@bendyline/squisq/storage';
+import { findDocumentPath } from '@bendyline/squisq/storage';
+import type { FileSystemProvider } from './types.js';
+
+const EXTENSION_MIME_MAP: Record<string, string> = {
+  '.md': 'text/markdown',
+  '.txt': 'text/plain',
+  '.json': 'application/json',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.png': 'image/png',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+  '.ogg': 'audio/ogg',
+};
+
+function guessMimeType(path: string): string {
+  const dot = path.lastIndexOf('.');
+  if (dot === -1) return 'application/octet-stream';
+  const ext = path.slice(dot).toLowerCase();
+  return EXTENSION_MIME_MAP[ext] ?? 'application/octet-stream';
+}
+
+function joinPrefix(prefix: string, p: string): string {
+  const clean = p.replace(/^\/+/, '');
+  return prefix.replace(/\/+$/, '') + '/' + clean;
+}
+
+export class FileSystemContentContainer implements ContentContainer {
+  private readonly prefix: string;
+
+  constructor(
+    private readonly provider: FileSystemProvider,
+    prefix = '.docblocks/media',
+  ) {
+    this.prefix = prefix.replace(/^\/+/, '').replace(/\/+$/, '');
+  }
+
+  async readFile(path: string): Promise<ArrayBuffer | null> {
+    return this.provider.readBinary(joinPrefix(this.prefix, path));
+  }
+
+  async writeFile(path: string, data: ArrayBuffer | Uint8Array, _mimeType?: string): Promise<void> {
+    await this.provider.writeBinary(joinPrefix(this.prefix, path), data);
+  }
+
+  async removeFile(path: string): Promise<void> {
+    await this.provider.delete(joinPrefix(this.prefix, path));
+  }
+
+  async listFiles(prefix?: string): Promise<ContentEntry[]> {
+    const entries: ContentEntry[] = [];
+    const walk = async (dir: string) => {
+      let children;
+      try {
+        children = await this.provider.readDirectory(dir);
+      } catch {
+        return;
+      }
+      for (const child of children) {
+        if (child.kind === 'directory') {
+          await walk(child.path);
+        } else {
+          const rel = child.path.replace(new RegExp('^/?' + this.prefix + '/?'), '');
+          if (prefix && !rel.startsWith(prefix)) continue;
+          const meta = await this.provider.stat(child.path);
+          entries.push({
+            path: rel,
+            mimeType: guessMimeType(rel),
+            size: meta?.size ?? 0,
+          });
+        }
+      }
+    };
+    await walk('/' + this.prefix);
+    return entries;
+  }
+
+  async exists(path: string): Promise<boolean> {
+    return this.provider.exists(joinPrefix(this.prefix, path));
+  }
+
+  async getDocumentPath(): Promise<string | null> {
+    return findDocumentPath(await this.listFiles());
+  }
+
+  async readDocument(): Promise<string | null> {
+    const docPath = await this.getDocumentPath();
+    if (!docPath) return null;
+    const data = await this.readFile(docPath);
+    if (!data) return null;
+    return new TextDecoder().decode(data);
+  }
+
+  async writeDocument(markdown: string, filename?: string): Promise<void> {
+    const name = filename ?? 'index.md';
+    const data = new TextEncoder().encode(markdown);
+    await this.writeFile(name, data, 'text/markdown');
+  }
+}

package/src/filesystem/index.ts

@@ -8,6 +8,8 @@ export type {
 
 export { IndexedDBFileSystemProvider } from './indexeddb-provider.js';
 export { IndexedDBContentContainer } from './indexeddb-content-container.js';
+export { FileSystemContentContainer } from './filesystem-content-container.js';
+export { createFileMediaProvider } from './file-media-provider.js';
 
 export {
   NativeFileSystemProvider,
@@ -18,3 +20,5 @@ export {
   loadDirectoryHandle,
   removeDirectoryHandle,
 } from './native-provider.js';
+
+export { ElectronFileSystemProvider, isElectronHost } from './electron-provider.js';

package/src/host/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Host bridge — shared types + runtime access for the Electron desktop
+ * host. The renderer calls `getDocblocksHost()` to reach the preload
+ * contextBridge; `isElectronHost()` gates desktop-only UI branches.
+ */
+
+export type {
+  DocblocksHostAPI,
+  DocblocksHostFsAPI,
+  DocblocksHostWorkspacesAPI,
+  DocblocksHostShellAPI,
+  DocblocksHostFfmpegAPI,
+  DocblocksHostUpdaterAPI,
+  ElectronWorkspaceInfo,
+  HostEnvironment,
+  MenuCommand,
+  OpenRequest,
+  UpdaterStatus,
+} from './types.js';
+
+import type { DocblocksHostAPI } from './types.js';
+
+/** True when running inside the Electron desktop shell. */
+export function isElectronHost(): boolean {
+  if (typeof globalThis === 'undefined') return false;
+  const host = (globalThis as { docblocksHost?: unknown }).docblocksHost;
+  return (
+    typeof host === 'object' &&
+    host !== null &&
+    typeof (host as { fs?: unknown }).fs === 'object' &&
+    (host as { fs?: unknown }).fs !== null
+  );
+}
+
+/** Return the host API, or throw if not running under Electron. */
+export function getDocblocksHost(): DocblocksHostAPI {
+  const host = (globalThis as { docblocksHost?: DocblocksHostAPI }).docblocksHost;
+  if (!host) {
+    throw new Error('docblocksHost is not available — not running under Electron?');
+  }
+  return host;
+}
+
+/** Return the host API, or null if not running under Electron. */
+export function maybeGetDocblocksHost(): DocblocksHostAPI | null {
+  return (globalThis as { docblocksHost?: DocblocksHostAPI }).docblocksHost ?? null;
+}