Add session MIDI ZIP export

.dockerignore

@@ -10,4 +10,4 @@ venv
 node_modules
 backend/data/*.sqlite3
 backend/data/*.sqlite3-*
-
+backend/data/session_midi_exports

.gitignore

@@ -6,4 +6,4 @@ venv/
 node_modules/
 backend/data/*.sqlite3
 backend/data/*.sqlite3-*
-
+backend/data/session_midi_exports/

README.md

@@ -27,6 +27,7 @@ The current implementation is meant as an MVP for experimentation, demos, and ar
 - A `FastAPI` backend that wraps the Python Continuator engine.
 - One isolated Continuator engine per live session.
 - SQLite logging for captured and generated phrases.
+- Session MIDI export for all played/generated phrase pairs.
 - A compact UI with MIDI controls, phrase playback, and session activity views.
 - A tabbed `History | Memory` activity card.
 - Docker packaging suitable for local containers and Hugging Face Docker Spaces.
@@ -53,6 +54,7 @@ What is implemented today:
 - Phrase capture based on silence detection.
 - Continuator settings exposed through a compact advanced drawer.
 - Per-session `History` and `Memory` visualization.
+- `Save Session MIDI` export from the Session panel.
 
 What is intentionally not implemented yet:
 
@@ -66,6 +68,7 @@ What is intentionally not implemented yet:
 The UI is organized around a simple performance loop:
 
 - `Session`: create a new isolated Continuator session or reset its memory.
+- `Save Session MIDI`: export every played/generated phrase pair from the current session as MIDI files in one ZIP archive.
 - `MIDI I/O`: connect browser MIDI, choose an input port, and choose a playback output.
 - `Phrase Flow`: monitor captured and generated note counts, send a phrase manually, replay the last continuation, or clear local buffers.
 - `Session Activity`: switch between `History` and `Memory`.
@@ -76,6 +79,27 @@ The UX principle is to keep the performance flow visible at all times and hide l
 - Advanced model controls live in the `Advanced Continuator Settings` drawer.
 - Memory inspection stays inside a local tabbed card rather than taking over the page.
 
+## Saving Session MIDI
+
+The Session panel includes `Save Session MIDI`.
+
+When clicked, the browser asks the backend for a ZIP archive containing one `.mid`
+file for each played input phrase and each generated phrase in the current
+session. Filenames preserve the phrase order and label files as `input` or
+`generated`.
+
+In browsers that support the File System Access API, such as Chrome and Edge,
+the button opens a file-save picker for the ZIP archive. The checkbox labelled
+`Don't ask again` remembers the selected ZIP file handle in browser storage and
+overwrites that same ZIP on future saves after permission is granted. This
+intentionally remembers a file, not a folder, because Chrome can reject folder
+access for protected locations.
+
+If the browser does not support the file-save picker, the export falls back to a
+normal browser download. The backend also keeps `POST /api/sessions/{session_id}/save-midi`
+as a server-side fallback route, but browser users should prefer the ZIP
+download path because it writes to a location they choose locally.
+
 ## High-Level Architecture
 
 ```mermaid
@@ -185,6 +209,7 @@ backend/
     config.py
     continuator_adapter.py
     main.py
+    midi_export.py
     schemas.py
     session_manager.py
     storage.py
@@ -203,6 +228,7 @@ Main responsibilities:
 - `frontend/app.js`: MIDI capture, phrase segmentation, API calls, playback, and client-side visualization.
 - `frontend/styles.css`: layout and visual design.
 - `backend/app/main.py`: FastAPI routes.
+- `backend/app/midi_export.py`: phrase-payload to MIDI conversion and ZIP packaging.
 - `backend/app/session_manager.py`: session lifecycle, orchestration, and API-facing session logic.
 - `backend/app/continuator_adapter.py`: bridge between web JSON payloads and the Continuator Python engine.
 - `backend/app/storage.py`: SQLite session and phrase logging.
@@ -220,6 +246,9 @@ Current API endpoints:
 - `POST /api/sessions/{session_id}/generate`: generate a phrase directly from memory.
 - `GET /api/sessions/{session_id}/history`: retrieve recent logged phrase history.
 - `GET /api/sessions/{session_id}/memory`: retrieve the active memory snapshot for the live engine.
+- `GET /api/sessions/{session_id}/midi-download`: return played and generated phrases as base64 MIDI file payloads.
+- `GET /api/sessions/{session_id}/midi.zip`: download played and generated phrases as a ZIP archive for the browser save/download flow.
+- `POST /api/sessions/{session_id}/save-midi`: save played and generated phrases as MIDI files on the backend as a server-side fallback.
 - `POST /api/sessions/{session_id}/reset`: clear the live engine memory while preserving session settings.
 
 API payloads use JSON and expose both:
@@ -268,6 +297,7 @@ Typical local interaction:
 7. Wait until the selected phrase gap has elapsed after the final note release. The default gap is 1 second.
 8. Let auto-send submit the phrase, or click `Send Phrase`.
 9. Inspect `History` or `Memory` in the `Session Activity` card.
+10. Use `Save Session MIDI` in the Session panel to export the played/generated phrases as a ZIP archive of MIDI files.
 
 When you change frontend code, a normal refresh is usually enough.
 When you change backend models or routes, restarting the server and refreshing the page is the safest option.
@@ -278,6 +308,7 @@ Environment variables currently supported:
 
 - `CONTINUATOR_APP_NAME`: override the displayed app name.
 - `CONTINUATOR_DB_PATH`: move the SQLite database to another location.
+- `CONTINUATOR_SESSION_EXPORT_DIR`: choose where fallback backend-side MIDI exports are written.
 - `CONTINUATOR_SEED_MIDI_FILE`: preload each new session with one MIDI file.
 - `CONTINUATOR_SEED_MIDI_FOLDER`: preload each new session with a folder of MIDI files.
 
@@ -286,6 +317,7 @@ Examples:
 ```bash
 export CONTINUATOR_SEED_MIDI_FILE=/absolute/path/to/example.mid
 export CONTINUATOR_DB_PATH=/absolute/path/to/continuator.sqlite3
+export CONTINUATOR_SESSION_EXPORT_DIR=/absolute/path/to/session-midi-exports
 ```
 
 ## Optional Seed Corpus
@@ -336,6 +368,12 @@ If you want phrase history to survive restarts, attach a storage volume or bucke
 CONTINUATOR_DB_PATH=/data/continuator.sqlite3
 ```
 
+The browser ZIP export does not require persistent Space storage because the
+archive is downloaded to the user. The server-side fallback `save-midi` route
+writes inside the container unless `CONTINUATOR_SESSION_EXPORT_DIR` points to a
+mounted volume, so it is mainly useful for local development or managed storage
+setups.
+
 If you want each new session to start from a corpus, you can also define:
 
 ```bash
@@ -348,6 +386,7 @@ For a first public demo, the simplest deployment is:
 - free CPU hardware
 - no persistent storage
 - no seed corpus
+- browser-side MIDI ZIP export only
 
 That keeps the setup minimal and is enough to validate browser MIDI capture, API round-trips, and continuation playback.
 
@@ -367,6 +406,7 @@ Things to keep in mind:
 - The current live session registry is in process memory, so scaling to multiple replicas would require shared session storage.
 - SQLite is fine for a prototype, but PostgreSQL would be a better next step for heavier concurrent use.
 - Persistent user memory is not implemented yet.
+- Browser MIDI ZIP exports are user downloads; backend-side MIDI export folders need mounted storage if they should survive a Space rebuild.
 - Long-lived or heavier multi-user deployments will need explicit storage, authentication, and horizontal architecture decisions.
 
 ## Local Mac Usage After Space Setup

backend/app/config.py

@@ -16,6 +16,7 @@ class Settings:
     app_name: str
     frontend_dir: Path
     db_path: Path
+    session_export_dir: Path
     seed_midi_file: Path | None
     seed_midi_folder: Path | None
 
@@ -32,6 +33,8 @@ def load_settings() -> Settings:
         app_name=os.getenv("CONTINUATOR_APP_NAME", "Web Continuator"),
         frontend_dir=FRONTEND_DIR,
         db_path=_env_path("CONTINUATOR_DB_PATH") or (DATA_DIR / "continuator.sqlite3"),
+        session_export_dir=_env_path("CONTINUATOR_SESSION_EXPORT_DIR")
+        or (DATA_DIR / "session_midi_exports"),
         seed_midi_file=_env_path("CONTINUATOR_SEED_MIDI_FILE"),
         seed_midi_folder=_env_path("CONTINUATOR_SEED_MIDI_FOLDER"),
     )

backend/app/main.py

@@ -21,6 +21,7 @@ from .schemas import (
     ContinueResponse,
     CreateSessionRequest,
     CreateSessionResponse,
+    DownloadSessionMidiResponse,
     GeneratePhraseRequest,
     GeneratePhraseResponse,
     ImportMidiResponse,
@@ -30,6 +31,7 @@ from .schemas import (
     PublicConfigResponse,
     RegisterRequest,
     ResetSessionResponse,
+    SaveSessionMidiResponse,
     SessionHistoryResponse,
     SessionMemoryResponse,
     UpdateSessionNameRequest,
@@ -51,6 +53,7 @@ session_manager = SessionManager(
     storage=storage,
     seed_midi_file=settings.seed_midi_file,
     seed_midi_folder=settings.seed_midi_folder,
+    session_export_dir=settings.session_export_dir,
 )
 
 
@@ -331,6 +334,76 @@ def session_history(
         raise HTTPException(status_code=404, detail=f"Unknown session: {error.args[0]}") from error
 
 
+@app.post(
+    "/api/sessions/{session_id}/save-midi",
+    response_model=SaveSessionMidiResponse,
+    tags=["session"],
+)
+def save_session_midi(
+    session_id: str,
+    current_user: AuthenticatedUser | None = Depends(get_optional_current_user),
+) -> SaveSessionMidiResponse:
+    try:
+        return session_manager.save_session_midi(
+            session_id,
+            None if current_user is None else current_user.id,
+        )
+    except UnknownSessionError as error:
+        raise HTTPException(status_code=404, detail=f"Unknown session: {error.args[0]}") from error
+    except ValueError as error:
+        raise HTTPException(status_code=400, detail=str(error)) from error
+
+
+@app.get(
+    "/api/sessions/{session_id}/midi-download",
+    response_model=DownloadSessionMidiResponse,
+    tags=["session"],
+)
+def download_session_midi(
+    session_id: str,
+    current_user: AuthenticatedUser | None = Depends(get_optional_current_user),
+) -> DownloadSessionMidiResponse:
+    try:
+        return session_manager.download_session_midi(
+            session_id,
+            None if current_user is None else current_user.id,
+        )
+    except UnknownSessionError as error:
+        raise HTTPException(status_code=404, detail=f"Unknown session: {error.args[0]}") from error
+    except ValueError as error:
+        raise HTTPException(status_code=400, detail=str(error)) from error
+
+
+@app.get(
+    "/api/sessions/{session_id}/midi.zip",
+    tags=["session"],
+)
+def session_midi_zip(
+    session_id: str,
+    current_user: AuthenticatedUser | None = Depends(get_optional_current_user),
+) -> Response:
+    try:
+        file_name, content, payload = session_manager.session_midi_zip(
+            session_id,
+            None if current_user is None else current_user.id,
+        )
+    except UnknownSessionError as error:
+        raise HTTPException(status_code=404, detail=f"Unknown session: {error.args[0]}") from error
+    except ValueError as error:
+        raise HTTPException(status_code=400, detail=str(error)) from error
+
+    return Response(
+        content=content,
+        media_type="application/zip",
+        headers={
+            "Content-Disposition": f'attachment; filename="{file_name}"',
+            "X-Midi-File-Count": str(payload.file_count),
+            "X-Midi-Input-File-Count": str(payload.input_file_count),
+            "X-Midi-Generated-File-Count": str(payload.generated_file_count),
+        },
+    )
+
+
 @app.get(
     "/api/sessions/{session_id}/memory",
     response_model=SessionMemoryResponse,

backend/app/midi_export.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from io import BytesIO
+from pathlib import Path
+from zipfile import ZIP_DEFLATED, ZipFile
+
+import mido
+
+from .schemas import PhrasePayload
+
+
+MIDI_EXPORT_TEMPO = 500_000
+MIDI_EXPORT_TICKS_PER_BEAT = 480
+
+
+def phrase_payload_to_midi_bytes(payload: PhrasePayload) -> bytes:
+    midi_file = mido.MidiFile(type=0, ticks_per_beat=MIDI_EXPORT_TICKS_PER_BEAT)
+    track = mido.MidiTrack()
+    midi_file.tracks.append(track)
+    track.append(mido.MetaMessage("set_tempo", tempo=MIDI_EXPORT_TEMPO, time=0))
+
+    current_seconds = 0.0
+    previous_tick = 0
+    for event in payload.events:
+        current_seconds += float(event.delta_seconds)
+        absolute_tick = max(
+            previous_tick,
+            int(
+                round(
+                    mido.second2tick(
+                        current_seconds,
+                        MIDI_EXPORT_TICKS_PER_BEAT,
+                        MIDI_EXPORT_TEMPO,
+                    )
+                )
+            ),
+        )
+        delta_ticks = absolute_tick - previous_tick
+        previous_tick = absolute_tick
+        velocity = int(event.velocity) if event.type == "note_on" else 0
+        track.append(
+            mido.Message(
+                event.type,
+                note=int(event.note),
+                velocity=velocity,
+                channel=int(event.channel),
+                time=delta_ticks,
+            )
+        )
+
+    track.append(mido.MetaMessage("end_of_track", time=0))
+    buffer = BytesIO()
+    midi_file.save(file=buffer)
+    return buffer.getvalue()
+
+
+def write_phrase_payload_midi(payload: PhrasePayload, path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(phrase_payload_to_midi_bytes(payload))
+
+
+def midi_files_to_zip_bytes(files: list[tuple[str, bytes]]) -> bytes:
+    buffer = BytesIO()
+    with ZipFile(buffer, mode="w", compression=ZIP_DEFLATED) as archive:
+        for file_name, content in files:
+            archive.writestr(file_name, content)
+    return buffer.getvalue()

backend/app/schemas.py

@@ -178,6 +178,46 @@ class SessionHistoryResponse(BaseModel):
     items: list[HistoryItem]
 
 
+class SessionMidiExportFile(BaseModel):
+    kind: Literal["input", "generated"]
+    request_id: str
+    file_name: str
+    path: str
+    event_count: int = Field(ge=0)
+    note_count: int = Field(ge=0)
+    duration_seconds: float = Field(ge=0.0)
+
+
+class SaveSessionMidiResponse(BaseModel):
+    session_id: str
+    exported_at: str
+    directory: str
+    file_count: int = Field(ge=0)
+    input_file_count: int = Field(ge=0)
+    generated_file_count: int = Field(ge=0)
+    files: list[SessionMidiExportFile]
+
+
+class SessionMidiDownloadFile(BaseModel):
+    kind: Literal["input", "generated"]
+    request_id: str
+    file_name: str
+    event_count: int = Field(ge=0)
+    note_count: int = Field(ge=0)
+    duration_seconds: float = Field(ge=0.0)
+    content_base64: str
+
+
+class DownloadSessionMidiResponse(BaseModel):
+    session_id: str
+    exported_at: str
+    folder_name: str
+    file_count: int = Field(ge=0)
+    input_file_count: int = Field(ge=0)
+    generated_file_count: int = Field(ge=0)
+    files: list[SessionMidiDownloadFile]
+
+
 class MemoryPhraseItem(BaseModel):
     slot: int = Field(ge=1)
     source: MemoryPhraseSource

backend/app/session_manager.py

@@ -3,15 +3,22 @@ from __future__ import annotations
 from dataclasses import dataclass
 from datetime import UTC, datetime
 from pathlib import Path
+import base64
 import threading
 import uuid
 
 from .continuator_adapter import ContinuatorSessionEngine, MidiImportError, NoContinuationAvailable
+from .midi_export import (
+    midi_files_to_zip_bytes,
+    phrase_payload_to_midi_bytes,
+    write_phrase_payload_midi,
+)
 from .schemas import (
     ContinueRequest,
     ContinueResponse,
     CreateSessionRequest,
     CreateSessionResponse,
+    DownloadSessionMidiResponse,
     GeneratePhraseResponse,
     GenerationConstraintsStatus,
     GenerationTraceStep,
@@ -23,8 +30,11 @@ from .schemas import (
     OpenSessionResponse,
     PhrasePayload,
     ResetSessionResponse,
+    SaveSessionMidiResponse,
     SessionConfiguration,
     SessionHistoryResponse,
+    SessionMidiDownloadFile,
+    SessionMidiExportFile,
     SessionMemoryResponse,
     SessionMemorySummary,
     UpdateSessionNameRequest,
@@ -47,6 +57,15 @@ def utc_now_iso() -> str:
     return datetime.now(UTC).isoformat(timespec="seconds").replace("+00:00", "Z")
 
 
+def safe_export_path_part(value: object, fallback: str) -> str:
+    normalized = "".join(
+        char if char.isalnum() or char in {"-", "_"} else "-"
+        for char in str(value or "")
+    )
+    normalized = "-".join(part for part in normalized.split("-") if part)
+    return (normalized[:80] or fallback).strip("-_") or fallback
+
+
 @dataclass
 class SessionState:
     session_id: str
@@ -68,10 +87,12 @@ class SessionManager:
         storage: PhraseStorage,
         seed_midi_file: Path | None = None,
         seed_midi_folder: Path | None = None,
+        session_export_dir: Path | None = None,
     ) -> None:
         self.storage = storage
         self.seed_midi_file = seed_midi_file
         self.seed_midi_folder = seed_midi_folder
+        self.session_export_dir = session_export_dir or Path("session_midi_exports")
         self._sessions: dict[str, SessionState] = {}
         self._lock = threading.RLock()
 
@@ -528,6 +549,138 @@ class SessionManager:
         ]
         return SessionHistoryResponse(session_id=session_id, items=items)
 
+    def save_session_midi(
+        self,
+        session_id: str,
+        owner_user_id: str | None,
+    ) -> SaveSessionMidiResponse:
+        if not self.storage.session_exists(session_id, owner_user_id, allow_guest=True):
+            raise UnknownSessionError(session_id)
+
+        rows = self.storage.get_played_and_generated_phrases(session_id)
+        if not rows:
+            raise ValueError("No played or generated phrases are available to save yet.")
+
+        exported_at = utc_now_iso()
+        folder_name = "-".join(
+            [
+                safe_export_path_part(session_id[:12], "session"),
+                safe_export_path_part(exported_at, "export"),
+                uuid.uuid4().hex[:8],
+            ]
+        )
+        export_dir = self.session_export_dir / folder_name
+        counts = {"input": 0, "generated": 0}
+        files: list[SessionMidiExportFile] = []
+
+        for index, row in enumerate(rows, start=1):
+            kind = str(row["kind"])
+            if kind not in counts:
+                continue
+            payload = PhrasePayload.model_validate(row["payload"])
+            counts[kind] += 1
+            created_at = safe_export_path_part(row["created_at"], "time")
+            request_id = safe_export_path_part(row["request_id"], "request")
+            file_name = f"{index:04d}_{kind}_{created_at}_{request_id[:12]}.mid"
+            path = export_dir / file_name
+            write_phrase_payload_midi(payload, path)
+            files.append(
+                SessionMidiExportFile(
+                    kind=kind,
+                    request_id=str(row["request_id"]),
+                    file_name=file_name,
+                    path=str(path.resolve()),
+                    event_count=payload.event_count,
+                    note_count=payload.note_count,
+                    duration_seconds=payload.duration_seconds,
+                )
+            )
+
+        if not files:
+            raise ValueError("No playable phrases are available to save yet.")
+
+        return SaveSessionMidiResponse(
+            session_id=session_id,
+            exported_at=exported_at,
+            directory=str(export_dir.resolve()),
+            file_count=len(files),
+            input_file_count=counts["input"],
+            generated_file_count=counts["generated"],
+            files=files,
+        )
+
+    def download_session_midi(
+        self,
+        session_id: str,
+        owner_user_id: str | None,
+    ) -> DownloadSessionMidiResponse:
+        if not self.storage.session_exists(session_id, owner_user_id, allow_guest=True):
+            raise UnknownSessionError(session_id)
+
+        rows = self.storage.get_played_and_generated_phrases(session_id)
+        if not rows:
+            raise ValueError("No played or generated phrases are available to save yet.")
+
+        exported_at = utc_now_iso()
+        folder_name = "-".join(
+            [
+                "continuator-session",
+                safe_export_path_part(session_id[:12], "session"),
+                safe_export_path_part(exported_at, "export"),
+                uuid.uuid4().hex[:8],
+            ]
+        )
+        counts = {"input": 0, "generated": 0}
+        files: list[SessionMidiDownloadFile] = []
+
+        for index, row in enumerate(rows, start=1):
+            kind = str(row["kind"])
+            if kind not in counts:
+                continue
+            payload = PhrasePayload.model_validate(row["payload"])
+            counts[kind] += 1
+            created_at = safe_export_path_part(row["created_at"], "time")
+            request_id = safe_export_path_part(row["request_id"], "request")
+            file_name = f"{index:04d}_{kind}_{created_at}_{request_id[:12]}.mid"
+            midi_bytes = phrase_payload_to_midi_bytes(payload)
+            files.append(
+                SessionMidiDownloadFile(
+                    kind=kind,
+                    request_id=str(row["request_id"]),
+                    file_name=file_name,
+                    event_count=payload.event_count,
+                    note_count=payload.note_count,
+                    duration_seconds=payload.duration_seconds,
+                    content_base64=base64.b64encode(midi_bytes).decode("ascii"),
+                )
+            )
+
+        if not files:
+            raise ValueError("No playable phrases are available to save yet.")
+
+        return DownloadSessionMidiResponse(
+            session_id=session_id,
+            exported_at=exported_at,
+            folder_name=folder_name,
+            file_count=len(files),
+            input_file_count=counts["input"],
+            generated_file_count=counts["generated"],
+            files=files,
+        )
+
+    def session_midi_zip(
+        self,
+        session_id: str,
+        owner_user_id: str | None,
+    ) -> tuple[str, bytes, DownloadSessionMidiResponse]:
+        payload = self.download_session_midi(session_id, owner_user_id)
+        files = [
+            (file.file_name, base64.b64decode(file.content_base64))
+            for file in payload.files
+        ]
+        archive_name = f"{payload.folder_name}.zip"
+        return archive_name, midi_files_to_zip_bytes(files), payload
+
     def get_memory(self, session_id: str, owner_user_id: str | None) -> SessionMemoryResponse:
         state = self._require_session(session_id, owner_user_id)
         return self._memory_response(

backend/app/storage.py

@@ -605,3 +605,56 @@ class PhraseStorage:
             }
             for row in rows
         ]
+
+    def get_played_and_generated_phrases(self, session_id: str) -> list[dict[str, object]]:
+        with self._lock, self._connect() as connection:
+            rows = connection.execute(
+                """
+                SELECT
+                    phrases.id,
+                    phrases.request_id,
+                    phrases.kind,
+                    phrases.created_at,
+                    phrases.event_count,
+                    phrases.note_count,
+                    phrases.duration_seconds,
+                    phrases.payload_json
+                FROM phrases
+                WHERE phrases.session_id = ?
+                  AND phrases.event_count > 0
+                  AND (
+                    phrases.kind = 'generated'
+                    OR (
+                      phrases.kind = 'input'
+                      AND EXISTS (
+                        SELECT 1
+                        FROM phrases AS generated
+                        WHERE generated.session_id = phrases.session_id
+                          AND generated.request_id = phrases.request_id
+                          AND generated.kind = 'generated'
+                          AND generated.event_count > 0
+                      )
+                    )
+                  )
+                ORDER BY
+                    phrases.created_at ASC,
+                    phrases.request_id ASC,
+                    CASE phrases.kind WHEN 'input' THEN 0 ELSE 1 END,
+                    phrases.id ASC
+                """,
+                (session_id,),
+            ).fetchall()
+
+        return [
+            {
+                "id": row["id"],
+                "request_id": row["request_id"],
+                "kind": row["kind"],
+                "created_at": row["created_at"],
+                "event_count": row["event_count"],
+                "note_count": row["note_count"],
+                "duration_seconds": row["duration_seconds"],
+                "payload": json.loads(row["payload_json"]),
+            }
+            for row in rows
+        ]

frontend/app.js

@@ -53,6 +53,9 @@ const FAUST_CLAVIER_DSP_URL = "/assets/faust/continuator-clavier.dsp";
 const FAUST_CUSTOM_TEMPLATE_DSP_URL = "/assets/faust/custom-poly-template.dsp";
 const PHRASE_TIMEOUT_STORAGE_KEY = "continuator.phrase.timeout.ms";
 const MIDI_INPUT_MONITOR_STORAGE_KEY = "continuator.midi.input.monitor";
+const MIDI_EXPORT_FILE_DB_NAME = "continuator-midi-zip-export";
+const MIDI_EXPORT_FILE_STORE_NAME = "file-handles";
+const MIDI_EXPORT_FILE_HANDLE_KEY = "session-midi-export-zip";
 const FAUST_CUSTOM_SOURCE_STORAGE_KEY = "continuator.faust.custom.source";
 const FAUST_CUSTOM_VALUES_STORAGE_KEY = "continuator.faust.custom.values";
 const PLAYBACK_PREFERENCE_STORAGE_PREFIX = "continuator.playback.preference";
@@ -151,6 +154,8 @@ const elements = {
   readyOutputStep: document.querySelector("#ready-output-step"),
   rendererHealth: document.querySelector("#renderer-health"),
   sessionSaveNote: document.querySelector("#session-save-note"),
+  sessionMidiSaveResult: document.querySelector("#session-midi-save-result"),
+  rememberMidiExportFileToggle: document.querySelector("#remember-midi-export-file-toggle"),
   timingReadout: document.querySelector("#timing-readout"),
   timelineCaptured: document.querySelector("#timeline-captured"),
   timelineGenerated: document.querySelector("#timeline-generated"),
@@ -210,6 +215,7 @@ const elements = {
   panicButton: document.querySelector("#panic-button"),
   createSessionButton: document.querySelector("#create-session-button"),
   resetSessionButton: document.querySelector("#reset-session-button"),
+  saveSessionMidiButton: document.querySelector("#save-session-midi-button"),
   applySettingsButton: document.querySelector("#apply-settings-button"),
   importMidiFilesButton: document.querySelector("#import-midi-files-button"),
   importMidiFolderButton: document.querySelector("#import-midi-folder-button"),
@@ -241,6 +247,8 @@ const state = {
   authUser: null,
   sessionId: null,
   sessionIsOwned: false,
+  sessionMidiSaving: false,
+  midiExportFileHandle: null,
   selectedInputLabel: "No MIDI input selected",
   lastMidiEventLabel: "None yet",
   readmeOpen: false,
@@ -536,6 +544,85 @@ function safeLocalStorageSet(key, value) {
   }
 }
 
+function midiExportZipSaveSupported() {
+  return typeof window.showSaveFilePicker === "function";
+}
+
+function midiExportZipRememberSupported() {
+  return midiExportZipSaveSupported() && typeof window.indexedDB !== "undefined";
+}
+
+function openMidiExportFileDb() {
+  return new Promise((resolve, reject) => {
+    if (!window.indexedDB) {
+      reject(new Error("This browser cannot remember export files."));
+      return;
+    }
+    const request = window.indexedDB.open(MIDI_EXPORT_FILE_DB_NAME, 1);
+    request.onupgradeneeded = () => {
+      request.result.createObjectStore(MIDI_EXPORT_FILE_STORE_NAME);
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error || new Error("Could not open export file storage."));
+  });
+}
+
+async function withMidiExportFileStore(mode, callback) {
+  const db = await openMidiExportFileDb();
+  try {
+    return await new Promise((resolve, reject) => {
+      const transaction = db.transaction(MIDI_EXPORT_FILE_STORE_NAME, mode);
+      const store = transaction.objectStore(MIDI_EXPORT_FILE_STORE_NAME);
+      const request = callback(store);
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error || new Error("Export file storage failed."));
+    });
+  } finally {
+    db.close();
+  }
+}
+
+function readStoredMidiExportFileHandle() {
+  return withMidiExportFileStore("readonly", (store) =>
+    store.get(MIDI_EXPORT_FILE_HANDLE_KEY),
+  );
+}
+
+function writeStoredMidiExportFileHandle(handle) {
+  return withMidiExportFileStore("readwrite", (store) =>
+    store.put(handle, MIDI_EXPORT_FILE_HANDLE_KEY),
+  );
+}
+
+function clearStoredMidiExportFileHandle() {
+  return withMidiExportFileStore("readwrite", (store) =>
+    store.delete(MIDI_EXPORT_FILE_HANDLE_KEY),
+  );
+}
+
+async function initializeMidiExportFilePreference() {
+  if (!elements.rememberMidiExportFileToggle) {
+    return;
+  }
+  const supported = midiExportZipRememberSupported();
+  elements.rememberMidiExportFileToggle.disabled = !supported;
+  if (!supported) {
+    elements.rememberMidiExportFileToggle.title =
+      "Remembering export files is not available in this browser.";
+    return;
+  }
+  try {
+    const handle = await readStoredMidiExportFileHandle();
+    if (handle) {
+      state.midiExportFileHandle = handle;
+      elements.rememberMidiExportFileToggle.checked = true;
+    }
+  } catch {
+    state.midiExportFileHandle = null;
+    elements.rememberMidiExportFileToggle.checked = false;
+  }
+}
+
 function loadStoredInputMonitorPreference() {
   return safeLocalStorageGet(MIDI_INPUT_MONITOR_STORAGE_KEY) === "true";
 }
@@ -1867,6 +1954,121 @@ function renderPerformanceState() {
   renderTimingReadout();
 }
 
+function setSessionMidiSaveResult(message = "", isError = false) {
+  if (!elements.sessionMidiSaveResult) {
+    return;
+  }
+  const normalizedMessage = String(message || "").trim();
+  elements.sessionMidiSaveResult.hidden = !normalizedMessage;
+  elements.sessionMidiSaveResult.textContent = normalizedMessage;
+  elements.sessionMidiSaveResult.classList.toggle("is-error", Boolean(isError));
+}
+
+async function ensureFileWritePermission(handle) {
+  const options = { mode: "readwrite" };
+  if ((await handle.queryPermission(options)) === "granted") {
+    return true;
+  }
+  return (await handle.requestPermission(options)) === "granted";
+}
+
+function fileNameFromContentDisposition(value) {
+  const match = String(value || "").match(/filename="([^"]+)"/i);
+  return match?.[1] || `continuator-session-${Date.now()}.zip`;
+}
+
+async function requestSessionMidiZip() {
+  const response = await fetch(`/api/sessions/${state.sessionId}/midi.zip`);
+  const blob = await response.blob();
+  if (!response.ok) {
+    let detail = `MIDI export failed (${response.status}).`;
+    try {
+      const text = await blob.text();
+      const payload = JSON.parse(text);
+      if (typeof payload?.detail === "string") {
+        detail = payload.detail;
+      }
+    } catch {
+      // Keep the default error.
+    }
+    throw new Error(detail);
+  }
+
+  return {
+    blob,
+    archive_file_name: fileNameFromContentDisposition(
+      response.headers.get("Content-Disposition"),
+    ),
+    file_count: Number(response.headers.get("X-Midi-File-Count") || 0),
+    input_file_count: Number(response.headers.get("X-Midi-Input-File-Count") || 0),
+    generated_file_count: Number(response.headers.get("X-Midi-Generated-File-Count") || 0),
+  };
+}
+
+async function chooseMidiExportZipFileHandle(fileName) {
+  const rememberFile = elements.rememberMidiExportFileToggle?.checked;
+  if (rememberFile && state.midiExportFileHandle) {
+    if (await ensureFileWritePermission(state.midiExportFileHandle)) {
+      return state.midiExportFileHandle;
+    }
+  }
+
+  const pickerOptions = {
+    id: "continuator-session-midi-zip-export",
+    suggestedName: fileName || `continuator-session-${Date.now()}.zip`,
+    startIn: "downloads",
+    types: [
+      {
+        description: "ZIP archive",
+        accept: {
+          "application/zip": [".zip"],
+        },
+      },
+    ],
+  };
+  let handle = null;
+  try {
+    handle = await window.showSaveFilePicker(pickerOptions);
+  } catch (error) {
+    if (error?.name === "TypeError") {
+      handle = await window.showSaveFilePicker({
+        suggestedName: pickerOptions.suggestedName,
+        types: pickerOptions.types,
+      });
+    } else {
+      throw error;
+    }
+  }
+  if (!(await ensureFileWritePermission(handle))) {
+    throw new Error("Permission to write that ZIP file was not granted.");
+  }
+
+  if (rememberFile && midiExportZipRememberSupported()) {
+    state.midiExportFileHandle = handle;
+    await writeStoredMidiExportFileHandle(handle);
+  }
+  return handle;
+}
+
+async function writeZipBlobToFileHandle(blob, handle) {
+  const writable = await handle.createWritable();
+  await writable.write(blob);
+  await writable.close();
+  return handle.name || "selected ZIP file";
+}
+
+function downloadZipBlob(blob, fileName) {
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = fileName || `continuator-session-${Date.now()}.zip`;
+  document.body.append(link);
+  link.click();
+  link.remove();
+  window.setTimeout(() => URL.revokeObjectURL(url), 1000);
+  return link.download;
+}
+
 function stopPhraseGapCountdown() {
   if (state.phraseGapAnimationFrameId) {
     window.cancelAnimationFrame(state.phraseGapAnimationFrameId);
@@ -2886,8 +3088,23 @@ function syncSettingsControls(configuration) {
 
 function updateSessionActionState() {
   const hasPendingSettings = hasPendingSessionSettings();
+  const canRememberExportFile = midiExportZipRememberSupported();
   elements.createSessionButton.disabled = false;
   elements.resetSessionButton.disabled = !state.sessionId;
+  elements.saveSessionMidiButton.disabled = !state.sessionId || state.sessionMidiSaving;
+  elements.saveSessionMidiButton.classList.toggle("is-pending", state.sessionMidiSaving);
+  elements.saveSessionMidiButton.textContent = state.sessionMidiSaving
+    ? "Saving MIDI..."
+    : "Save Session MIDI";
+  elements.rememberMidiExportFileToggle.disabled =
+    !canRememberExportFile || state.sessionMidiSaving;
+  if (!canRememberExportFile) {
+    elements.rememberMidiExportFileToggle.checked = false;
+    elements.rememberMidiExportFileToggle.title =
+      "Remembering export files is not available in this browser.";
+  } else {
+    elements.rememberMidiExportFileToggle.title = "";
+  }
   elements.showGraphButton.disabled = !state.sessionId || state.graphLoading;
   elements.showGraphButton.classList.toggle("is-pending", state.graphLoading);
   elements.showGraphButton.textContent = state.graphLoading
@@ -2985,6 +3202,7 @@ function clearCurrentSessionState(message = null) {
   state.sessionConfiguration = null;
   state.historyItems = [];
   state.memoryItems = [];
+  setSessionMidiSaveResult();
   elements.sessionId.textContent = "Open or create a session";
   setGraphOpen(false);
   clearPhraseBuffers();
@@ -4390,6 +4608,7 @@ async function useSessionPayload(payload, { owned = Boolean(state.authUser) } =
   state.sessionId = payload.session_id;
   state.sessionIsOwned = owned;
   state.sessionConfiguration = payload.configuration;
+  setSessionMidiSaveResult();
   elements.sessionId.textContent = payload.session_id;
   syncSettingsControls(payload.configuration);
   await restoreSessionPreferences(payload.configuration);
@@ -4478,6 +4697,54 @@ async function resetSession() {
   await refreshSavedSessions();
 }
 
+async function saveSessionMidi() {
+  if (!state.sessionId) {
+    setSessionMidiSaveResult("Create or open a session before saving MIDI files.", true);
+    setPhraseMessage("Create or open a session before saving MIDI files.", true);
+    return;
+  }
+
+  state.sessionMidiSaving = true;
+  updateSessionActionState();
+  setSessionMidiSaveResult("Saving played and generated phrases as MIDI files...");
+  setPhraseStatus("Saving");
+  setPhraseMessage("Saving played and generated phrases as MIDI files...");
+  try {
+    const payload = await requestSessionMidiZip();
+    let destinationLabel = null;
+    if (midiExportZipSaveSupported()) {
+      let fileHandle = null;
+      try {
+        fileHandle = await chooseMidiExportZipFileHandle(payload.archive_file_name);
+      } catch (error) {
+        if (error?.name === "AbortError") {
+          setPhraseStatus(state.lastCapturedPhrase.length ? "Phrase ready" : "Waiting for MIDI");
+          setSessionMidiSaveResult("MIDI export cancelled.");
+          setPhraseMessage("MIDI export cancelled.");
+          return;
+        }
+        if (error?.name === "NotAllowedError" || /system files/i.test(error?.message || "")) {
+          throw new Error(
+            "Chrome blocked that location. Save the ZIP in Downloads, Documents, Desktop, or Music instead of a system, home, or project folder.",
+          );
+        }
+        throw error;
+      }
+      destinationLabel = await writeZipBlobToFileHandle(payload.blob, fileHandle);
+    } else {
+      destinationLabel = `${downloadZipBlob(payload.blob, payload.archive_file_name)} in your browser downloads`;
+    }
+
+    const message = defaultSessionMidiSaveMessage(payload, destinationLabel);
+    setPhraseStatus("Saved");
+    setSessionMidiSaveResult(message);
+    setPhraseMessage(message);
+  } finally {
+    state.sessionMidiSaving = false;
+    updateSessionActionState();
+  }
+}
+
 async function applyCurrentSessionSettings() {
   if (!state.sessionId) {
     setPhraseMessage("Create a session before applying settings.", true);
@@ -4706,6 +4973,14 @@ function defaultMidiImportMessage(payload) {
   return message;
 }
 
+function defaultSessionMidiSaveMessage(payload, destinationLabel = null) {
+  const fileCount = Number(payload?.file_count || 0);
+  const inputCount = Number(payload?.input_file_count || 0);
+  const generatedCount = Number(payload?.generated_file_count || 0);
+  const destination = destinationLabel || payload?.directory || "the selected folder";
+  return `Saved ${pluralize(fileCount, "MIDI file")} (${pluralize(inputCount, "played phrase")}, ${pluralize(generatedCount, "generated phrase")}) to ${destination}.`;
+}
+
 function defaultMemoryGenerationMessage(payload, requestedNoteCount) {
   return (
     payload.status_message ||
@@ -6566,6 +6841,30 @@ function bindEvents() {
     }
   });
 
+  elements.saveSessionMidiButton.addEventListener("click", async () => {
+    try {
+      await saveSessionMidi();
+    } catch (error) {
+      setSessionMidiSaveResult(error.message, true);
+      setPhraseMessage(error.message, true);
+      setPhraseStatus("Error");
+    }
+  });
+
+  elements.rememberMidiExportFileToggle.addEventListener("change", async () => {
+    if (elements.rememberMidiExportFileToggle.checked) {
+      setSessionMidiSaveResult("The next selected MIDI ZIP file will be remembered and overwritten on future saves.");
+      return;
+    }
+    state.midiExportFileHandle = null;
+    try {
+      await clearStoredMidiExportFileHandle();
+      setSessionMidiSaveResult("MIDI export ZIP preference cleared.");
+    } catch {
+      setSessionMidiSaveResult("MIDI export ZIP preference cleared for this page.");
+    }
+  });
+
   elements.connectMidiButton.addEventListener("click", async () => {
     try {
       await connectMidi();
@@ -7038,6 +7337,7 @@ async function initialize() {
   }
   initializePhraseTimeoutSetting();
   initializeInputMonitorPreference();
+  await initializeMidiExportFilePreference();
   populatePlaybackChoices();
   syncAuthUI();
   renderSavedSessions([]);

frontend/index.html

@@ -4,7 +4,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>Web Continuator</title>
-    <link rel="stylesheet" href="/assets/styles.css?v=20260505-label-button-contrast" />
+    <link rel="stylesheet" href="/assets/styles.css?v=20260602-session-midi-zip2" />
   </head>
   <body>
     <div class="page-aura"></div>
@@ -157,6 +157,20 @@
           </ol>
         </section>
 
+        <section class="readme-block">
+          <h3>Saving Session MIDI</h3>
+          <p>
+            The Session panel can export the current session as a MIDI ZIP
+            archive. The archive contains the played input phrases and generated
+            continuations in session order.
+          </p>
+          <p>
+            In Chrome and Edge, <strong>Don't ask again</strong> remembers the
+            selected ZIP file and overwrites it on future saves. Other browsers
+            use the normal download flow.
+          </p>
+        </section>
+
         <section class="readme-block">
           <h3>Studio Layout</h3>
           <ul class="readme-list">
@@ -887,7 +901,19 @@
                 <div class="button-row">
                   <button id="create-session-button">Create Session</button>
                   <button id="reset-session-button" class="ghost">Reset Memory</button>
+                  <button id="save-session-midi-button" class="ghost">
+                    Save Session MIDI
+                  </button>
+                  <label class="toggle compact-toggle">
+                    <input id="remember-midi-export-file-toggle" type="checkbox" />
+                    <span>Don't ask again</span>
+                  </label>
                 </div>
+                <p
+                  id="session-midi-save-result"
+                  class="session-midi-save-result"
+                  hidden
+                ></p>
                 <div class="settings-compact">
                   <div class="settings-label-row">
                     <span class="small-copy">Current settings</span>
@@ -1133,6 +1159,6 @@
       </section>
     </main>
 
-    <script type="module" src="/assets/app.js?v=20260504-graph-modes"></script>
+    <script type="module" src="/assets/app.js?v=20260602-session-midi-zip2"></script>
   </body>
 </html>

frontend/styles.css

@@ -1451,6 +1451,24 @@ input[type="password"]:disabled {
   line-height: 1.45;
 }
 
+.session-midi-save-result {
+  margin: -6px 0 16px;
+  padding: 10px 12px;
+  border-radius: 14px;
+  border: 1px solid rgba(109, 211, 206, 0.22);
+  background: rgba(109, 211, 206, 0.08);
+  color: var(--text);
+  font-size: 0.84rem;
+  line-height: 1.45;
+  overflow-wrap: anywhere;
+}
+
+.session-midi-save-result.is-error {
+  border-color: rgba(239, 127, 88, 0.34);
+  background: rgba(239, 127, 88, 0.1);
+  color: #ffd8ca;
+}
+
 .timeline-card {
   padding-bottom: 18px;
 }