@bendyline/docblocks 1.0.0 → 1.1.1

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,126 @@
+/**
+ * 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> {
+    const full = joinPrefix(this.prefix, path);
+    const binary = await this.provider.readBinary(full);
+    if (binary) return binary;
+    // IndexedDB-backed workspaces store text via `writeFile(string)` and
+    // binary via `writeBinary(ArrayBuffer)` under separate keys, so a
+    // markdown file written through the text API is invisible to
+    // `readBinary`. Fall back to text-then-UTF-8 so consumers like the
+    // recursive HTML export can resolve sibling `.md` links uniformly
+    // across browser and native workspaces.
+    const text = await this.provider.readFile(full);
+    if (text === null) return null;
+    return new TextEncoder().encode(text).buffer as ArrayBuffer;
+  }
+
+  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/filesystem/indexeddb-provider.ts

@@ -153,6 +153,66 @@ export class IndexedDBFileSystemProvider implements FileSystemProvider {
   async rename(oldPath: string, newPath: string): Promise<void> {
     const op = normalisePath(oldPath);
     const np = normalisePath(newPath);
+    if (op === np) return;
+    if (!op || !np) {
+      throw new Error('Cannot rename the filesystem root');
+    }
+    if (np.startsWith(op + '/')) {
+      throw new Error('Cannot move a directory into itself');
+    }
+
+    const dirs = await this.getDirs();
+
+    // Handle directory rename by moving every tracked child directory and
+    // every file record keyed under the old directory prefix.
+    if (dirs.has(op)) {
+      const newParent = parentDir(np);
+      if (newParent) {
+        await this.ensureDir(newParent);
+      }
+
+      const allKeys = await this.store.keys();
+      const oldKeyPrefix = `fs:${op}/`;
+      const newKeyPrefix = `fs:${np}/`;
+      const metaSuffix = ':meta';
+      const keysToMove = allKeys.filter((k) => k.startsWith(oldKeyPrefix));
+
+      await Promise.all(
+        keysToMove.map(async (oldKey) => {
+          const newKey = newKeyPrefix + oldKey.slice(oldKeyPrefix.length);
+          if (oldKey.endsWith(metaSuffix)) {
+            const meta = await this.store.get<FileMeta>(oldKey);
+            if (meta) {
+              const newFilePath = newKey.slice(3, -metaSuffix.length);
+              await this.store.set(metaKey(newFilePath), {
+                ...meta,
+                name: baseName(newFilePath),
+                path: newFilePath,
+              });
+            }
+          } else {
+            const value = await this.store.get<unknown>(oldKey);
+            if (value !== null) {
+              await this.store.set(newKey, value);
+            }
+          }
+          await this.store.remove(oldKey);
+        }),
+      );
+
+      dirs.delete(op);
+      dirs.add(np);
+      const oldPrefix = op + '/';
+      const newPrefix = np + '/';
+      for (const d of [...dirs]) {
+        if (d.startsWith(oldPrefix)) {
+          dirs.delete(d);
+          dirs.add(newPrefix + d.slice(oldPrefix.length));
+        }
+      }
+      await this.saveDirs(dirs);
+      return;
+    }
 
     // Read existing data
     const content = await this.store.get<string>(contentKey(op));
@@ -167,9 +227,11 @@ export class IndexedDBFileSystemProvider implements FileSystemProvider {
       await this.store.set(binaryKey(np), binary);
     }
     if (meta) {
-      meta.name = baseName(np);
-      meta.path = np;
-      await this.store.set(metaKey(np), meta);
+      await this.store.set(metaKey(np), {
+        ...meta,
+        name: baseName(np),
+        path: np,
+      });
     }
 
     // Ensure parent dir of new path exists
@@ -182,22 +244,6 @@ export class IndexedDBFileSystemProvider implements FileSystemProvider {
     await this.store.remove(contentKey(op));
     await this.store.remove(binaryKey(op));
     await this.store.remove(metaKey(op));
-
-    // Handle directory rename
-    const dirs = await this.getDirs();
-    if (dirs.has(op)) {
-      dirs.delete(op);
-      dirs.add(np);
-      const oldPrefix = op + '/';
-      const newPrefix = np + '/';
-      for (const d of [...dirs]) {
-        if (d.startsWith(oldPrefix)) {
-          dirs.delete(d);
-          dirs.add(newPrefix + d.slice(oldPrefix.length));
-        }
-      }
-      await this.saveDirs(dirs);
-    }
   }
 
   async readDirectory(path: string): Promise<FileSystemEntry[]> {

package/src/filesystem/native-provider.ts

@@ -153,6 +153,28 @@ export class NativeFileSystemProvider implements FileSystemProvider {
     this.root = root;
   }
 
+  private async copyDirectory(oldDirPath: string, newDirPath: string): Promise<boolean> {
+    const source = await resolveDir(this.root, oldDirPath);
+    if (!source) return false;
+    await resolveDirCreate(this.root, newDirPath);
+
+    for await (const [name, handle] of source as unknown as AsyncIterable<
+      [string, FileSystemHandle]
+    >) {
+      const oldChild = oldDirPath ? `${oldDirPath}/${name}` : name;
+      const newChild = newDirPath ? `${newDirPath}/${name}` : name;
+      if (handle.kind === 'directory') {
+        await this.copyDirectory(oldChild, newChild);
+      } else {
+        const fileHandle = await source.getFileHandle(name);
+        const file = await fileHandle.getFile();
+        await this.writeBinary(newChild, await file.arrayBuffer());
+      }
+    }
+
+    return true;
+  }
+
   async readFile(path: string): Promise<string | null> {
     const p = normalisePath(path);
     const dir = await resolveDir(this.root, parentDir(p));
@@ -187,20 +209,31 @@ export class NativeFileSystemProvider implements FileSystemProvider {
   async rename(oldPath: string, newPath: string): Promise<void> {
     const op = normalisePath(oldPath);
     const np = normalisePath(newPath);
+    if (op === np) return;
+    if (!op || !np) {
+      throw new Error('Cannot rename the filesystem root');
+    }
+    if (np.startsWith(op + '/')) {
+      throw new Error('Cannot move a directory into itself');
+    }
 
     // The File System Access API doesn't have a native rename.
-    // Read → write → delete.
-    const content = await this.readFile(op);
-    if (content !== null) {
-      await this.writeFile(np, content);
+    // Copy → delete.
+    const oldParent = await resolveDir(this.root, parentDir(op));
+    if (!oldParent) return;
+
+    try {
+      const fileHandle = await oldParent.getFileHandle(baseName(op));
+      const file = await fileHandle.getFile();
+      await this.writeBinary(np, await file.arrayBuffer());
       await this.delete(op);
       return;
+    } catch {
+      // Not a file; try directory below.
     }
 
-    // Try binary
-    const binary = await this.readBinary(op);
-    if (binary !== null) {
-      await this.writeBinary(np, binary);
+    const copied = await this.copyDirectory(op, np);
+    if (copied) {
       await this.delete(op);
     }
   }

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;
+}