@bendyline/squisq 1.3.0 → 1.4.0

package/src/schemas/themes/minimalist.json

@@ -0,0 +1,45 @@
+{
+  "schemaVersion": "1",
+  "id": "minimalist",
+  "name": "Minimalist",
+  "description": "Clean near-white background with sans-serif type and minimal animation.",
+  "colors": {
+    "primary": "#2d3748",
+    "secondary": "#4a5568",
+    "background": "#f7fafc",
+    "backgroundLight": "#edf2f7",
+    "text": "#1a202c",
+    "textMuted": "#718096",
+    "highlight": "#3182ce",
+    "warning": "#e53e3e"
+  },
+  "typography": {
+    "bodyFont": { "stackId": "inter" },
+    "titleFont": { "stackId": "inter" },
+    "titleWeight": "bold",
+    "lineHeight": 1.6
+  },
+  "style": {
+    "textShadow": false,
+    "overlayOpacity": 0.3,
+    "animationSpeed": 1.2,
+    "borderRadius": 8
+  },
+  "renderStyle": {
+    "name": "minimalist",
+    "defaultTextAnimation": "fadeIn",
+    "ambientMotion": false,
+    "defaultTransition": { "type": "fade", "duration": 0.6 },
+    "templateHints": {
+      "title": { "showAccentLine": false }
+    }
+  },
+  "colorSchemes": {
+    "blue": { "bg": "#ebf8ff", "text": "#2b6cb0", "accent": "#3182ce" },
+    "green": { "bg": "#f0fff4", "text": "#276749", "accent": "#38a169" },
+    "purple": { "bg": "#faf5ff", "text": "#553c9a", "accent": "#805ad5" },
+    "red": { "bg": "#fff5f5", "text": "#c53030", "accent": "#e53e3e" },
+    "orange": { "bg": "#fffaf0", "text": "#c05621", "accent": "#dd6b20" },
+    "teal": { "bg": "#e6fffa", "text": "#285e61", "accent": "#319795" }
+  }
+}

package/src/schemas/themes/morning-light.json

@@ -0,0 +1,42 @@
+{
+  "schemaVersion": "1",
+  "id": "morning-light",
+  "name": "Morning Light",
+  "description": "Warm light background with dark text and gentle serif typography.",
+  "colors": {
+    "primary": "#744210",
+    "secondary": "#975a16",
+    "background": "#faf8f5",
+    "backgroundLight": "#f5f0eb",
+    "text": "#2d3748",
+    "textMuted": "#718096",
+    "highlight": "#dd6b20",
+    "warning": "#c53030"
+  },
+  "typography": {
+    "bodyFont": { "stackId": "lora" },
+    "titleFont": { "stackId": "merriweather" },
+    "titleWeight": "bold",
+    "lineHeight": 1.7
+  },
+  "style": {
+    "textShadow": false,
+    "overlayOpacity": 0.35,
+    "animationSpeed": 1.1,
+    "borderRadius": 4
+  },
+  "renderStyle": {
+    "name": "morning-light",
+    "defaultTextAnimation": "fadeIn",
+    "ambientMotion": false,
+    "defaultTransition": { "type": "fade", "duration": 1.0 }
+  },
+  "colorSchemes": {
+    "blue": { "bg": "#ebf8ff", "text": "#2c5282", "accent": "#4299e1" },
+    "green": { "bg": "#f0fff4", "text": "#22543d", "accent": "#48bb78" },
+    "purple": { "bg": "#faf5ff", "text": "#44337a", "accent": "#9f7aea" },
+    "red": { "bg": "#fff5f5", "text": "#9b2c2c", "accent": "#fc8181" },
+    "orange": { "bg": "#fffaf0", "text": "#744210", "accent": "#ed8936" },
+    "teal": { "bg": "#e6fffa", "text": "#234e52", "accent": "#38b2ac" }
+  }
+}

package/src/schemas/themes/standard-dark.json

@@ -0,0 +1,50 @@
+{
+  "schemaVersion": "1",
+  "id": "standard-dark",
+  "name": "Standard Dark",
+  "description": "Standard, dark variant. System fonts, dark navy background, light text.",
+  "colors": {
+    "primary": "#3182ce",
+    "secondary": "#4a5568",
+    "background": "#1a202c",
+    "backgroundLight": "#2d3748",
+    "text": "#f7fafc",
+    "textMuted": "#a0aec0",
+    "highlight": "#4299e1",
+    "warning": "#fc8181"
+  },
+  "typography": {
+    "bodyFont": { "stackId": "system-sans" },
+    "titleFont": { "stackId": "system-serif" },
+    "monoFont": { "stackId": "system-mono" },
+    "titleWeight": "bold"
+  },
+  "style": {
+    "textShadow": true,
+    "overlayOpacity": 0.45,
+    "animationSpeed": 1.0
+  },
+  "renderStyle": {
+    "name": "standard",
+    "defaultTextAnimation": "fadeIn",
+    "defaultImageAnimation": "slowZoom",
+    "ambientMotion": true,
+    "defaultTransition": { "type": "fade", "duration": 0.7 }
+  },
+  "colorSchemes": {
+    "blue": { "bg": "#1a365d", "text": "#63b3ed", "accent": "#90cdf4" },
+    "green": { "bg": "#22543d", "text": "#9ae6b4", "accent": "#68d391" },
+    "purple": { "bg": "#44337a", "text": "#d6bcfa", "accent": "#b794f4" },
+    "red": { "bg": "#742a2a", "text": "#fc8181", "accent": "#feb2b2" },
+    "orange": { "bg": "#744210", "text": "#fbd38d", "accent": "#f6ad55" },
+    "teal": { "bg": "#234e52", "text": "#81e6d9", "accent": "#4fd1c5" }
+  },
+  "persistentLayers": {
+    "bottomLayers": [
+      {
+        "template": "gradientBackground",
+        "config": { "type": "gradientBackground", "preset": "dark-vignette" }
+      }
+    ]
+  }
+}

package/src/schemas/themes/standard.json

@@ -0,0 +1,42 @@
+{
+  "schemaVersion": "1",
+  "id": "standard",
+  "name": "Standard Light",
+  "description": "Clean and safe — black-on-white, system fonts only, no external font dependencies. Default theme.",
+  "colors": {
+    "primary": "#2563eb",
+    "secondary": "#475569",
+    "background": "#ffffff",
+    "backgroundLight": "#f1f5f9",
+    "text": "#0f172a",
+    "textMuted": "#475569",
+    "highlight": "#1d4ed8",
+    "warning": "#dc2626"
+  },
+  "typography": {
+    "bodyFont": { "stackId": "system-sans" },
+    "titleFont": { "stackId": "system-serif" },
+    "monoFont": { "stackId": "system-mono" },
+    "titleWeight": "bold"
+  },
+  "style": {
+    "textShadow": false,
+    "overlayOpacity": 0.35,
+    "animationSpeed": 1.0
+  },
+  "renderStyle": {
+    "name": "standard",
+    "defaultTextAnimation": "fadeIn",
+    "defaultImageAnimation": "slowZoom",
+    "ambientMotion": true,
+    "defaultTransition": { "type": "fade", "duration": 0.7 }
+  },
+  "colorSchemes": {
+    "blue": { "bg": "#dbeafe", "text": "#1d4ed8", "accent": "#2563eb" },
+    "green": { "bg": "#dcfce7", "text": "#166534", "accent": "#16a34a" },
+    "purple": { "bg": "#ede9fe", "text": "#5b21b6", "accent": "#7c3aed" },
+    "red": { "bg": "#fee2e2", "text": "#991b1b", "accent": "#dc2626" },
+    "orange": { "bg": "#ffedd5", "text": "#9a3412", "accent": "#ea580c" },
+    "teal": { "bg": "#ccfbf1", "text": "#115e59", "accent": "#0d9488" }
+  }
+}

package/src/schemas/themes/tech-dark.json

@@ -0,0 +1,48 @@
+{
+  "schemaVersion": "1",
+  "id": "tech-dark",
+  "name": "Tech Dark",
+  "description": "True black with neon cyan/green accents and monospace titles.",
+  "colors": {
+    "primary": "#00e5ff",
+    "secondary": "#00e676",
+    "background": "#0a0a0a",
+    "backgroundLight": "#1a1a2e",
+    "text": "#e0e0e0",
+    "textMuted": "#9e9e9e",
+    "highlight": "#00e5ff",
+    "warning": "#ff5252"
+  },
+  "typography": {
+    "bodyFont": { "stackId": "ibm-plex-sans" },
+    "titleFont": { "stackId": "jetbrains-mono" },
+    "monoFont": { "stackId": "jetbrains-mono" },
+    "titleWeight": "bold",
+    "titleScale": 0.9,
+    "lineHeight": 1.5
+  },
+  "style": {
+    "textShadow": true,
+    "overlayOpacity": 0.55,
+    "animationSpeed": 0.9,
+    "borderRadius": 2
+  },
+  "renderStyle": {
+    "name": "tech-dark",
+    "defaultTextAnimation": "typewriter",
+    "defaultImageAnimation": "slowZoom",
+    "ambientMotion": true,
+    "defaultTransition": { "type": "dissolve", "duration": 0.4 },
+    "templateHints": {
+      "statHighlight": { "entrance": "dramatic" }
+    }
+  },
+  "colorSchemes": {
+    "blue": { "bg": "#0d1b2a", "text": "#00b0ff", "accent": "#40c4ff" },
+    "green": { "bg": "#0d1b0d", "text": "#00e676", "accent": "#69f0ae" },
+    "purple": { "bg": "#1a0d2e", "text": "#d500f9", "accent": "#ea80fc" },
+    "red": { "bg": "#2e0d0d", "text": "#ff5252", "accent": "#ff8a80" },
+    "orange": { "bg": "#2e1a0d", "text": "#ff9100", "accent": "#ffab40" },
+    "teal": { "bg": "#0d2e2e", "text": "#1de9b6", "accent": "#64ffda" }
+  }
+}

package/src/schemas/themes/warm-earth.json

@@ -0,0 +1,50 @@
+{
+  "schemaVersion": "1",
+  "id": "warm-earth",
+  "name": "Warm Earth",
+  "description": "Natural warm tones with earthy browns and terracotta accents.",
+  "colors": {
+    "primary": "#9c4221",
+    "secondary": "#c05621",
+    "background": "#1c1410",
+    "backgroundLight": "#2d241e",
+    "text": "#faf5f0",
+    "textMuted": "#c4a882",
+    "highlight": "#dd6b20",
+    "warning": "#e53e3e"
+  },
+  "typography": {
+    "bodyFont": { "stackId": "pt-serif" },
+    "titleFont": { "stackId": "pt-serif" },
+    "titleWeight": "bold",
+    "lineHeight": 1.6
+  },
+  "style": {
+    "textShadow": true,
+    "overlayOpacity": 0.5,
+    "animationSpeed": 1.1
+  },
+  "renderStyle": {
+    "name": "warm-earth",
+    "defaultTextAnimation": "fadeIn",
+    "defaultImageAnimation": "panLeft",
+    "ambientMotion": true,
+    "defaultTransition": { "type": "fade", "duration": 0.9 }
+  },
+  "colorSchemes": {
+    "blue": { "bg": "#2a1f14", "text": "#90cdf4", "accent": "#63b3ed" },
+    "green": { "bg": "#1e2a14", "text": "#9ae6b4", "accent": "#68d391" },
+    "purple": { "bg": "#2a142a", "text": "#d6bcfa", "accent": "#b794f4" },
+    "red": { "bg": "#2a1414", "text": "#fc8181", "accent": "#feb2b2" },
+    "orange": { "bg": "#2a1e0a", "text": "#fbd38d", "accent": "#f6ad55" },
+    "teal": { "bg": "#142a28", "text": "#81e6d9", "accent": "#4fd1c5" }
+  },
+  "persistentLayers": {
+    "bottomLayers": [
+      {
+        "template": "gradientBackground",
+        "config": { "type": "gradientBackground", "preset": "earth-tones" }
+      }
+    ]
+  }
+}

package/src/storage/ScopedContentContainer.ts

@@ -0,0 +1,113 @@
+/**
+ * ScopedContentContainer
+ *
+ * Wraps a parent {@link ContentContainer} and prefixes every path with a
+ * fixed subfolder, presenting that subfolder as the root. Useful for
+ * sidecar folders (e.g. `<imagebasename>_files/`) where a component
+ * should be able to read/write/list files relative to its own root
+ * without knowing where it lives in the parent tree.
+ *
+ * Scopes nest: `scopeContainer(scopeContainer(parent, 'a'), 'b')` is
+ * equivalent to `scopeContainer(parent, 'a/b')`.
+ *
+ * `getDocumentPath()` always returns `null` for scoped sidecars — they
+ * are not document roots.
+ */
+
+import type { ContentContainer, ContentEntry } from './ContentContainer.js';
+
+/** Normalize a prefix: strip leading/trailing slashes, ensure no `..` segments. */
+function normalizePrefix(prefix: string): string {
+  let p = prefix.trim();
+  while (p.startsWith('/')) p = p.slice(1);
+  while (p.endsWith('/')) p = p.slice(0, -1);
+  if (p.length === 0) {
+    throw new Error('ScopedContentContainer: prefix must not be empty');
+  }
+  if (p.split('/').some((seg) => seg === '..' || seg === '.')) {
+    throw new Error(
+      `ScopedContentContainer: prefix must not contain '.' or '..' segments: ${prefix}`,
+    );
+  }
+  return p;
+}
+
+/**
+ * A ContentContainer view rooted at a subfolder of a parent container.
+ * All paths passed to / returned from this container are relative to
+ * the subfolder; the parent never sees an unprefixed path.
+ */
+export class ScopedContentContainer implements ContentContainer {
+  private readonly parent: ContentContainer;
+  /** Prefix without trailing slash. */
+  readonly prefix: string;
+  /** Prefix with trailing slash. */
+  private readonly prefixSlash: string;
+
+  constructor(parent: ContentContainer, prefix: string) {
+    this.parent = parent;
+    this.prefix = normalizePrefix(prefix);
+    this.prefixSlash = `${this.prefix}/`;
+  }
+
+  private toParent(path: string): string {
+    let p = path;
+    while (p.startsWith('/')) p = p.slice(1);
+    return this.prefixSlash + p;
+  }
+
+  /** Strip the prefix from a parent-space path. Returns null if the path is outside the scope. */
+  private fromParent(parentPath: string): string | null {
+    if (!parentPath.startsWith(this.prefixSlash)) return null;
+    return parentPath.slice(this.prefixSlash.length);
+  }
+
+  readFile(path: string): Promise<ArrayBuffer | null> {
+    return this.parent.readFile(this.toParent(path));
+  }
+
+  writeFile(path: string, data: ArrayBuffer | Uint8Array, mimeType?: string): Promise<void> {
+    return this.parent.writeFile(this.toParent(path), data, mimeType);
+  }
+
+  removeFile(path: string): Promise<void> {
+    return this.parent.removeFile(this.toParent(path));
+  }
+
+  async listFiles(prefix?: string): Promise<ContentEntry[]> {
+    const parentPrefix = prefix ? this.toParent(prefix) : this.prefixSlash;
+    const entries = await this.parent.listFiles(parentPrefix);
+    const out: ContentEntry[] = [];
+    for (const e of entries) {
+      const local = this.fromParent(e.path);
+      if (local === null) continue;
+      out.push({ path: local, mimeType: e.mimeType, size: e.size });
+    }
+    return out;
+  }
+
+  exists(path: string): Promise<boolean> {
+    return this.parent.exists(this.toParent(path));
+  }
+
+  /** Sidecars are not document roots. */
+  async getDocumentPath(): Promise<string | null> {
+    return null;
+  }
+
+  async readDocument(): Promise<string | null> {
+    return null;
+  }
+
+  async writeDocument(): Promise<void> {
+    throw new Error(
+      'ScopedContentContainer is a sidecar view and does not support writeDocument(). ' +
+        'Write to a specific path with writeFile() instead.',
+    );
+  }
+}
+
+/** Factory: convenience wrapper for `new ScopedContentContainer(parent, prefix)`. */
+export function scopeContainer(parent: ContentContainer, prefix: string): ScopedContentContainer {
+  return new ScopedContentContainer(parent, prefix);
+}

package/src/storage/index.ts

@@ -5,4 +5,5 @@ 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 { ScopedContentContainer, scopeContainer } from './ScopedContentContainer.js';
 export { createMediaProviderFromContainer } from './MediaProviderFromContainer.js';

package/src/versions/DocumentVersionManager.ts

@@ -0,0 +1,70 @@
+/**
+ * Convenience wrapper around the version operations that captures a
+ * {@link ContentContainer} reference and an optional basename override.
+ *
+ * Hosts that prefer a stable handle (e.g. to pass into a UI component)
+ * use this; everything it does is also reachable as a free function.
+ */
+
+import type { ContentContainer } from '../storage/ContentContainer.js';
+import {
+  coalesceVersions,
+  listVersions,
+  pruneVersions,
+  readVersion,
+  revertToVersion,
+  saveVersion,
+} from './operations.js';
+import type {
+  CoalesceOptions,
+  PrunePolicy,
+  RevertOptions,
+  SaveVersionOptions,
+  SaveVersionResult,
+  Version,
+} from './types.js';
+
+export interface DocumentVersionManagerOptions {
+  /**
+   * Override the document basename used in version filenames. Defaults to
+   * the basename of `container.getDocumentPath()` resolved at call time.
+   */
+  basename?: string;
+}
+
+export class DocumentVersionManager {
+  private readonly container: ContentContainer;
+  private readonly basename: string | undefined;
+
+  constructor(container: ContentContainer, options: DocumentVersionManagerOptions = {}) {
+    this.container = container;
+    this.basename = options.basename;
+  }
+
+  saveVersion(options: SaveVersionOptions = {}): Promise<SaveVersionResult> {
+    return saveVersion(this.container, { basename: this.basename, ...options });
+  }
+
+  listVersions(): Promise<Version[]> {
+    return listVersions(this.container, this.basename);
+  }
+
+  readVersion(version: Version | string): Promise<string | null> {
+    return readVersion(this.container, version);
+  }
+
+  revertToVersion(
+    version: Version | string,
+    options?: RevertOptions,
+  ): Promise<{ reverted: boolean; snapshotted: Version | null }> {
+    return revertToVersion(this.container, version, options);
+  }
+
+  pruneVersions(policy: PrunePolicy): Promise<Version[]> {
+    return pruneVersions(this.container, policy, this.basename);
+  }
+
+  coalesceVersions(options?: CoalesceOptions): Promise<Version[]> {
+    return coalesceVersions(this.container, options, this.basename);
+  }
+}

package/src/versions/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Document version history for Squisq.
+ *
+ * Snapshots of the primary markdown document live inside the same
+ * {@link ContentContainer} at `.versions/<basename>.<timestamp>.md`.
+ * Hosts call {@link DocumentVersionManager.saveVersion} (or the
+ * underlying {@link saveVersion}) when they want to stamp a new version;
+ * the editor's auto-save effect calls it on idle. Either way, snapshots
+ * are written only when the document differs from the latest one.
+ *
+ * @example
+ * ```ts
+ * import { DocumentVersionManager } from '@bendyline/squisq/versions';
+ *
+ * const versioning = new DocumentVersionManager(container);
+ * const result = await versioning.saveVersion();
+ * if (result.saved) console.log('Stamped', result.version);
+ *
+ * const history = await versioning.listVersions();
+ * await versioning.revertToVersion(history[0]);
+ * await versioning.pruneVersions({ type: 'keep-last-n', n: 50 });
+ * ```
+ */
+
+export type {
+  Version,
+  SaveVersionOptions,
+  SaveVersionResult,
+  PrunePolicy,
+  RevertOptions,
+  CoalesceOptions,
+} from './types.js';
+
+export {
+  saveVersion,
+  listVersions,
+  readVersion,
+  revertToVersion,
+  pruneVersions,
+  coalesceVersions,
+} from './operations.js';
+
+export {
+  DocumentVersionManager,
+  type DocumentVersionManagerOptions,
+} from './DocumentVersionManager.js';
+
+export {
+  formatVersionTimestamp,
+  parseVersionTimestamp,
+  VERSION_TIMESTAMP_PATTERN,
+} from './timestamp.js';
+
+export { VERSIONS_PREFIX, getDocBasename, buildVersionPath, parseVersionPath } from './paths.js';