feat: support caching binary assets via BlobAsset

[peter-gy]

As part of the upcoming marimo-export solution, we need a way to represent media-typed binary assets like PNGs, SVGs, JSON, or HTML snippets within the new caching infrastructure.

This PR introduces BlobAsset for storing arbitrary outputs with a .bin extension which can be deserialized by clients based on BlobAsset.media_type and BlobAsset.metadata contents.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview, Comment	Jul 22, 2026 11:49am

[cubic-dev-ai]

No issues found across 4 files

Architecture diagram

sequenceDiagram
    participant Client as Marimo Kernel / Cell
    participant Stub as maybe_update_lazy_stub()
    participant BlobAsset as BlobAsset Struct
    participant Serializer as BLOB_SERIALIZERS["bin"]
    participant Deserializer as BLOB_DESERIALIZERS[".bin"]
    participant LazyLoader as LazyLoader
    participant Store as Cache Store (Filesystem)

    Note over Client,Store: Binary Asset Cache Flow

    Client->>Stub: call maybe_update_lazy_stub(value)
    Stub->>Stub: check type registration
    alt Type is BlobAsset
        Stub-->>Client: return "bin" loader key
    else Other supported type
        Stub-->>Client: return existing loader key
    end

    Client->>BlobAsset: Create with data, media_type, filename, metadata
    Client->>Serializer: encode(BlobAsset) via BLOB_SERIALIZERS["bin"]
    Serializer->>BlobAsset: access data field
    alt Valid BlobAsset
        Serializer->>Serializer: msgspec.msgpack.encode(object)
        Serializer-->>Client: return bytes with .bin encoding
    else TypeError (not BlobAsset)
        Serializer-->>Client: raise TypeError
    end

    Client->>LazyLoader: save_cache(Cache with BlobAsset defs)
    LazyLoader->>LazyLoader: to_item() checks loader in supported list
    alt Loader is "bin"
        LazyLoader->>LazyLoader: write {var}.bin file
        LazyLoader->>Store: store serialized bytes
    end

    Note over Store,LazyLoader: Cache Load (Reverse Flow)

    LazyLoader->>Store: load_cache(hash_key)
    Store-->>LazyLoader: retrieve cached bytes for .bin files

    LazyLoader->>Deserializer: decode(bytes) via BLOB_DESERIALIZERS[".bin"]
    Deserializer->>Deserializer: msgspec.msgpack.decode(bytes, type=BlobAsset)
    Deserializer-->>LazyLoader: return reconstructed BlobAsset

    LazyLoader-->>Client: return Cache with BlobAsset restored

    Note over Client,Store: Client consumes BlobAsset metadata
    Client->>BlobAsset: access .media_type (e.g. "image/svg+xml")
    Client->>BlobAsset: access .metadata (e.g. format_id)
    Client->>BlobAsset: access .data (raw bytes for export)

Loading

_{Re-trigger cubic}

[Copilot]

Pull request overview

This PR adds a new cached-blob payload type, BlobAsset, to support storing media-typed binary assets (e.g. PNG/SVG/JSON/HTML snippets) in marimo’s lazy cache infrastructure as .bin blobs, intended to support upcoming export work.

Changes:

• Introduces BlobAsset (msgspec struct) plus .bin msgpack serializer/deserializer and registers it in the lazy type-to-loader lookup.
• Extends the lazy loader’s blob strategy handling to include the new "bin" format.
• Adds tests covering codec selection, serializer round-trip, and end-to-end lazy loader save/load behavior for BlobAsset.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
tests/_save/stubs/test_lazy_asset_codec.py	Adds tests validating .bin codec selection and lazy loader round-tripping of BlobAsset.
marimo/_save/stubs/lazy_stub.py	Defines BlobAsset, registers it to the "bin" loader, and implements msgpack-based .bin (de)serialization.
marimo/_save/stubs/init.py	Re-exports BlobAsset from the stubs package.
marimo/_save/loaders/lazy.py	Adds "bin" to the set of blob-based loader strategies in to_item().

[dmadisetti]

Looks, good- is there a followup usage path? Or is this consumed directly?

[peter-gy]

Looks, good- is there a followup usage path? Or is this consumed directly?

For now only directly