pixelweaver 0.1.0

package/src/lib/save/directory-format.ts

@@ -0,0 +1,42 @@
+/**
+ * Directory Format Adapter -- converts ProjectSnapshot to/from a flat file map.
+ *
+ * Produces a Record<string, Uint8Array> where keys are relative paths
+ * (e.g. "project.json", "canvases/main/frames/0/layer-abc.raw") and
+ * values are file contents. The storage backend handles writing these
+ * to the actual filesystem (desktop) or packaging them (browser download as ZIP).
+ */
+
+import type { ProjectSnapshot } from './project-snapshot.js';
+import { SNAPSHOT_VERSION } from './project-snapshot.js';
+
+/** A flat map of relative-path -> file-contents. */
+export type FileMap = Record<string, Uint8Array>;
+
+/** Convert a ProjectSnapshot into a directory file map. */
+export function snapshotToFileMap(snapshot: ProjectSnapshot): FileMap {
+  // For now the entire snapshot is stored as a single JSON file.
+  // Future iterations will split pixel data into per-layer PNG files
+  // under canvases/<name>/frames/<index>/layer-<id>.png.
+  const json = JSON.stringify(snapshot, null, 2);
+  const encoder = new TextEncoder();
+  return {
+    'project.json': encoder.encode(json),
+  };
+}
+
+/** Convert a directory file map back into a ProjectSnapshot. */
+export function fileMapToSnapshot(files: FileMap): ProjectSnapshot {
+  const projectJson = files['project.json'];
+  if (!projectJson) throw new Error('Invalid project directory: missing project.json');
+
+  const decoder = new TextDecoder();
+  const json = decoder.decode(projectJson);
+  const snapshot = JSON.parse(json) as ProjectSnapshot;
+
+  if (snapshot.version !== SNAPSHOT_VERSION) {
+    console.warn(`Snapshot version mismatch: expected ${String(SNAPSHOT_VERSION)}, got ${String(snapshot.version)}`);
+  }
+
+  return snapshot;
+}

package/src/lib/save/project-snapshot.ts

@@ -0,0 +1,139 @@
+/**
+ * Project Snapshot -- format-agnostic project serialization.
+ *
+ * Gathers all project state into a single ProjectSnapshot object,
+ * and restores it from one. Format adapters (ZIP, directory) convert
+ * between ProjectSnapshot and on-disk representation.
+ */
+
+// Canvas must be deserialized first -- layers and frames depend on dimensions.
+import {
+  serializeCanvasState,
+  deserializeCanvasState,
+} from '../canvas/canvas-state.svelte.js';
+
+// Layer tree (structure, names, visibility, blend modes).
+import {
+  serialize as serializeLayers,
+  deserialize as deserializeLayers,
+} from '../layers/layer-tree.svelte.js';
+
+// Per-frame pixel data, FPS, origin.
+import {
+  serialize as serializeFrames,
+  deserialize as deserializeFrames,
+} from '../animation/frame-model.svelte.js';
+
+// Named frame ranges (animation tags / sub-clips).
+import {
+  serialize as serializeFrameTags,
+  deserialize as deserializeFrameTags,
+} from '../animation/frame-tags.svelte.js';
+
+// Variant presets (palette swap overrides per layer group).
+import {
+  serialize as serializeVariants,
+  deserialize as deserializeVariants,
+} from '../variants/variant-state.svelte.js';
+
+// Level editor map state (tile grid, entities, collision shapes).
+import { mapState } from '../leveleditor/map-state.svelte.js';
+
+// Foreground/background colors and recent-color history.
+import {
+  serializeColorState,
+  deserializeColorState,
+} from '../color/color-state.svelte.js';
+
+// Project-level palette and lock mode.
+import {
+  serialize as serializePalette,
+  deserialize as deserializePalette,
+} from '../color/palette-state.svelte.js';
+
+// Reset undo/redo stacks when loading a different project.
+import { clearHistory } from '../core/dispatcher.js';
+
+// Clear stale action-log entries so the panel doesn't show previous-session commands.
+import { actionLog } from '../history/action-log.svelte.js';
+
+/** Version of the snapshot format for future migration. */
+export const SNAPSHOT_VERSION = 1;
+
+/** Complete serialized project state. */
+export interface ProjectSnapshot {
+  /** Format version -- bump when the shape changes. */
+  version: number;
+  /** Human-readable project name (displayed in title bar, file pickers, etc.). */
+  name: string;
+  /** Canvas pixel dimensions. */
+  canvas: { width: number; height: number };
+  /** Layer tree structure, blend modes, visibility, active layer. */
+  layers: unknown;
+  /** Animation frames with per-layer pixel data, FPS, origin. */
+  frames: unknown;
+  /** Named frame ranges / animation sub-clips. */
+  frameTags: unknown;
+  /** Variant presets (per-group palette swap overrides). */
+  variants: unknown;
+  /** Level editor map: tile grid, entities, collision shapes. */
+  map: unknown;
+  /** Foreground/background colors and recent-color history. */
+  colors: unknown;
+  /** Project-level palette and lock mode. */
+  palette: unknown;
+}
+
+/** Collect all project state into a snapshot. */
+export function gatherSnapshot(projectName: string): ProjectSnapshot {
+  return {
+    version: SNAPSHOT_VERSION,
+    name: projectName,
+    canvas: serializeCanvasState(),
+    layers: serializeLayers(),
+    frames: serializeFrames(),
+    frameTags: serializeFrameTags(),
+    variants: serializeVariants(),
+    map: mapState.serialize(),
+    colors: serializeColorState(),
+    palette: serializePalette(),
+  };
+}
+
+/**
+ * Apply a snapshot to restore project state.
+ *
+ * Ordering matters: canvas dimensions are restored first because layer
+ * and frame deserialization may reference canvas size. Undo/redo history
+ * is cleared last so that stale commands from the previous project cannot
+ * corrupt the freshly loaded state.
+ */
+export function applySnapshot(snapshot: ProjectSnapshot): void {
+  // 1. Canvas dimensions first -- layers and frames depend on these.
+  deserializeCanvasState(snapshot.canvas as { width: number; height: number });
+
+  // 2. Layer structure before frames (frames reference layer IDs).
+  deserializeLayers(snapshot.layers as Parameters<typeof deserializeLayers>[0]);
+
+  // 3. Frame pixel data, FPS, origin.
+  deserializeFrames(snapshot.frames as Parameters<typeof deserializeFrames>[0]);
+
+  // 4. Frame tags (depend on frame indices being settled).
+  deserializeFrameTags(snapshot.frameTags as Parameters<typeof deserializeFrameTags>[0]);
+
+  // 5. Variant presets (reference layer group IDs, so layers must exist).
+  deserializeVariants(snapshot.variants as Parameters<typeof deserializeVariants>[0]);
+
+  // 6. Level editor map state.
+  mapState.deserialize(snapshot.map as Parameters<typeof mapState.deserialize>[0]);
+
+  // 7. Color state (independent, but restored after canvas for consistency).
+  deserializeColorState(snapshot.colors as Parameters<typeof deserializeColorState>[0]);
+
+  // 8. Palette state.
+  deserializePalette(snapshot.palette as Parameters<typeof deserializePalette>[0]);
+
+  // 9. Clear undo/redo so stale commands from the previous project are gone.
+  clearHistory();
+  actionLog.clearAll();
+}

package/src/lib/save/recent-projects.ts

@@ -0,0 +1,56 @@
+/**
+ * Recent Projects -- persists a list of recently opened/saved projects
+ * in localStorage so the New Project dialog can offer quick access.
+ */
+
+const STORAGE_KEY = 'pixelweaver:recent-projects';
+const MAX_ENTRIES = 10;
+
+export interface RecentProject {
+  /** Display name of the project. */
+  name: string;
+  /** File path (desktop) or file name (browser). */
+  path: string;
+  /** Unix timestamp (ms) of last save/open. */
+  timestamp: number;
+  /** Human-readable dimensions, e.g. "32x32". */
+  dimensions: string;
+}
+
+/** Read recent projects from localStorage, most recent first. */
+export function getRecentProjects(): RecentProject[] {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return [];
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed as RecentProject[];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Add or update a project in the recent list.
+ * If a project with the same path already exists, it is moved to the top
+ * and its metadata is updated. The list is capped at MAX_ENTRIES.
+ */
+export function addRecentProject(entry: RecentProject): void {
+  const list = getRecentProjects().filter((p) => p.path !== entry.path);
+  list.unshift(entry);
+  if (list.length > MAX_ENTRIES) list.length = MAX_ENTRIES;
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(list));
+  } catch {
+    // Storage full or unavailable
+  }
+}
+
+/** Remove all recent projects from localStorage. */
+export function clearRecentProjects(): void {
+  try {
+    localStorage.removeItem(STORAGE_KEY);
+  } catch {
+    // Ignore
+  }
+}

package/src/lib/save/save-state.svelte.ts

@@ -0,0 +1,35 @@
+/**
+ * Save State -- tracks the current project's save path and format.
+ *
+ * When a project is saved for the first time, savePath and saveFormat
+ * are set. Subsequent Ctrl+S re-saves to the same location silently.
+ * Ctrl+Shift+S re-opens the Save As dialog.
+ */
+
+/** 'zip' = .pwv file, 'directory' = folder on disk */
+export type SaveFormat = 'zip' | 'directory';
+
+let savePath = $state<string | null>(null);
+let saveFormat = $state<SaveFormat | null>(null);
+let projectName = $state('Untitled');
+
+export const saveState = {
+  get savePath() { return savePath; },
+  set savePath(v: string | null) { savePath = v; },
+
+  get saveFormat() { return saveFormat; },
+  set saveFormat(v: SaveFormat | null) { saveFormat = v; },
+
+  get projectName() { return projectName; },
+  set projectName(v: string) { projectName = v; },
+
+  /** Reset save state (e.g. when creating a new project). */
+  reset() {
+    savePath = null;
+    saveFormat = null;
+    projectName = 'Untitled';
+  },
+
+  /** Whether the project has been saved at least once. */
+  get hasSavePath() { return savePath !== null; },
+};

package/src/lib/save/storage.ts

@@ -0,0 +1,167 @@
+/**
+ * Storage -- platform-adaptive save/load facade.
+ *
+ * Detects whether the app runs inside a pywebview desktop window or a
+ * plain browser. Desktop uses native file dialogs and filesystem access
+ * via the pywebview bridge; browser falls back to download + file input.
+ */
+
+import { packZip, unpackZip } from './zip-format.js';
+import { snapshotToFileMap } from './directory-format.js';
+import type { ProjectSnapshot } from './project-snapshot.js';
+import type { SaveFormat } from './save-state.svelte.js';
+
+// --- Base64 helpers ---
+
+function uint8ArrayToBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]!);
+  }
+  return btoa(binary);
+}
+
+function base64ToUint8Array(b64: string): Uint8Array {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+// --- Desktop detection ---
+
+/** Check if running inside a pywebview desktop window. */
+function isDesktop(): boolean {
+  return !!window.pywebview;
+}
+
+// --- Save ---
+
+export interface SaveResult {
+  path: string;
+  format: SaveFormat;
+}
+
+/**
+ * Show a Save As dialog and write the project.
+ * Returns the chosen path+format, or null if cancelled.
+ */
+export async function saveAs(snapshot: ProjectSnapshot): Promise<SaveResult | null> {
+  if (isDesktop()) {
+    return saveAsDesktop(snapshot);
+  }
+  return saveAsBrowser(snapshot);
+}
+
+/**
+ * Save silently to a known path+format (re-save).
+ */
+export async function saveToPath(snapshot: ProjectSnapshot, path: string, format: SaveFormat): Promise<void> {
+  if (isDesktop()) {
+    await writeDesktop(snapshot, path, format);
+  } else {
+    // Browser can't re-save to a path -- fall back to download
+    await downloadBrowser(snapshot, format, path);
+  }
+}
+
+/**
+ * Show an Open dialog and read a project file.
+ * Returns the snapshot + metadata, or null if cancelled.
+ */
+export async function openProject(): Promise<{ snapshot: ProjectSnapshot; path: string; format: SaveFormat } | null> {
+  if (isDesktop()) {
+    return openDesktop();
+  }
+  return openBrowser();
+}
+
+// --- Desktop (pywebview) implementations ---
+
+async function saveAsDesktop(snapshot: ProjectSnapshot): Promise<SaveResult | null> {
+  const blob = await packZip(snapshot);
+  const buffer = new Uint8Array(await blob.arrayBuffer());
+  const b64 = uint8ArrayToBase64(buffer);
+  const fileName = `${snapshot.name || 'Untitled'}.pwv`;
+
+  const path = await window.pywebview!.api.save_file(
+    b64, fileName, 'PixelWeaver Project', ['pwv'],
+  );
+  if (!path) return null;
+
+  return { path, format: 'zip' };
+}
+
+async function writeDesktop(snapshot: ProjectSnapshot, path: string, format: SaveFormat): Promise<void> {
+  if (format === 'zip') {
+    const blob = await packZip(snapshot);
+    const buffer = new Uint8Array(await blob.arrayBuffer());
+    const b64 = uint8ArrayToBase64(buffer);
+    await window.pywebview!.api.write_file(path, b64);
+  } else {
+    const fileMap = snapshotToFileMap(snapshot);
+    const files = Object.entries(fileMap).map(([name, data]) => ({
+      name,
+      data: uint8ArrayToBase64(data),
+    }));
+    await window.pywebview!.api.write_files_to_directory(path, files);
+  }
+}
+
+async function openDesktop(): Promise<{ snapshot: ProjectSnapshot; path: string; format: SaveFormat } | null> {
+  const result = await window.pywebview!.api.open_file(
+    'PixelWeaver Project', ['pwv'],
+  );
+  if (!result) return null;
+
+  const bytes = base64ToUint8Array(result.data);
+  const blob = new Blob([bytes]);
+  const snapshot = await unpackZip(blob);
+  return { snapshot, path: result.path, format: 'zip' };
+}
+
+// --- Browser implementations ---
+
+async function saveAsBrowser(snapshot: ProjectSnapshot): Promise<SaveResult | null> {
+  // Browser: always download as ZIP
+  const fileName = `${snapshot.name || 'Untitled'}.pwv`;
+  await downloadBrowser(snapshot, 'zip', fileName);
+  return { path: fileName, format: 'zip' };
+}
+
+async function downloadBrowser(snapshot: ProjectSnapshot, _format: SaveFormat, fileName: string): Promise<void> {
+  // In the browser, directory format is not possible -- always pack as ZIP
+  const blob = await packZip(snapshot);
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = fileName.endsWith('.pwv') ? fileName : `${fileName}.pwv`;
+  document.body.appendChild(a);
+  a.click();
+  document.body.removeChild(a);
+  URL.revokeObjectURL(url);
+}
+
+async function openBrowser(): Promise<{ snapshot: ProjectSnapshot; path: string; format: SaveFormat } | null> {
+  const input = document.createElement('input');
+  input.type = 'file';
+  input.accept = '.pwv';
+
+  const file = await new Promise<File | null>((resolve) => {
+    input.onchange = () => { resolve(input.files?.[0] ?? null); };
+    const onFocus = () => {
+      setTimeout(() => {
+        if (!input.files?.length) resolve(null);
+        window.removeEventListener('focus', onFocus);
+      }, 300);
+    };
+    window.addEventListener('focus', onFocus);
+    input.click();
+  });
+
+  if (!file) return null;
+  const snapshot = await unpackZip(file);
+  return { snapshot, path: file.name, format: 'zip' };
+}

package/src/lib/save/zip-format.ts

@@ -0,0 +1,45 @@
+/**
+ * ZIP Format Adapter -- reads/writes ProjectSnapshot as a .pwv ZIP archive.
+ *
+ * The .pwv file is a ZIP containing a single project.json with the
+ * full ProjectSnapshot. ZIP compression handles the bulk of pixel data
+ * (RGBA arrays compress well). Future versions may split pixel data
+ * into separate PNG files within the archive for efficiency.
+ */
+
+import type { ProjectSnapshot } from './project-snapshot.js';
+import { SNAPSHOT_VERSION } from './project-snapshot.js';
+
+/** Lazy-load fflate to keep it out of the initial bundle. */
+async function getfflate() {
+  return await import('fflate');
+}
+
+/** Pack a ProjectSnapshot into a .pwv ZIP blob. */
+export async function packZip(snapshot: ProjectSnapshot): Promise<Blob> {
+  const { zipSync, strToU8 } = await getfflate();
+  const json = JSON.stringify(snapshot);
+  const data = strToU8(json);
+  const zipped = zipSync({ 'project.json': data }, { level: 6 });
+  // Copy into a fresh ArrayBuffer to satisfy strict BlobPart typing
+  // (fflate returns Uint8Array<ArrayBufferLike> which may be SharedArrayBuffer)
+  const buf = new ArrayBuffer(zipped.byteLength);
+  new Uint8Array(buf).set(zipped);
+  return new Blob([buf], { type: 'application/zip' });
+}
+
+/** Unpack a .pwv ZIP blob into a ProjectSnapshot. */
+export async function unpackZip(blob: Blob): Promise<ProjectSnapshot> {
+  const { unzipSync, strFromU8 } = await getfflate();
+  const buffer = new Uint8Array(await blob.arrayBuffer());
+  const files = unzipSync(buffer);
+  const projectJson = files['project.json'];
+  if (!projectJson) throw new Error('Invalid .pwv file: missing project.json');
+  const json = strFromU8(projectJson);
+  const snapshot = JSON.parse(json) as ProjectSnapshot;
+  if (snapshot.version !== SNAPSHOT_VERSION) {
+    // Future: add migration logic here
+    console.warn(`Snapshot version mismatch: expected ${String(SNAPSHOT_VERSION)}, got ${String(snapshot.version)}`);
+  }
+  return snapshot;
+}