refactor: migrate project storage from IndexedDB to OPFS with folder-based structure

- Replace monolithic KGStorage with KGProjectStorage (OPFS) and KGConfigStorage (IndexedDB)
- Each project stored as folder: project.json + meta.json + media/
- Add KGConfigUpgrader with V1 upgrader to auto-migrate existing IndexedDB projects to OPFS
- Request persistent storage via navigator.storage.persist() to prevent browser eviction
- Show loading spinner during one-time migration
- Enforce safe project name characters (letters, numbers, space, hyphen, underscore, period, parens)
- Export projects as .kgstudio zip bundles instead of raw JSON
- Import supports .kgstudio bundles (with meta.json validation) and legacy JSON files
- Auto-deduplicate project names on import with (1), (2), etc. suffix
- Add OPFS shell debugger (pwd, ls, cd, cat, dl) accessible via KGDebugger.opfs()
- Add ESLint semi rule for consistent semicolons
- Delete KGStorage.ts — all logic absorbed by new storage classes
- Add jszip dependency for zip export/import

src/util/projectNameUtil.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest';
+import { isValidProjectName, sanitizeProjectName } from './projectNameUtil';
+
+describe('isValidProjectName', () => {
+  it('accepts simple alphanumeric names', () => {
+    expect(isValidProjectName('MyProject')).toBe(true);
+    expect(isValidProjectName('project123')).toBe(true);
+  });
+
+  it('accepts names with allowed special characters', () => {
+    expect(isValidProjectName('My Song')).toBe(true);
+    expect(isValidProjectName('song-v2')).toBe(true);
+    expect(isValidProjectName('song_final')).toBe(true);
+    expect(isValidProjectName('song.backup')).toBe(true);
+    expect(isValidProjectName('Song (v2)')).toBe(true);
+  });
+
+  it('rejects empty or whitespace-only names', () => {
+    expect(isValidProjectName('')).toBe(false);
+    expect(isValidProjectName('   ')).toBe(false);
+  });
+
+  it('rejects names starting with a dot', () => {
+    expect(isValidProjectName('.hidden')).toBe(false);
+  });
+
+  it('rejects names with disallowed characters', () => {
+    expect(isValidProjectName('my/song')).toBe(false);
+    expect(isValidProjectName('my\\song')).toBe(false);
+    expect(isValidProjectName('my:song')).toBe(false);
+    expect(isValidProjectName('my*song')).toBe(false);
+    expect(isValidProjectName('my?song')).toBe(false);
+    expect(isValidProjectName('my"song')).toBe(false);
+    expect(isValidProjectName('my<song')).toBe(false);
+    expect(isValidProjectName('my>song')).toBe(false);
+    expect(isValidProjectName('my|song')).toBe(false);
+  });
+
+  it('accepts accented characters', () => {
+    expect(isValidProjectName('Café Waltz')).toBe(true);
+    expect(isValidProjectName('Ñoño')).toBe(true);
+  });
+});
+
+describe('sanitizeProjectName', () => {
+  it('returns valid names unchanged', () => {
+    expect(sanitizeProjectName('My Song')).toBe('My Song');
+    expect(sanitizeProjectName('project-123')).toBe('project-123');
+  });
+
+  it('replaces disallowed characters with underscores', () => {
+    expect(sanitizeProjectName('my/song')).toBe('my_song');
+    expect(sanitizeProjectName('my:song')).toBe('my_song');
+    expect(sanitizeProjectName('a*b?c')).toBe('a_b_c');
+  });
+
+  it('collapses consecutive underscores', () => {
+    expect(sanitizeProjectName('a///b')).toBe('a_b');
+    expect(sanitizeProjectName('a__b')).toBe('a_b');
+  });
+
+  it('collapses consecutive spaces', () => {
+    expect(sanitizeProjectName('a   b')).toBe('a b');
+  });
+
+  it('trims leading/trailing whitespace, underscores, and dots', () => {
+    expect(sanitizeProjectName('  My Song  ')).toBe('My Song');
+    expect(sanitizeProjectName('__song__')).toBe('song');
+    expect(sanitizeProjectName('.hidden')).toBe('hidden');
+    expect(sanitizeProjectName('...dots...')).toBe('dots');
+  });
+
+  it('returns fallback for names that become empty after sanitization', () => {
+    expect(sanitizeProjectName('///')).toBe('Untitled Project');
+    expect(sanitizeProjectName('...')).toBe('Untitled Project');
+    expect(sanitizeProjectName('___')).toBe('Untitled Project');
+  });
+});

src/util/projectNameUtil.ts

@@ -0,0 +1,44 @@
+/**
+ * Allowed characters for project names: letters, numbers, space, hyphen, underscore, period, parentheses.
+ * These are safe across Windows, macOS, and Linux as directory names.
+ */
+const VALID_PROJECT_NAME_REGEX = /^[a-zA-Z0-9 \-_.()\u00C0-\u024F]+$/;
+
+/**
+ * Characters that are NOT allowed in project names — replaced during sanitization.
+ */
+const DISALLOWED_CHARS_REGEX = /[^a-zA-Z0-9 \-_.()\u00C0-\u024F]/g;
+
+/**
+ * Validate whether a project name contains only allowed characters.
+ * Does NOT check for empty string — caller should check that separately.
+ */
+export function isValidProjectName(name: string): boolean {
+  if (!name || name.trim().length === 0) return false;
+  if (name.startsWith('.')) return false; // hidden files on Unix
+  return VALID_PROJECT_NAME_REGEX.test(name);
+}
+
+/**
+ * Sanitize a project name by replacing disallowed characters with underscores,
+ * collapsing consecutive underscores/spaces, and trimming.
+ */
+export function sanitizeProjectName(name: string): string {
+  let sanitized = name.replace(DISALLOWED_CHARS_REGEX, '_');
+
+  // Collapse consecutive underscores
+  sanitized = sanitized.replace(/_{2,}/g, '_');
+
+  // Collapse consecutive spaces
+  sanitized = sanitized.replace(/ {2,}/g, ' ');
+
+  // Trim leading/trailing whitespace, underscores, and dots
+  sanitized = sanitized.replace(/^[.\s_]+|[.\s_]+$/g, '').trim();
+
+  // If everything was stripped, provide a fallback
+  if (sanitized.length === 0) {
+    sanitized = 'Untitled Project';
+  }
+
+  return sanitized;
+}

src/util/saveUtil.ts

@@ -1,5 +1,4 @@
-import { KGStorage, DuplicateEntryError } from '../core/io/KGStorage';
-import { DB_CONSTANTS } from '../constants/coreConstants';
+import { KGProjectStorage, DuplicateEntryError } from '../core/io/KGProjectStorage';
 import { KGCore } from '../core/KGCore';
 
 /**
@@ -13,43 +12,37 @@ export const saveProject = async (
   projectName: string,
   setStatus: (status: string) => void
 ): Promise<boolean> => {
-  const storage = KGStorage.getInstance();
-  
+  const storage = KGProjectStorage.getInstance();
+
   try {
     await storage.save(
-      DB_CONSTANTS.DB_NAME,
-      DB_CONSTANTS.PROJECTS_STORE_NAME,
       projectName,
       KGCore.instance().getCurrentProject(),
       false,
-      DB_CONSTANTS.DB_VERSION
     );
-    
+
     setStatus(`Project "${projectName}" has been saved`);
     console.log("project saved successfully");
     return true;
-    
+
   } catch (error) {
     console.error("Error saving project:", error);
-    
+
     if (error instanceof DuplicateEntryError) {
       const confirmed = window.confirm(`Project "${projectName}" already exists. Do you want to overwrite it?`);
-      
+
       if (confirmed) {
         try {
           await storage.save(
-            DB_CONSTANTS.DB_NAME,
-            DB_CONSTANTS.PROJECTS_STORE_NAME,
             projectName,
             KGCore.instance().getCurrentProject(),
             true,
-            DB_CONSTANTS.DB_VERSION
           );
-          
+
           setStatus(`Project "${projectName}" has been saved`);
           console.log("project saved successfully after overwrite");
           return true;
-          
+
         } catch (overwriteError) {
           console.error("Error overwriting project:", overwriteError);
           window.alert(`An error occurred while overwriting the project: ${overwriteError}`);
@@ -65,4 +58,4 @@ export const saveProject = async (
       return false;
     }
   }
-};
+};