@bendyline/squisq 1.0.1 → 1.1.0

package/src/__tests__/contentContainer.test.ts

@@ -0,0 +1,282 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { MemoryContentContainer, findDocumentPath } from '../storage/ContentContainer';
+import { createMediaProviderFromContainer } from '../storage/MediaProviderFromContainer';
+import type { ContentEntry } from '../storage/ContentContainer';
+
+// ============================================
+// MemoryContentContainer
+// ============================================
+
+describe('MemoryContentContainer', () => {
+  let container: MemoryContentContainer;
+
+  beforeEach(() => {
+    container = new MemoryContentContainer();
+  });
+
+  it('readFile returns null for missing file', async () => {
+    expect(await container.readFile('missing.txt')).toBeNull();
+  });
+
+  it('writeFile and readFile round-trip', async () => {
+    const data = new TextEncoder().encode('hello world');
+    await container.writeFile('test.txt', data, 'text/plain');
+    const result = await container.readFile('test.txt');
+    expect(result).not.toBeNull();
+    expect(new TextDecoder().decode(result!)).toBe('hello world');
+  });
+
+  it('writeFile with ArrayBuffer', async () => {
+    const buf = new ArrayBuffer(4);
+    new Uint8Array(buf).set([1, 2, 3, 4]);
+    await container.writeFile('data.bin', buf);
+    const result = await container.readFile('data.bin');
+    expect(new Uint8Array(result!)).toEqual(new Uint8Array([1, 2, 3, 4]));
+  });
+
+  it('writeFile overwrites existing file', async () => {
+    await container.writeFile('f.txt', new TextEncoder().encode('first'));
+    await container.writeFile('f.txt', new TextEncoder().encode('second'));
+    const result = await container.readFile('f.txt');
+    expect(new TextDecoder().decode(result!)).toBe('second');
+  });
+
+  it('removeFile deletes a file', async () => {
+    await container.writeFile('f.txt', new TextEncoder().encode('data'));
+    await container.removeFile('f.txt');
+    expect(await container.readFile('f.txt')).toBeNull();
+  });
+
+  it('removeFile is a no-op for missing file', async () => {
+    // Should not throw
+    await container.removeFile('nonexistent.txt');
+  });
+
+  it('exists returns true for existing file', async () => {
+    await container.writeFile('f.txt', new TextEncoder().encode('data'));
+    expect(await container.exists('f.txt')).toBe(true);
+  });
+
+  it('exists returns false for missing file', async () => {
+    expect(await container.exists('missing.txt')).toBe(false);
+  });
+
+  it('listFiles returns all files', async () => {
+    await container.writeFile('a.txt', new TextEncoder().encode('a'), 'text/plain');
+    await container.writeFile('b.jpg', new Uint8Array([0xff, 0xd8]), 'image/jpeg');
+    const entries = await container.listFiles();
+    expect(entries).toHaveLength(2);
+    expect(entries.map((e) => e.path).sort()).toEqual(['a.txt', 'b.jpg']);
+  });
+
+  it('listFiles with prefix filters results', async () => {
+    await container.writeFile('index.md', new TextEncoder().encode('# Hi'));
+    await container.writeFile('images/hero.jpg', new Uint8Array([0xff]));
+    await container.writeFile('images/bg.png', new Uint8Array([0x89]));
+    await container.writeFile('audio/clip.mp3', new Uint8Array([0x49]));
+
+    const imageEntries = await container.listFiles('images/');
+    expect(imageEntries).toHaveLength(2);
+    expect(imageEntries.map((e) => e.path).sort()).toEqual(['images/bg.png', 'images/hero.jpg']);
+  });
+
+  it('listFiles reports correct size', async () => {
+    const data = new Uint8Array([1, 2, 3, 4, 5]);
+    await container.writeFile('data.bin', data);
+    const entries = await container.listFiles();
+    expect(entries[0].size).toBe(5);
+  });
+
+  it('listFiles guesses MIME type from extension', async () => {
+    await container.writeFile('photo.jpg', new Uint8Array([0xff]));
+    const entries = await container.listFiles();
+    expect(entries[0].mimeType).toBe('image/jpeg');
+  });
+
+  it('listFiles uses provided MIME type over guess', async () => {
+    await container.writeFile('data.bin', new Uint8Array([0]), 'application/custom');
+    const entries = await container.listFiles();
+    expect(entries[0].mimeType).toBe('application/custom');
+  });
+});
+
+// ============================================
+// Document discovery
+// ============================================
+
+describe('getDocumentPath', () => {
+  let container: MemoryContentContainer;
+
+  beforeEach(() => {
+    container = new MemoryContentContainer();
+  });
+
+  it('returns null for empty container', async () => {
+    expect(await container.getDocumentPath()).toBeNull();
+  });
+
+  it('finds index.md', async () => {
+    await container.writeFile('index.md', new TextEncoder().encode('# Hello'));
+    expect(await container.getDocumentPath()).toBe('index.md');
+  });
+
+  it('prefers index.md over doc.md', async () => {
+    await container.writeFile('doc.md', new TextEncoder().encode('doc'));
+    await container.writeFile('index.md', new TextEncoder().encode('index'));
+    expect(await container.getDocumentPath()).toBe('index.md');
+  });
+
+  it('prefers doc.md over document.md', async () => {
+    await container.writeFile('document.md', new TextEncoder().encode('document'));
+    await container.writeFile('doc.md', new TextEncoder().encode('doc'));
+    expect(await container.getDocumentPath()).toBe('doc.md');
+  });
+
+  it('prefers document.md over arbitrary .md', async () => {
+    await container.writeFile('readme.md', new TextEncoder().encode('readme'));
+    await container.writeFile('document.md', new TextEncoder().encode('document'));
+    expect(await container.getDocumentPath()).toBe('document.md');
+  });
+
+  it('falls back to first .md at root', async () => {
+    await container.writeFile('my-story.md', new TextEncoder().encode('story'));
+    expect(await container.getDocumentPath()).toBe('my-story.md');
+  });
+
+  it('ignores .md files in subdirectories', async () => {
+    await container.writeFile('docs/notes.md', new TextEncoder().encode('notes'));
+    expect(await container.getDocumentPath()).toBeNull();
+  });
+
+  it('ignores non-md files', async () => {
+    await container.writeFile('data.json', new TextEncoder().encode('{}'));
+    await container.writeFile('hero.jpg', new Uint8Array([0xff]));
+    expect(await container.getDocumentPath()).toBeNull();
+  });
+});
+
+describe('readDocument / writeDocument', () => {
+  let container: MemoryContentContainer;
+
+  beforeEach(() => {
+    container = new MemoryContentContainer();
+  });
+
+  it('writeDocument creates index.md by default', async () => {
+    await container.writeDocument('# Hello');
+    expect(await container.getDocumentPath()).toBe('index.md');
+    expect(await container.readDocument()).toBe('# Hello');
+  });
+
+  it('writeDocument uses custom filename', async () => {
+    await container.writeDocument('# Custom', 'story.md');
+    expect(await container.getDocumentPath()).toBe('story.md');
+    expect(await container.readDocument()).toBe('# Custom');
+  });
+
+  it('readDocument returns null for empty container', async () => {
+    expect(await container.readDocument()).toBeNull();
+  });
+});
+
+// ============================================
+// findDocumentPath (standalone)
+// ============================================
+
+describe('findDocumentPath', () => {
+  it('returns null for empty list', () => {
+    expect(findDocumentPath([])).toBeNull();
+  });
+
+  it('finds index.md from entry list', () => {
+    const entries: ContentEntry[] = [
+      { path: 'images/hero.jpg', mimeType: 'image/jpeg', size: 100 },
+      { path: 'index.md', mimeType: 'text/markdown', size: 50 },
+    ];
+    expect(findDocumentPath(entries)).toBe('index.md');
+  });
+
+  it('skips subdirectory .md files', () => {
+    const entries: ContentEntry[] = [
+      { path: 'docs/guide.md', mimeType: 'text/markdown', size: 50 },
+    ];
+    expect(findDocumentPath(entries)).toBeNull();
+  });
+});
+
+// ============================================
+// createMediaProviderFromContainer
+// ============================================
+
+describe('createMediaProviderFromContainer', () => {
+  let container: MemoryContentContainer;
+  let blobCounter = 0;
+
+  beforeEach(() => {
+    container = new MemoryContentContainer();
+    blobCounter = 0;
+    // Mock URL.createObjectURL / revokeObjectURL (not available in Node)
+    vi.stubGlobal('URL', {
+      ...URL,
+      createObjectURL: () => `blob:mock-${++blobCounter}`,
+      revokeObjectURL: vi.fn(),
+    });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('resolveUrl returns path as-is for missing file', async () => {
+    const provider = createMediaProviderFromContainer(container);
+    expect(await provider.resolveUrl('missing.jpg')).toBe('missing.jpg');
+    provider.dispose();
+  });
+
+  it('resolveUrl returns blob URL for existing file', async () => {
+    await container.writeFile('hero.jpg', new Uint8Array([0xff, 0xd8]), 'image/jpeg');
+    const provider = createMediaProviderFromContainer(container);
+    const url = await provider.resolveUrl('hero.jpg');
+    expect(url).toMatch(/^blob:/);
+    provider.dispose();
+  });
+
+  it('resolveUrl caches blob URLs', async () => {
+    await container.writeFile('hero.jpg', new Uint8Array([0xff, 0xd8]), 'image/jpeg');
+    const provider = createMediaProviderFromContainer(container);
+    const url1 = await provider.resolveUrl('hero.jpg');
+    const url2 = await provider.resolveUrl('hero.jpg');
+    expect(url1).toBe(url2);
+    provider.dispose();
+  });
+
+  it('listMedia excludes markdown files', async () => {
+    await container.writeFile('index.md', new TextEncoder().encode('# Doc'));
+    await container.writeFile('hero.jpg', new Uint8Array([0xff]), 'image/jpeg');
+    await container.writeFile('clip.mp4', new Uint8Array([0x00]), 'video/mp4');
+
+    const provider = createMediaProviderFromContainer(container);
+    const media = await provider.listMedia();
+    expect(media).toHaveLength(2);
+    expect(media.map((m) => m.name).sort()).toEqual(['clip.mp4', 'hero.jpg']);
+    provider.dispose();
+  });
+
+  it('addMedia writes to container and returns path', async () => {
+    const provider = createMediaProviderFromContainer(container);
+    const path = await provider.addMedia('photo.png', new Uint8Array([0x89]), 'image/png');
+    expect(path).toBe('photo.png');
+    expect(await container.exists('photo.png')).toBe(true);
+    provider.dispose();
+  });
+
+  it('removeMedia deletes from container', async () => {
+    await container.writeFile('hero.jpg', new Uint8Array([0xff]), 'image/jpeg');
+    const provider = createMediaProviderFromContainer(container);
+    // Resolve first to populate cache
+    await provider.resolveUrl('hero.jpg');
+    await provider.removeMedia('hero.jpg');
+    expect(await container.exists('hero.jpg')).toBe(false);
+    provider.dispose();
+  });
+});

package/src/storage/ContentContainer.ts

@@ -0,0 +1,200 @@
+/**
+ * ContentContainer — virtual file system for document containers.
+ *
+ * A Squisq document is more than just markdown: it's a container of files
+ * including the primary markdown document, images, audio, timing data, and
+ * other media. ContentContainer provides an abstract async file system
+ * interface for reading, writing, and listing these files.
+ *
+ * Paths are forward-slash separated strings relative to the container root
+ * (e.g., 'images/hero.jpg', 'index.md'). No leading slash.
+ *
+ * Implementations:
+ * - MemoryContentContainer — in-memory Map (for zip import, tests, transient use)
+ * - SlotContentContainer — backed by IndexedDB slot storage (in the site package)
+ */
+
+/**
+ * Metadata about a file in a ContentContainer.
+ */
+export interface ContentEntry {
+  /** Relative path within the container (e.g., 'images/hero.jpg') */
+  path: string;
+  /** MIME type (e.g., 'image/jpeg') */
+  mimeType: string;
+  /** File size in bytes */
+  size: number;
+}
+
+/**
+ * Abstract async file system for document containers.
+ *
+ * All paths are forward-slash separated, relative to the container root,
+ * with no leading slash. Example: 'images/hero.jpg', 'index.md'.
+ */
+export interface ContentContainer {
+  /** Read a file's binary content. Returns null if the file does not exist. */
+  readFile(path: string): Promise<ArrayBuffer | null>;
+
+  /** Write a file. Creates or overwrites. */
+  writeFile(path: string, data: ArrayBuffer | Uint8Array, mimeType?: string): Promise<void>;
+
+  /** Remove a file. No-op if the file does not exist. */
+  removeFile(path: string): Promise<void>;
+
+  /**
+   * List files in the container.
+   * @param prefix — Optional path prefix to filter by (e.g., 'images/')
+   */
+  listFiles(prefix?: string): Promise<ContentEntry[]>;
+
+  /** Check whether a file exists. */
+  exists(path: string): Promise<boolean>;
+
+  /**
+   * Find the primary markdown document path.
+   *
+   * Discovery order: index.md → doc.md → document.md → first *.md at root.
+   * Returns null if no markdown file is found at the root level.
+   */
+  getDocumentPath(): Promise<string | null>;
+
+  /**
+   * Convenience: read the primary markdown document as a UTF-8 string.
+   * Returns null if no markdown file is found.
+   */
+  readDocument(): Promise<string | null>;
+
+  /**
+   * Convenience: write a markdown document.
+   * @param markdown — The markdown content
+   * @param filename — Filename to use (defaults to 'index.md')
+   */
+  writeDocument(markdown: string, filename?: string): Promise<void>;
+}
+
+// ============================================
+// Well-known markdown filenames in priority order
+// ============================================
+
+const MARKDOWN_PRIORITY = ['index.md', 'doc.md', 'document.md'];
+
+/**
+ * Find the primary markdown path from a list of file entries.
+ * Exported for reuse by other ContentContainer implementations.
+ */
+export function findDocumentPath(entries: ContentEntry[]): string | null {
+  // Only consider root-level files (no '/' in path)
+  const rootFiles = entries.filter((e) => !e.path.includes('/'));
+
+  for (const name of MARKDOWN_PRIORITY) {
+    if (rootFiles.some((e) => e.path.toLowerCase() === name)) {
+      return name;
+    }
+  }
+
+  // Fallback: first .md file at root
+  const firstMd = rootFiles.find((e) => e.path.toLowerCase().endsWith('.md'));
+  return firstMd?.path ?? null;
+}
+
+// ============================================
+// MemoryContentContainer
+// ============================================
+
+interface MemoryFile {
+  data: ArrayBuffer;
+  mimeType: string;
+}
+
+/**
+ * In-memory ContentContainer backed by a Map.
+ *
+ * Used for zip import (deserialize into memory), tests, and transient operations.
+ */
+export class MemoryContentContainer implements ContentContainer {
+  private files = new Map<string, MemoryFile>();
+
+  async readFile(path: string): Promise<ArrayBuffer | null> {
+    return this.files.get(path)?.data ?? null;
+  }
+
+  async writeFile(path: string, data: ArrayBuffer | Uint8Array, mimeType?: string): Promise<void> {
+    const buffer = data instanceof ArrayBuffer ? data : data.slice().buffer;
+    this.files.set(path, {
+      data: buffer,
+      mimeType: mimeType ?? guessMimeType(path),
+    });
+  }
+
+  async removeFile(path: string): Promise<void> {
+    this.files.delete(path);
+  }
+
+  async listFiles(prefix?: string): Promise<ContentEntry[]> {
+    const entries: ContentEntry[] = [];
+    for (const [path, file] of this.files) {
+      if (prefix && !path.startsWith(prefix)) continue;
+      entries.push({
+        path,
+        mimeType: file.mimeType,
+        size: file.data.byteLength,
+      });
+    }
+    return entries;
+  }
+
+  async exists(path: string): Promise<boolean> {
+    return this.files.has(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');
+  }
+}
+
+// ============================================
+// MIME type guessing
+// ============================================
+
+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',
+  '.css': 'text/css',
+  '.html': 'text/html',
+  '.js': 'application/javascript',
+};
+
+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';
+}

package/src/storage/MediaProviderFromContainer.ts

@@ -0,0 +1,92 @@
+/**
+ * MediaProviderFromContainer — bridges ContentContainer to MediaProvider.
+ *
+ * Creates a MediaProvider that resolves relative paths by reading binary data
+ * from a ContentContainer and generating blob URLs. Blob URLs are cached and
+ * revoked on dispose().
+ *
+ * This allows any ContentContainer (memory, slot-backed, zip-loaded) to be
+ * used with existing rendering components (DocPlayer, ImageLayer, VideoLayer)
+ * that consume MediaProvider.
+ */
+
+import type { MediaProvider, MediaEntry } from '../schemas/MediaProvider.js';
+import type { ContentContainer } from './ContentContainer.js';
+
+/**
+ * Create a MediaProvider backed by a ContentContainer.
+ *
+ * @param container — The ContentContainer to read/write media from
+ * @returns A MediaProvider that resolves paths to blob URLs
+ */
+export function createMediaProviderFromContainer(container: ContentContainer): MediaProvider {
+  const blobUrlCache = new Map<string, string>();
+
+  return {
+    async resolveUrl(relativePath: string): Promise<string> {
+      const cached = blobUrlCache.get(relativePath);
+      if (cached) return cached;
+
+      const data = await container.readFile(relativePath);
+      if (!data) return relativePath;
+
+      const entries = await container.listFiles();
+      const entry = entries.find((e) => e.path === relativePath);
+      const mimeType = entry?.mimeType ?? 'application/octet-stream';
+
+      const blob = new Blob([data], { type: mimeType });
+      const url = URL.createObjectURL(blob);
+      blobUrlCache.set(relativePath, url);
+      return url;
+    },
+
+    async listMedia(): Promise<MediaEntry[]> {
+      const entries = await container.listFiles();
+      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> {
+      // Invalidate any cached blob URL for this path before overwriting
+      const cached = blobUrlCache.get(name);
+      if (cached) {
+        URL.revokeObjectURL(cached);
+        blobUrlCache.delete(name);
+      }
+
+      let buffer: ArrayBuffer | Uint8Array;
+      if (data instanceof Blob) {
+        buffer = await data.arrayBuffer();
+      } else {
+        buffer = data;
+      }
+      await container.writeFile(name, buffer, mimeType);
+      return name;
+    },
+
+    async removeMedia(relativePath: string): Promise<void> {
+      const cached = blobUrlCache.get(relativePath);
+      if (cached) {
+        URL.revokeObjectURL(cached);
+        blobUrlCache.delete(relativePath);
+      }
+      await container.removeFile(relativePath);
+    },
+
+    dispose(): void {
+      for (const url of blobUrlCache.values()) {
+        URL.revokeObjectURL(url);
+      }
+      blobUrlCache.clear();
+    },
+  };
+}

package/src/storage/index.ts

@@ -3,3 +3,6 @@ export { MemoryStorageAdapter } from './MemoryStorageAdapter.js';
 export { LocalStorageAdapter } from './LocalStorageAdapter.js';
 export { LocalForageAdapter } from './LocalForageAdapter.js';
 export type { LocalForageAdapterOptions } from './LocalForageAdapter.js';
+export type { ContentContainer, ContentEntry } from './ContentContainer.js';
+export { MemoryContentContainer, findDocumentPath } from './ContentContainer.js';
+export { createMediaProviderFromContainer } from './MediaProviderFromContainer.js';