pixelweaver 0.1.0

package/src/lib/history/spec-format.ts

@@ -0,0 +1,210 @@
+/**
+ * Spec Export/Import -- serializes the semantic action log to/from a
+ * portable JSON document format.
+ *
+ * The spec format captures the complete sequence of commands needed to
+ * reproduce a pixel art sprite from scratch. This enables:
+ *
+ * - Saving and loading command histories
+ * - Sharing reproducible "recipes" for sprite creation
+ * - Diffing two specs to see what changed
+ * - AI-assisted generation by producing spec documents
+ */
+
+import type { ActionLogEntry } from './action-log.svelte.js';
+
+// --- Types ---
+
+export interface SpecDocument {
+  version: string;
+  canvasWidth: number;
+  canvasHeight: number;
+  commands: SpecCommand[];
+}
+
+export interface SpecCommand {
+  type: string;
+  description: string;
+  params: Record<string, unknown>;
+}
+
+export interface SpecDiff {
+  type: 'added' | 'removed' | 'modified';
+  index: number;
+  command?: SpecCommand;        // for 'added'
+  oldCommand?: SpecCommand;     // for 'removed' / 'modified'
+  newCommand?: SpecCommand;     // for 'modified'
+  changes?: string[];           // list of changed param names (for 'modified')
+}
+
+// --- Current spec format version ---
+const SPEC_VERSION = '1.0.0';
+
+// --- Export ---
+
+/**
+ * Export the action log entries as a spec document.
+ * Only enabled entries are included in the export.
+ */
+export function exportSpec(
+  entries: ActionLogEntry[],
+  canvasWidth: number,
+  canvasHeight: number,
+): SpecDocument {
+  return {
+    version: SPEC_VERSION,
+    canvasWidth,
+    canvasHeight,
+    commands: entries
+      .filter((e) => e.enabled)
+      .map((e) => ({
+        type: e.type,
+        description: e.description,
+        // Strip internal/undo-related params (those starting with underscore)
+        params: filterInternalParams(e.params),
+      })),
+  };
+}
+
+// --- Import ---
+
+/**
+ * Import a spec document into a sequence of commands suitable for replay.
+ * Validates the spec structure and returns the command list.
+ *
+ * Accepts `null`/`undefined` so callers that hand us unvalidated JSON
+ * (the spec-format tests, and history-commands when the dispatcher did
+ * not pre-validate) still hit the structural check instead of crashing.
+ */
+export function importSpec(
+  spec: SpecDocument | null | undefined,
+): { type: string; params: Record<string, unknown> }[] {
+  if (!spec || !Array.isArray(spec.commands)) {
+    throw new Error('Invalid spec document: missing commands array');
+  }
+
+  return spec.commands.map((cmd) => ({
+    type: cmd.type,
+    params: { ...cmd.params },
+  }));
+}
+
+// --- Diff ---
+
+/**
+ * Diff two spec documents and return a list of differences.
+ *
+ * Uses a simple index-based comparison (not LCS/Myers diff) since spec
+ * commands are typically short ordered lists. For each index position:
+ * - If spec1 has a command but spec2 doesn't: 'removed'
+ * - If spec2 has a command but spec1 doesn't: 'added'
+ * - If both have commands but they differ: 'modified'
+ */
+export function diffSpecs(
+  spec1: SpecDocument,
+  spec2: SpecDocument,
+): SpecDiff[] {
+  const diffs: SpecDiff[] = [];
+  const maxLen = Math.max(spec1.commands.length, spec2.commands.length);
+
+  for (let i = 0; i < maxLen; i++) {
+    const cmd1 = spec1.commands[i];
+    const cmd2 = spec2.commands[i];
+
+    if (!cmd1 && cmd2) {
+      // Command added in spec2
+      diffs.push({
+        type: 'added',
+        index: i,
+        command: cmd2,
+      });
+    } else if (cmd1 && !cmd2) {
+      // Command removed in spec2
+      diffs.push({
+        type: 'removed',
+        index: i,
+        oldCommand: cmd1,
+      });
+    } else if (cmd1 && cmd2) {
+      // Both exist -- check if they differ
+      const changes = findParamChanges(cmd1, cmd2);
+      if (cmd1.type !== cmd2.type || changes.length > 0) {
+        diffs.push({
+          type: 'modified',
+          index: i,
+          oldCommand: cmd1,
+          newCommand: cmd2,
+          changes: cmd1.type !== cmd2.type
+            ? ['type', ...changes]
+            : changes,
+        });
+      }
+    }
+  }
+
+  return diffs;
+}
+
+// --- Internal helpers ---
+
+/**
+ * Filter out internal params (underscore-prefixed) that are used by the
+ * undo system but should not be part of the exported spec.
+ */
+function filterInternalParams(params: Record<string, unknown>): Record<string, unknown> {
+  const filtered: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (!key.startsWith('_')) {
+      filtered[key] = value;
+    }
+  }
+  return filtered;
+}
+
+/**
+ * Compare two spec commands' params and return the list of param names
+ * that differ between them.
+ */
+function findParamChanges(cmd1: SpecCommand, cmd2: SpecCommand): string[] {
+  const changes: string[] = [];
+  const allKeys = new Set([
+    ...Object.keys(cmd1.params),
+    ...Object.keys(cmd2.params),
+  ]);
+
+  for (const key of allKeys) {
+    const v1 = cmd1.params[key];
+    const v2 = cmd2.params[key];
+    if (!deepEqual(v1, v2)) {
+      changes.push(key);
+    }
+  }
+
+  return changes;
+}
+
+/**
+ * Simple deep equality check for JSON-serializable values.
+ * Sufficient for command params which are plain objects/arrays/primitives.
+ */
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== typeof b) return false;
+
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    return a.every((val, idx) => deepEqual(val, b[idx]));
+  }
+
+  if (typeof a === 'object' && typeof b === 'object') {
+    const objA = a as Record<string, unknown>;
+    const objB = b as Record<string, unknown>;
+    const keysA = Object.keys(objA);
+    const keysB = Object.keys(objB);
+    if (keysA.length !== keysB.length) return false;
+    return keysA.every((key) => deepEqual(objA[key], objB[key]));
+  }
+
+  return false;
+}

package/src/lib/iso/SeamCheckerPanel.svelte

@@ -0,0 +1,251 @@
+<script lang="ts">
+  /**
+   * SeamCheckerPanel -- dockable right-sidebar panel that inspects the
+   * current render buffer for tile-edge mismatches.
+   *
+   * Calls checkSeams() from seam-checker.ts whenever the composited render
+   * buffer changes, and displays the results as a scrollable list with
+   * color swatches for each mismatched pixel pair.
+   */
+
+  import { checkSeams, type SeamIssue } from './seam-checker.js';
+  import { getRenderBuffer } from '../canvas/render-state.svelte.js';
+  import RefreshCwIcon from '~icons/lucide/refresh-cw';
+
+  // --- Seam analysis state ---
+
+  /** Manually incremented to force a re-check even when the buffer ref is the same. */
+  let refreshTick = $state(0);
+
+  /** The list of detected seam issues, derived from the current render buffer. */
+  let issues = $derived.by((): SeamIssue[] => {
+    // Read refreshTick so manual refreshes trigger a re-derive.
+    void refreshTick;
+    const buffer = getRenderBuffer();
+    if (!buffer) return [];
+    return checkSeams(buffer);
+  });
+
+  /** Human-readable label for edge names (includes the opposite edge for context). */
+  function edgeLabel(edge: SeamIssue['edge']): string {
+    switch (edge) {
+      case 'top': return 'Top / Bottom';
+      case 'left': return 'Left / Right';
+      // checkSeams only emits 'top' and 'left', but handle others defensively.
+      case 'bottom': return 'Bottom / Top';
+      case 'right': return 'Right / Left';
+    }
+  }
+
+  function handleRefresh(): void {
+    refreshTick++;
+  }
+</script>
+
+<div class="seam-panel">
+  <!-- Header -->
+  <div class="seam-header">
+    <span class="seam-title">Seam Checker</span>
+    <div class="seam-actions">
+      <button
+        class="action-btn"
+        title="Refresh"
+        aria-label="Refresh seam check"
+        onclick={handleRefresh}
+      ><RefreshCwIcon /></button>
+    </div>
+  </div>
+
+  <!-- Results -->
+  <div class="seam-body">
+    {#if !getRenderBuffer()}
+      <p class="seam-empty">No canvas data available.</p>
+    {:else if issues.length === 0}
+      <p class="seam-success">No seam issues found.</p>
+    {:else}
+      <p class="seam-summary">{issues.length} mismatch{issues.length === 1 ? '' : 'es'} detected</p>
+
+      <ul class="issue-list">
+        {#each issues as issue (`${issue.edge}-${String(issue.position)}`)}
+          <li class="issue-row">
+            <span class="issue-edge">{edgeLabel(issue.edge)}</span>
+            <span class="issue-pos">px {issue.position}</span>
+            <span class="swatch-pair">
+              <span
+                class="swatch"
+                style:background-color={issue.color1}
+                title={issue.color1}
+              ></span>
+              <span class="swatch-sep"></span>
+              <span
+                class="swatch"
+                style:background-color={issue.color2}
+                title={issue.color2}
+              ></span>
+            </span>
+          </li>
+        {/each}
+      </ul>
+    {/if}
+  </div>
+</div>
+
+<style>
+  .seam-panel {
+    display: flex;
+    flex-direction: column;
+    width: 100%;
+    height: 100%;
+    background: var(--bg-panel);
+    color: var(--text-primary);
+    font-size: var(--text-base);
+    user-select: none;
+  }
+
+  .seam-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 6px var(--space-3);
+    border-bottom: 1px solid var(--border);
+    background: var(--bg-toolbar);
+    flex-shrink: 0;
+  }
+
+  .seam-title {
+    font-weight: 600;
+    font-size: var(--text-sm);
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+    color: var(--text-secondary);
+  }
+
+  .seam-actions {
+    display: flex;
+    gap: var(--space-1);
+  }
+
+  .action-btn {
+    background: none;
+    border: 1px solid transparent;
+    border-radius: var(--radius-sm);
+    color: var(--text-secondary);
+    cursor: pointer;
+    width: 24px;
+    height: 24px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: var(--text-xl);
+    padding: 0;
+    line-height: 1;
+  }
+
+  .action-btn:hover {
+    background: var(--bg-primary);
+    color: var(--text-primary);
+    border-color: var(--border);
+  }
+
+  .action-btn :global(svg) {
+    width: 14px;
+    height: 14px;
+  }
+
+  /* Scrollable body */
+  .seam-body {
+    flex: 1;
+    overflow-y: auto;
+    overflow-x: hidden;
+    padding: var(--space-2) var(--space-3);
+  }
+
+  .seam-empty,
+  .seam-success {
+    color: var(--text-secondary);
+    font-size: var(--text-sm);
+    margin: 0;
+    padding: var(--space-2) 0;
+  }
+
+  .seam-success {
+    color: var(--accent);
+  }
+
+  .seam-summary {
+    margin: 0 0 var(--space-2) 0;
+    font-size: var(--text-sm);
+    color: var(--text-secondary);
+  }
+
+  /* Issue list */
+  .issue-list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+  }
+
+  .issue-row {
+    display: flex;
+    align-items: center;
+    gap: var(--space-2);
+    padding: 3px var(--space-2);
+    border-radius: var(--radius-sm);
+    font-size: var(--text-sm);
+    transition: background var(--transition-fast);
+  }
+
+  .issue-row:hover {
+    background: rgba(255, 255, 255, 0.04);
+  }
+
+  :global([data-theme="light"]) .issue-row:hover {
+    background: rgba(0, 0, 0, 0.04);
+  }
+
+  .issue-edge {
+    flex-shrink: 0;
+    font-weight: 500;
+    min-width: 72px;
+  }
+
+  .issue-pos {
+    color: var(--text-secondary);
+    flex-shrink: 0;
+    min-width: 36px;
+  }
+
+  /* Color swatches */
+  .swatch-pair {
+    display: flex;
+    align-items: center;
+    gap: 3px;
+    margin-left: auto;
+    flex-shrink: 0;
+  }
+
+  .swatch {
+    width: 14px;
+    height: 14px;
+    border: 1px solid var(--border);
+    border-radius: 2px;
+    /* Checkerboard to reveal alpha */
+    background-image:
+      linear-gradient(45deg, #808080 25%, transparent 25%),
+      linear-gradient(-45deg, #808080 25%, transparent 25%),
+      linear-gradient(45deg, transparent 75%, #808080 75%),
+      linear-gradient(-45deg, transparent 75%, #808080 75%);
+    background-size: 6px 6px;
+    background-position: 0 0, 0 3px, 3px -3px, -3px 0;
+  }
+
+  .swatch-sep {
+    width: 4px;
+    height: 1px;
+    background: var(--text-secondary);
+    flex-shrink: 0;
+  }
+</style>

package/src/lib/iso/iso-math.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect } from 'vitest';
+import { screenToIso, isoToScreen, isoDepthCompare } from './iso-math.js';
+
+describe('iso-math', () => {
+  const TW = 64;  // tile width
+  const TH = 32;  // tile height (standard 2:1 isometric)
+
+  describe('screenToIso / isoToScreen roundtrip', () => {
+    it('should roundtrip the origin tile (0, 0)', () => {
+      const screen = isoToScreen(0, 0, TW, TH);
+      const iso = screenToIso(screen.x, screen.y, TW, TH);
+      expect(iso.col).toBeCloseTo(0, 10);
+      expect(iso.row).toBeCloseTo(0, 10);
+    });
+
+    it('should roundtrip an arbitrary tile (3, 5)', () => {
+      const screen = isoToScreen(3, 5, TW, TH);
+      const iso = screenToIso(screen.x, screen.y, TW, TH);
+      expect(iso.col).toBeCloseTo(3, 10);
+      expect(iso.row).toBeCloseTo(5, 10);
+    });
+
+    it('should roundtrip with non-standard tile sizes', () => {
+      const tw = 48;
+      const th = 24;
+      const screen = isoToScreen(7, 2, tw, th);
+      const iso = screenToIso(screen.x, screen.y, tw, th);
+      expect(iso.col).toBeCloseTo(7, 10);
+      expect(iso.row).toBeCloseTo(2, 10);
+    });
+
+    it('should roundtrip from screen to iso and back', () => {
+      // Start from screen coords and verify roundtrip
+      const iso = screenToIso(100, 50, TW, TH);
+      const screen = isoToScreen(iso.col, iso.row, TW, TH);
+      expect(screen.x).toBeCloseTo(100, 10);
+      expect(screen.y).toBeCloseTo(50, 10);
+    });
+  });
+
+  describe('isoToScreen', () => {
+    it('should return (0, 0) for tile (0, 0)', () => {
+      const { x, y } = isoToScreen(0, 0, TW, TH);
+      expect(x).toBe(0);
+      expect(y).toBe(0);
+    });
+
+    it('should offset correctly for tile (1, 0) -- pure column shift', () => {
+      const { x, y } = isoToScreen(1, 0, TW, TH);
+      // col=1, row=0: x = (1-0)*32 = 32, y = (1+0)*16 = 16
+      expect(x).toBe(TW / 2);
+      expect(y).toBe(TH / 2);
+    });
+  });
+
+  describe('isoDepthCompare', () => {
+    it('should sort objects with smaller col+row sum first (farther from camera)', () => {
+      const far = { col: 0, row: 0, height: 0 };
+      const near = { col: 3, row: 2, height: 0 };
+      expect(isoDepthCompare(far, near)).toBeLessThan(0);
+      expect(isoDepthCompare(near, far)).toBeGreaterThan(0);
+    });
+
+    it('should sort lower height first when col+row sums are equal', () => {
+      const low = { col: 2, row: 3, height: 0 };
+      const high = { col: 2, row: 3, height: 2 };
+      expect(isoDepthCompare(low, high)).toBeLessThan(0);
+      expect(isoDepthCompare(high, low)).toBeGreaterThan(0);
+    });
+
+    it('should return 0 for identical positions and heights', () => {
+      const a = { col: 1, row: 1, height: 1 };
+      const b = { col: 1, row: 1, height: 1 };
+      expect(isoDepthCompare(a, b)).toBe(0);
+    });
+  });
+});

package/src/lib/iso/iso-math.ts

@@ -0,0 +1,77 @@
+/**
+ * Isometric Math -- coordinate conversions and depth sorting for isometric grids.
+ *
+ * Uses the standard 2:1 isometric projection where tile width is twice tile height.
+ * Screen origin (0,0) is the top-center of the grid; columns go right-down,
+ * rows go left-down.
+ */
+
+/** Result of converting screen coordinates to isometric tile coordinates. */
+export interface IsoCoord {
+  col: number;
+  row: number;
+}
+
+/** Result of converting isometric tile coordinates to screen position. */
+export interface ScreenCoord {
+  x: number;
+  y: number;
+}
+
+/** Object with isometric position and elevation, used for depth sorting. */
+export interface IsoObject {
+  col: number;
+  row: number;
+  height: number;
+}
+
+/**
+ * Convert screen coordinates to isometric tile coordinates.
+ *
+ * Returns fractional col/row -- caller should Math.floor() for tile lookup.
+ * The formulas invert the standard isometric projection matrix:
+ *   screenX = (col - row) * (tileWidth / 2)
+ *   screenY = (col + row) * (tileHeight / 2)
+ */
+export function screenToIso(
+  screenX: number,
+  screenY: number,
+  tileWidth: number,
+  tileHeight: number,
+): IsoCoord {
+  const halfW = tileWidth / 2;
+  const halfH = tileHeight / 2;
+  const col = (screenX / halfW + screenY / halfH) / 2;
+  const row = (screenY / halfH - screenX / halfW) / 2;
+  return { col, row };
+}
+
+/**
+ * Convert isometric tile coordinates to screen position.
+ *
+ * Returns the top-center anchor point of the tile diamond.
+ */
+export function isoToScreen(
+  col: number,
+  row: number,
+  tileWidth: number,
+  tileHeight: number,
+): ScreenCoord {
+  const x = (col - row) * (tileWidth / 2);
+  const y = (col + row) * (tileHeight / 2);
+  return { x, y };
+}
+
+/**
+ * Depth sort comparator for isometric objects.
+ *
+ * Objects with smaller (col + row) are farther from the camera and should
+ * be rendered first. When sums are equal, lower height renders first.
+ * Returns negative if `a` should render before `b`.
+ */
+export function isoDepthCompare(a: IsoObject, b: IsoObject): number {
+  const sumA = a.col + a.row;
+  const sumB = b.col + b.row;
+  if (sumA !== sumB) return sumA - sumB;
+  return a.height - b.height;
+}

package/src/lib/iso/seam-checker-panel-plugin.ts

@@ -0,0 +1,25 @@
+/**
+ * Seam Checker Panel Plugin -- registers SeamCheckerPanel as a dockable
+ * panel in the right sidebar. Shows tile-edge mismatches for the current
+ * composited render buffer.
+ *
+ * Discovered by bootstrap via the `*-plugin.ts` glob.
+ */
+
+import type { PluginModule } from '../core/plugin-loader.js';
+import SeamCheckerPanel from './SeamCheckerPanel.svelte';
+
+export const seamCheckerPanelPlugin: PluginModule = {
+  name: 'ui/seam-checker-panel',
+  version: '1.0.0',
+  dependencies: [],
+  register(api) {
+    api.addPanel('seam-checker', {
+      title: 'Seam Checker',
+      component: SeamCheckerPanel,
+      position: 'right',
+      minWidth: 160,
+      maxWidth: 300,
+    });
+  },
+};