refactor: add load_notebook helper, simplify AppFileRouter

[mscolnick]

Extract the from_filename → get_unique_file_key → get_file_manager boilerplate into load_notebook(path) / new_notebook() helpers and migrate single-file consumers (islands, server export, session cache, dev CLI) off the router.

Hoist optional router capabilities (register_allowed_file, register_temp_dir, is_file_in_allowed_temp_dir, mark_stale, toggle_markdown) to the abstract base as no-op defaults so callers in SessionManager and the home endpoint stop branching on isinstance.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview, Comment	May 1, 2026 7:01pm

[cubic-dev-ai]

No issues found across 11 files

Architecture diagram

sequenceDiagram
    participant CLI as "CLI / Islands / Export"
    participant Loader as "Notebook Loader (NEW)"
    participant API as "API Endpoints (Home)"
    participant SM as "SessionManager"
    participant Router as "AppFileRouter (Base)"
    participant FM as "AppFileManager"

    Note over CLI, FM: Single File Access Flow (Simplified)

    CLI->>Loader: NEW: load_notebook(path)
    Loader->>Loader: Resolve absolute path
    opt Invalid extension (.txt, etc)
        Loader-->>CLI: Raise ValueError
    end
    Loader->>FM: Instantiate AppFileManager
    FM-->>Loader: file_manager
    Loader-->>CLI: return file_manager
    Note right of CLI: CLI/Islands no longer use Router\nfor single files.

    Note over API, Router: Workspace / Directory Flow (Refactored)

    API->>SM: Get File Router
    SM-->>API: file_router

    API->>Router: CHANGED: mark_stale()
    Note right of Router: Hoisted to base class.\nNo-op if not supported.

    API->>Router: CHANGED: toggle_markdown(bool)
    Router-->>API: return self OR new Router
    Note right of Router: No more 'isinstance' branching\nin caller.

    API->>Router: CHANGED: register_temp_dir(path)
    Note right of Router: Allows tutorial/temp files\nvia abstract interface.

    Note over SM, FM: Session Lifecycle Flow

    SM->>Router: CHANGED: register_allowed_file(path)
    Note right of Router: Logic shifted from SessionManager\nto Router implementations.

    SM->>Router: get_file_manager(key)
    alt Router is NewFileAppFileRouter
        Router->>FM: Instantiate (unbacked)
    else Router is Directory-backed
        Router->>FM: Instantiate (path-backed)
    end
    Router-->>SM: return file_manager

Loading

[dmadisetti]

Nice cleanup

[Copilot]

Pull request overview

This PR introduces a small notebook-loading API in marimo._session.notebook to replace repeated “router → unique key → file manager” boilerplate for single-file workflows, and simplifies router usage by making several router capabilities available as no-op defaults on the base class.

Changes:

• Added load_notebook(path) / new_notebook() helpers that validate marimo notebook extensions and load notebooks via AppFileManager.
• Migrated single-file consumers (exports, islands, session snapshot/export CLI, dev preview) to use load_notebook instead of AppFileRouter.from_filename(...).get_unique_file_key()....
• Hoisted optional router capabilities (e.g., mark_stale, toggle_markdown, temp dir registration) to AppFileRouter as no-op defaults, simplifying call sites that previously branched on router type.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/_session/notebook/test_loader.py	Adds coverage for load_notebook/new_notebook behavior (path types, relative resolution, extension validation, basic load).
marimo/_session/notebook/loader.py	Implements load_notebook and new_notebook helpers backed by MarimoPath + AppFileManager.
marimo/_session/notebook/init.py	Exposes the new loader helpers from the notebook package.
marimo/_server/session_manager.py	Removes router-type branching by calling register_allowed_file unconditionally in edit mode (now safe via base no-op).
marimo/_server/file_router.py	Makes get_file_manager/resolve_file_path abstract and adds no-op default implementations for optional router capabilities.
marimo/_server/export/_session_cache.py	Switches notebook hashing to load_notebook.
marimo/_server/export/init.py	Switches multiple export helpers to load_notebook for file manager creation.
marimo/_server/api/endpoints/home.py	Simplifies watched-folder refresh and markdown toggle logic using base no-op router methods.
marimo/_islands/_island_generator.py	Uses load_notebook for island generation from file.
marimo/_cli/export/session.py	Uses load_notebook for session snapshot exports (including subprocess script).
marimo/_cli/development/commands.py	Uses load_notebook for the dev preview command’s file manager creation.

[github-actions]

🚀 Development release published. You may be able to view the changes at https://marimo.app?v=0.23.5-dev10