feat(hub-client): import a project from a ZIP archive

[cscheid]

Summary

Adds an "Import from ZIP" action to the hub-client project-selector landing page: a user uploads a .zip and it becomes a brand-new hub-client project. This is the inverse of the existing "Export to ZIP" on ProjectTab.

The import reuses the existing project-creation pipeline end-to-end — onProjectCreated → App.handleProjectCreated → createNewProject — with no changes to the Automerge layer. createNewProject already accepts a mixed text/base64-binary file list, so import is just "parse ZIP → build that list → run the existing create path."

Tracked as bd-apv23. Design notes: claude-notes/plans/2026-06-01-import-from-zip.md.

What's in it

• ts-packages/quarto-sync-client/src/import-zip.ts — new pure parseProjectZip() (mirrors export-zip.ts). Unzips with fflate, then:
  • strips a single common top-level directory (GitHub-style repo-main/ downloads),
  • drops directory entries and __MACOSX/ · .DS_Store · .git/ junk,
  • rejects zip-slip paths (absolute / ..),
  • classifies text vs binary by extension, with a UTF-8/NUL sniff fallback for unknown extensions; binary content is base64-encoded for createNewProject.
• ts-packages/preview-runtime — new importProjectFromZip() wrapper mapping to the snake_case ProjectFile shape, symmetric with exportProjectAsZip.
• hub-client ProjectSelector — new "Import from ZIP" button + form (file picker, title prefilled from the filename, sync-server). Project type is passed as an 'imported' sentinel that App.handleProjectCreated already ignores.

Testing

TDD throughout (tests written first, confirmed failing, then implemented):

• Parser — 20 unit tests (text/binary, Unicode, nested paths, top-level-dir stripping, junk filtering, unknown-extension sniffing, zip-slip rejection, empty/corrupt errors, export→import round-trip).
• Wrapper — 2 shape-conversion / error-propagation tests.
• Component — 5 tests (button reveals form, filename prefills title, submit reads bytes → parser → onProjectCreated, parse errors surfaced, submit gated on a chosen file).
• E2E (hub-client/e2e/import-zip.spec.ts) — drives real Chromium against a live hub: upload a fixture zip (_quarto.yml, index.qmd, a real PNG) → new project created → both files appear in the sidebar → index.qmd renders the imported content in the preview iframe. Confirms text and binary round-trip through the real fflate → createNewProject → Automerge → render path.

Gates run green: hub-client unit 561 / integration 66 / wasm 79, production vite build, and the dependency packages (quarto-sync-client 136, preview-runtime 62). No Rust changes.

Note on the jsdom component test

The component test mocks importProjectFromZip rather than calling real fflate. Under vitest's jsdom environment, jsdom's TextEncoder.encode() returns a Uint8Array from a different JS realm, so x instanceof Uint8Array is false (jsdom/jsdom#2524). fflate's strToU8 uses TextEncoder, and its zipSync flatten step decides file-vs-directory with val instanceof u8 — so a strToU8-produced array is misclassified as a directory and the archive comes out corrupt. Real browsers are single-realm, so this is a test-environment artifact only (the e2e exercises the real path). Real ZIP parsing is therefore asserted in node-env suites.

Out of scope (possible follow-ups)

• Importing into an existing project (merge/overlay) — this only creates a new project.
• Async/worker unzip for very large archives.
• Drag-and-drop of a ZIP onto the landing page.

🤖 Generated with Claude Code