F8.2a: Import project files as durable library projects

[Flow-Fly]

Parent

• F8.2 — OS file-handler registration for .pf / .aseprite #123

Goal

Route .pf and legacy JSON project imports through one service that creates a new durable library identity without replacing the active project.

Context

The File menu currently parses and loads files directly into the active singleton project. F8.2 needs the same behavior for File menu, drag-and-drop, and OS launches.

Risk and routing

Risk: low
Readiness: ready-for-agent

The change is local, reversible, and covered through public service/workspace behavior. It does not request new browser permissions.

Acceptance Criteria

• Importing a valid .pf file creates a new project UUID and preserves its embedded project name.
• Legacy supported project input is migrated and persisted in the current canonical format.
• The active project is never overwritten.
• Invalid input creates no library record.
• When the workspace tab limit is full, the project is still saved to the library and the result explains that it was not opened.
• Existing guided-project creation behavior is unchanged.

Suggested Files

• src/services/project-file-import.ts
• src/services/project-library.ts
• src/stores/workspace.ts
• focused service/store tests

Verification

• Focused Vitest coverage for valid, legacy, invalid, and tab-limit paths.
• npm run test:run
• npm run build
• git diff --check

Dependencies

None.

Out of Scope

• Aseprite conversion.
• PWA launch registration.
• Writing changes back to the original OS file.

[Flow-Fly]

Agent Assessment

Risk: low
Agent-ready: yes
Routing: ready-for-agent

Evidence:

• Existing project migration, IndexedDB repository, workspace-open, and auto-save seams provide direct public interfaces.
• The new service can prove that the active context is unchanged and invalid input writes nothing.

Why this is safe:

• Read-only file parsing followed by a new UUID; no source-file writes or destructive replacement.

Verification:

• Focused import tests, full tests, production build, and diff check.

Human question or blocker:

• None.