From a622dc8456f0bd58e71b6337a5742d31f1bae99c Mon Sep 17 00:00:00 2001
From: Hugo Bois <hugo.bois@hotmail.fr>
Date: Wed, 10 Jun 2026 17:27:18 +0200
Subject: [PATCH 1/3] asset handling wip for boards, added advanced section to
 production panel

---
 components/board/BoardCanvas.module.css       |  29 +++
 components/board/BoardCanvas.tsx              | 123 ++++++++++--
 components/board/BoardCard.tsx                | 109 +++++-----
 components/navbar/ProductionPanel.module.css  | 102 ++++++++++
 components/navbar/ProductionPanel.tsx         |  87 ++++----
 components/project/WritingTimer.tsx           |   2 +-
 messages/de.json                              |   2 +
 messages/en.json                              |   2 +
 messages/es.json                              |   2 +
 messages/fr.json                              |   2 +
 messages/ja.json                              |   2 +
 messages/ko.json                              |   2 +
 messages/pl.json                              |   2 +
 messages/zh.json                              |   2 +
 src/context/ProjectContext.tsx                |   9 +
 src/lib/adapters/scriptio/scriptio-adapter.ts |  73 ++-----
 src/lib/assets/asset-gc.ts                    |  79 ++++++++
 src/lib/assets/asset-hash.ts                  |  19 ++
 src/lib/assets/asset-store.ts                 |  88 +++++++++
 src/lib/assets/use-asset-gc.ts                |  31 +++
 src/lib/assets/use-asset-url.ts               |  71 +++++++
 src/lib/import/import-project.ts              |  73 ++-----
 .../indexeddb-storage-provider.ts             | 121 +++++++++++-
 .../storage-provider/local-persistence.ts     |  10 +-
 .../migrations/store-migrations.ts            |  23 ++-
 .../storage-provider/storage-provider.ts      |  35 ++++
 src/lib/project/project-doc.ts                |  16 ++
 src/lib/project/project-state.ts              | 187 +++++++++++++++++-
 src/tests/assets/assets.test.ts               | 183 +++++++++++++++++
 .../migrations/store-migration-runner.test.ts |   1 +
 src/tests/project/scriptio-roundtrip.test.ts  | 172 ++++++++++++++++
 31 files changed, 1425 insertions(+), 234 deletions(-)
 create mode 100644 src/lib/assets/asset-gc.ts
 create mode 100644 src/lib/assets/asset-hash.ts
 create mode 100644 src/lib/assets/asset-store.ts
 create mode 100644 src/lib/assets/use-asset-gc.ts
 create mode 100644 src/lib/assets/use-asset-url.ts
 create mode 100644 src/tests/assets/assets.test.ts
 create mode 100644 src/tests/project/scriptio-roundtrip.test.ts

diff --git a/components/board/BoardCanvas.module.css b/components/board/BoardCanvas.module.css
index e943ad0e..0b566473 100644
--- a/components/board/BoardCanvas.module.css
+++ b/components/board/BoardCanvas.module.css
@@ -32,6 +32,12 @@
     cursor: grabbing;
 }
 
+/* Highlight the canvas while an image file is dragged over it. */
+.container.drag_over {
+    outline: 2px dashed var(--secondary-text);
+    outline-offset: -8px;
+}
+
 .grid {
     position: absolute;
     inset: 0;
@@ -76,6 +82,29 @@
     z-index: 1000;
 }
 
+/* Image resource card: bare image, no colored header/border chrome. */
+.card.image_card {
+    border: 1px solid rgba(0, 0, 0, 0.12);
+    background-color: var(--main-bg);
+    padding: 0;
+    overflow: hidden;
+}
+
+.card_image {
+    width: 100%;
+    height: 100%;
+    object-fit: contain;
+    display: block;
+    pointer-events: none;
+    user-select: none;
+}
+
+.card_image_placeholder {
+    width: 100%;
+    height: 100%;
+    background-color: rgba(0, 0, 0, 0.05);
+}
+
 .card_header {
     position: relative;
     display: flex;
diff --git a/components/board/BoardCanvas.tsx b/components/board/BoardCanvas.tsx
index ad1ed280..e83497f4 100644
--- a/components/board/BoardCanvas.tsx
+++ b/components/board/BoardCanvas.tsx
@@ -9,10 +9,14 @@ import { v7 as uuidv7 } from "uuid";
 import { Trash2, Plus, Minus, Copy, ListTree } from "lucide-react";
 import { useTranslations } from "next-intl";
 import { DEFAULT_ITEM_COLORS } from "@src/lib/utils/colors";
+import { importImageFile } from "@src/lib/assets/asset-store";
+import { scheduleAssetGc } from "@src/lib/assets/asset-gc";
 
 const GRID_SIZE = 20;
 const MIN_SCALE = 0.25;
 const MAX_SCALE = 2;
+/** Largest edge (in canvas px) an image card is sized to on first drop. */
+const MAX_IMAGE_CARD_SIZE = 400;
 
 interface CardContextMenuState {
     position: { x: number; y: number };
@@ -25,7 +29,7 @@ interface ArrowContextMenuState {
 }
 
 const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }) => {
-    const { repository, isYjsReady, isReadOnly, boardFocusCardId, setBoardFocusCardId } =
+    const { projectId, repository, isYjsReady, isReadOnly, boardFocusCardId, setBoardFocusCardId } =
         useContext(ProjectContext);
     const t = useTranslations("board");
     const projectState = repository?.getState();
@@ -37,6 +41,7 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
     const [offset, setOffset] = useState({ x: 0, y: 0 });
     const [scale, setScale] = useState(1);
     const [isPanning, setIsPanning] = useState(false);
+    const [isDraggingFile, setIsDraggingFile] = useState(false);
     const [isSnapping, setIsSnapping] = useState(true);
     const [cardContextMenu, setCardContextMenu] = useState<CardContextMenuState | null>(null);
     const [arrowContextMenu, setArrowContextMenu] = useState<ArrowContextMenuState | null>(null);
@@ -496,6 +501,73 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
         [cards, offset, scale, isSnapping, saveCards],
     );
 
+    // Highlight the canvas while an OS file drag hovers over it.
+    const handleDragOver = useCallback(
+        (e: React.DragEvent) => {
+            if (isReadOnly) return;
+            if (!Array.from(e.dataTransfer.types).includes("Files")) return;
+            e.preventDefault();
+            e.dataTransfer.dropEffect = "copy";
+            setIsDraggingFile(true);
+        },
+        [isReadOnly],
+    );
+
+    const handleDragLeave = useCallback((e: React.DragEvent) => {
+        // Ignore leave events fired when moving between the container's children.
+        if (!e.currentTarget.contains(e.relatedTarget as Node | null)) setIsDraggingFile(false);
+    }, []);
+
+    // Drop image files → store each in IndexedDB (deduped) and drop an image
+    // card referencing its hash at the cursor.
+    const handleDrop = useCallback(
+        async (e: React.DragEvent) => {
+            e.preventDefault();
+            setIsDraggingFile(false);
+            if (isReadOnly || !projectId) return;
+
+            const files = Array.from(e.dataTransfer.files).filter((f) => f.type.startsWith("image/"));
+            if (files.length === 0) return;
+
+            const container = containerRef.current;
+            if (!container) return;
+            const rect = container.getBoundingClientRect();
+            const dropX = (e.clientX - rect.left - offset.x) / scale;
+            const dropY = (e.clientY - rect.top - offset.y) / scale;
+
+            const created: BoardCardData[] = [];
+            for (const file of files) {
+                try {
+                    const { hash, width, height } = await importImageFile(projectId, file);
+                    const fit = Math.min(1, MAX_IMAGE_CARD_SIZE / Math.max(width, height, 1));
+                    const i = created.length;
+                    created.push({
+                        id: uuidv7(),
+                        type: "image",
+                        assetId: hash,
+                        title: "",
+                        description: "",
+                        color: "transparent",
+                        x: dropX + i * 24,
+                        y: dropY + i * 24,
+                        width: Math.max(60, Math.round(width * fit)),
+                        height: Math.max(60, Math.round(height * fit)),
+                    });
+                } catch (err) {
+                    console.error("[BoardCanvas] Failed to import image:", err);
+                }
+            }
+            if (created.length === 0) return;
+
+            setCards((prev) => {
+                const next = [...prev, ...created];
+                saveCards(next);
+                return next;
+            });
+        },
+        [isReadOnly, projectId, offset, scale, saveCards],
+    );
+
     // Update card (with multi-drag support)
     const handleUpdateCard = useCallback(
         (updatedCard: BoardCardData) => {
@@ -540,8 +612,10 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
             setArrows(newArrows);
             saveArrows(newArrows);
             setCardContextMenu(null);
+            // Deleting an image card may orphan its asset — reconcile (debounced).
+            if (projectId && projectState) scheduleAssetGc(projectId, projectState);
         },
-        [cards, arrows, saveCards, saveArrows],
+        [cards, arrows, saveCards, saveArrows, projectId, projectState],
     );
 
     // Change card color
@@ -769,10 +843,13 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
             <div className={styles.board_shadow} />
             <div
                 ref={containerRef}
-                className={`${styles.container} ${isPanning ? styles.panning : ""}`}
+                className={`${styles.container} ${isPanning ? styles.panning : ""} ${isDraggingFile ? styles.drag_over : ""}`}
                 onMouseDown={handleContainerMouseDown}
                 onDoubleClick={handleDoubleClick}
                 onWheel={handleWheel}
+                onDragOver={handleDragOver}
+                onDragLeave={handleDragLeave}
+                onDrop={handleDrop}
             >
                 <div className={styles.grid} style={gridPattern} />
 
@@ -899,6 +976,7 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
                         <BoardCard
                             key={card.id}
                             card={card}
+                            projectId={projectId}
                             scale={scale}
                             isSnapping={isSnapping}
                             gridSize={GRID_SIZE}
@@ -934,16 +1012,19 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
                             left: cardContextMenu.position.x,
                         }}
                     >
-                        <div className={styles.context_menu_colors}>
-                            {DEFAULT_ITEM_COLORS.map((color) => (
-                                <button
-                                    key={color}
-                                    className={`${styles.context_menu_color_swatch} ${cardContextMenu.card.color === color ? styles.context_menu_color_swatch_active : ""}`}
-                                    style={{ backgroundColor: color }}
-                                    onClick={() => handleChangeCardColor(cardContextMenu.card.id, color)}
-                                />
-                            ))}
-                        </div>
+                        {/* Color + outline apply to text notes; image cards have neither. */}
+                        {cardContextMenu.card.type !== "image" && (
+                            <div className={styles.context_menu_colors}>
+                                {DEFAULT_ITEM_COLORS.map((color) => (
+                                    <button
+                                        key={color}
+                                        className={`${styles.context_menu_color_swatch} ${cardContextMenu.card.color === color ? styles.context_menu_color_swatch_active : ""}`}
+                                        style={{ backgroundColor: color }}
+                                        onClick={() => handleChangeCardColor(cardContextMenu.card.id, color)}
+                                    />
+                                ))}
+                            </div>
+                        )}
                         <div
                             className={styles.context_menu_item}
                             onClick={() => handleDuplicateCard(cardContextMenu.card)}
@@ -951,13 +1032,15 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
                             <Copy size={16} />
                             <p className="unselectable">{t("duplicate")}</p>
                         </div>
-                        <div
-                            className={styles.context_menu_item}
-                            onClick={() => handleSendToOutline(cardContextMenu.card)}
-                        >
-                            <ListTree size={16} />
-                            <p className="unselectable">{t("sendToOutline")}</p>
-                        </div>
+                        {cardContextMenu.card.type !== "image" && (
+                            <div
+                                className={styles.context_menu_item}
+                                onClick={() => handleSendToOutline(cardContextMenu.card)}
+                            >
+                                <ListTree size={16} />
+                                <p className="unselectable">{t("sendToOutline")}</p>
+                            </div>
+                        )}
                         <div
                             className={styles.context_menu_item}
                             onClick={() => handleDeleteCard(cardContextMenu.card.id)}
diff --git a/components/board/BoardCard.tsx b/components/board/BoardCard.tsx
index d8de0bb4..60166e9f 100644
--- a/components/board/BoardCard.tsx
+++ b/components/board/BoardCard.tsx
@@ -4,9 +4,11 @@ import { useRef, useState, useCallback, useEffect } from "react";
 import styles from "./BoardCanvas.module.css";
 import { useTranslations } from "next-intl";
 import { BoardCardData } from "@src/lib/project/project-state";
+import { useAssetUrl } from "@src/lib/assets/use-asset-url";
 
 interface BoardCardProps {
     card: BoardCardData;
+    projectId: string;
     scale: number;
     isSnapping: boolean;
     gridSize: number;
@@ -20,6 +22,7 @@ interface BoardCardProps {
 
 const BoardCard = ({
     card,
+    projectId,
     scale,
     isSnapping,
     gridSize,
@@ -30,6 +33,9 @@ const BoardCard = ({
     isConnecting,
     isSelected,
 }: BoardCardProps) => {
+    const isImage = card.type === "image";
+    // Only resolves bytes for image cards (null assetId is a no-op for text notes).
+    const imageUrl = useAssetUrl(projectId, isImage ? card.assetId : null);
     const t = useTranslations("board");
     const cardRef = useRef<HTMLDivElement>(null);
     const [isDragging, setIsDragging] = useState(false);
@@ -237,63 +243,74 @@ const BoardCard = ({
     return (
         <div
             ref={cardRef}
-            className={`${styles.card} ${isDragging ? styles.card_dragging : ""} ${isConnecting ? styles.card_connecting : ""} ${isSelected ? styles.card_selected : ""}`}
+            className={`${styles.card} ${isImage ? styles.image_card : ""} ${isDragging ? styles.card_dragging : ""} ${isConnecting ? styles.card_connecting : ""} ${isSelected ? styles.card_selected : ""}`}
             style={{
                 left: card.x,
                 top: card.y,
                 width: card.width,
                 height: card.height,
-                borderColor: card.color,
-                backgroundColor: card.color,
+                ...(isImage ? {} : { borderColor: card.color, backgroundColor: card.color }),
             }}
             onMouseDown={handleMouseDown}
             onMouseUp={handleCardMouseUp}
-            onDoubleClick={handleDoubleClick}
+            onDoubleClick={isImage ? undefined : handleDoubleClick}
             onContextMenu={handleRightClick}
         >
-            <div className={styles.card_header} style={{ backgroundColor: card.color }}>
-                {isEditingTitle ? (
-                    <input
-                        type="text"
-                        className={styles.card_header_title_input}
-                        value={localTitle}
-                        onChange={(e) => setLocalTitle(e.target.value)}
-                        onBlur={handleTitleBlur}
-                        onKeyDown={handleTitleKeyDown}
-                        onClick={(e) => e.stopPropagation()}
-                        onMouseDown={(e) => e.stopPropagation()}
-                        placeholder={t("titlePlaceholder")}
-                        autoFocus
-                    />
+            {isImage ? (
+                imageUrl ? (
+                    // Blob object URLs can't be optimized by next/image; a plain <img> is correct here.
+                    // eslint-disable-next-line @next/next/no-img-element
+                    <img src={imageUrl} alt="" draggable={false} className={styles.card_image} />
                 ) : (
-                    <span className={styles.card_header_title} onDoubleClick={handleTitleDoubleClick}>
-                        {card.title || t("untitled")}
-                    </span>
-                )}
-            </div>
-
-            <div
-                className={styles.card_content}
-                style={{ backgroundColor: `color-mix(in srgb, ${card.color} 20%, white)` }}
-                onDoubleClick={handleDoubleClick}
-            >
-                <p className={styles.card_description} style={{ display: isEditing ? "none" : undefined }}>
-                    {card.description}
-                </p>
-                {isEditing && (
-                    <textarea
-                        className={styles.card_description_input}
-                        value={localDescription}
-                        onChange={(e) => setLocalDescription(e.target.value)}
-                        onBlur={handleDescriptionBlur}
-                        onKeyDown={handleDescriptionKeyDown}
-                        onClick={(e) => e.stopPropagation()}
-                        onMouseDown={(e) => e.stopPropagation()}
-                        placeholder={t("descriptionPlaceholder")}
-                        autoFocus
-                    />
-                )}
-            </div>
+                    <div className={styles.card_image_placeholder} />
+                )
+            ) : (
+                <>
+                    <div className={styles.card_header} style={{ backgroundColor: card.color }}>
+                        {isEditingTitle ? (
+                            <input
+                                type="text"
+                                className={styles.card_header_title_input}
+                                value={localTitle}
+                                onChange={(e) => setLocalTitle(e.target.value)}
+                                onBlur={handleTitleBlur}
+                                onKeyDown={handleTitleKeyDown}
+                                onClick={(e) => e.stopPropagation()}
+                                onMouseDown={(e) => e.stopPropagation()}
+                                placeholder={t("titlePlaceholder")}
+                                autoFocus
+                            />
+                        ) : (
+                            <span className={styles.card_header_title} onDoubleClick={handleTitleDoubleClick}>
+                                {card.title || t("untitled")}
+                            </span>
+                        )}
+                    </div>
+
+                    <div
+                        className={styles.card_content}
+                        style={{ backgroundColor: `color-mix(in srgb, ${card.color} 20%, white)` }}
+                        onDoubleClick={handleDoubleClick}
+                    >
+                        <p className={styles.card_description} style={{ display: isEditing ? "none" : undefined }}>
+                            {card.description}
+                        </p>
+                        {isEditing && (
+                            <textarea
+                                className={styles.card_description_input}
+                                value={localDescription}
+                                onChange={(e) => setLocalDescription(e.target.value)}
+                                onBlur={handleDescriptionBlur}
+                                onKeyDown={handleDescriptionKeyDown}
+                                onClick={(e) => e.stopPropagation()}
+                                onMouseDown={(e) => e.stopPropagation()}
+                                placeholder={t("descriptionPlaceholder")}
+                                autoFocus
+                            />
+                        )}
+                    </div>
+                </>
+            )}
 
             <div className={styles.card_resize_handle} onMouseDown={handleResizeStart} />
 
diff --git a/components/navbar/ProductionPanel.module.css b/components/navbar/ProductionPanel.module.css
index db741973..d68d5454 100644
--- a/components/navbar/ProductionPanel.module.css
+++ b/components/navbar/ProductionPanel.module.css
@@ -97,6 +97,108 @@
     text-overflow: ellipsis;
 }
 
+/* Info hint — icon next to a label that reveals a small explanatory popover
+   on hover/focus. */
+.hint {
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+    flex-shrink: 0;
+    outline: none;
+}
+
+.hint_icon {
+    color: var(--secondary-text);
+    cursor: help;
+    display: block;
+}
+
+.hint:hover .hint_icon,
+.hint:focus .hint_icon {
+    color: var(--primary-text);
+}
+
+.hint_popover {
+    position: absolute;
+    top: calc(100% + 8px);
+    left: 0;
+    z-index: 200;
+    width: 240px;
+    padding: 8px 10px;
+    background-color: var(--secondary);
+    border: 1px solid var(--separator);
+    border-radius: 8px;
+    box-shadow: 0 6px 18px rgba(0, 0, 0, 0.18);
+    font-size: 0.72rem;
+    line-height: 1.45;
+    color: var(--secondary-text);
+    white-space: normal;
+    opacity: 0;
+    visibility: hidden;
+    transition: opacity 0.12s ease;
+    pointer-events: none;
+}
+
+.hint:hover .hint_popover,
+.hint:focus .hint_popover {
+    opacity: 1;
+    visibility: visible;
+}
+
+/* Draft locking section drops its own bottom border: the Advanced divider
+   below provides the separating line instead. */
+.section_flush {
+    border-bottom: none;
+}
+
+/* Advanced — a labeled, clickable divider. The flanking lines replace a plain
+   separator, with the toggle label resting on the line. */
+.advanced_divider {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    width: 100%;
+    padding: 2px 16px 12px;
+    border: none;
+    background: none;
+    cursor: pointer;
+    color: var(--secondary-text);
+}
+
+.advanced_divider::before,
+.advanced_divider::after {
+    content: "";
+    flex: 1;
+    height: 1px;
+    background-color: var(--separator);
+}
+
+.advanced_divider_label {
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+    font-size: 0.68rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    white-space: nowrap;
+    transition: color 0.12s ease;
+}
+
+.advanced_divider:hover .advanced_divider_label {
+    color: var(--primary-text);
+}
+
+.advanced_chevron {
+    color: inherit;
+    flex-shrink: 0;
+    transition: transform 0.15s ease;
+}
+
+.advanced_chevron_open {
+    transform: rotate(180deg);
+}
+
 /* Provisional labels preview — boxed sub-section under the locking toggle. */
 .provisional_box {
     margin-top: 10px;
diff --git a/components/navbar/ProductionPanel.tsx b/components/navbar/ProductionPanel.tsx
index d00b815e..3c8183a4 100644
--- a/components/navbar/ProductionPanel.tsx
+++ b/components/navbar/ProductionPanel.tsx
@@ -2,7 +2,7 @@
 
 import { useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
 import { useTranslations } from "next-intl";
-import { X, BookOpen, Clapperboard, PencilLine, Settings } from "lucide-react";
+import { X, BookOpen, Clapperboard, PencilLine, Settings, Info, ChevronDown } from "lucide-react";
 
 import { ProjectContext } from "@src/context/ProjectContext";
 import { UserContext } from "@src/context/UserContext";
@@ -59,6 +59,10 @@ const ProductionPanel = ({ isOpen, onClose }: ProductionPanelProps) => {
     // until revision tracking is wired to the repository.
     const [revisionColor, setRevisionColor] = useState(REVISION_COLORS[0].name);
 
+    // Scene/page/revision controls are tucked under a collapsed "Advanced"
+    // section — the draft toggle covers the common case on its own.
+    const [advancedOpen, setAdvancedOpen] = useState(false);
+
     const revisionOptions: DropdownOption[] = REVISION_COLORS.map((c) => ({
         value: c.name,
         label: (
@@ -86,28 +90,17 @@ const ProductionPanel = ({ isOpen, onClose }: ProductionPanelProps) => {
         return () => document.removeEventListener("mousedown", handleClickOutside);
     }, [isOpen, onClose]);
 
-    const sceneUuids = useMemo(
-        () => scenes.map((s) => s.id).filter((id): id is string => !!id),
-        [scenes],
-    );
+    const sceneUuids = useMemo(() => scenes.map((s) => s.id).filter((id): id is string => !!id), [scenes]);
 
     const labels = useMemo(
         () =>
             sceneLocking
-                ? computeSceneLabels(
-                      sceneUuids,
-                      persistentScenes,
-                      sceneNumberingStyle,
-                      skippedSceneLetters,
-                  )
+                ? computeSceneLabels(sceneUuids, persistentScenes, sceneNumberingStyle, skippedSceneLetters)
                 : [],
         [sceneLocking, sceneUuids, persistentScenes, sceneNumberingStyle, skippedSceneLetters],
     );
 
-    const provisionalLabels = useMemo(
-        () => labels.filter((l) => l.status === "provisional"),
-        [labels],
-    );
+    const provisionalLabels = useMemo(() => labels.filter((l) => l.status === "provisional"), [labels]);
 
     // Stable across renders: the popup keeps a reference to this callback.
     const performUnlock = useCallback(() => {
@@ -131,12 +124,7 @@ const ProductionPanel = ({ isOpen, onClose }: ProductionPanelProps) => {
         // Re-read fresh persistent data
         const persistentSnapshot = repository.scenes;
 
-        const currentLabels = computeSceneLabels(
-            uuids,
-            persistentSnapshot,
-            sceneNumberingStyle,
-            skippedSceneLetters,
-        );
+        const currentLabels = computeSceneLabels(uuids, persistentSnapshot, sceneNumberingStyle, skippedSceneLetters);
 
         currentLabels.forEach((label) => {
             if (label.status === "provisional") {
@@ -189,10 +177,7 @@ const ProductionPanel = ({ isOpen, onClose }: ProductionPanelProps) => {
         return computeSceneLabels(pageAnchors, persistentPages, "suffix", skippedSceneLetters);
     }, [pageLocking, pageAnchors, persistentPages, skippedSceneLetters]);
 
-    const provisionalPageLabels = useMemo(
-        () => pageLabels.filter((l) => l.status === "provisional"),
-        [pageLabels],
-    );
+    const provisionalPageLabels = useMemo(() => pageLabels.filter((l) => l.status === "provisional"), [pageLabels]);
 
     const performPageUnlock = useCallback(() => {
         if (!repository) return;
@@ -213,12 +198,7 @@ const ProductionPanel = ({ isOpen, onClose }: ProductionPanelProps) => {
         const anchorInfos = getPageAnchorInfo(editor);
         const anchors = anchorInfos.map((a) => a.anchorId);
         const persistentSnapshot = repository.pages;
-        const currentLabels = computeSceneLabels(
-            anchors,
-            persistentSnapshot,
-            "suffix",
-            skippedSceneLetters,
-        );
+        const currentLabels = computeSceneLabels(anchors, persistentSnapshot, "suffix", skippedSceneLetters);
         currentLabels.forEach((label, idx) => {
             if (label.status === "provisional") {
                 repository.upsertPage(label.uuid, {
@@ -262,8 +242,7 @@ const ProductionPanel = ({ isOpen, onClose }: ProductionPanelProps) => {
     const draftLocking = sceneLocking && pageLocking;
 
     const hasProvisionalDraft =
-        (sceneLocking && provisionalLabels.length > 0) ||
-        (pageLocking && provisionalPageLabels.length > 0);
+        (sceneLocking && provisionalLabels.length > 0) || (pageLocking && provisionalPageLabels.length > 0);
 
     const performDraftUnlock = useCallback(() => {
         if (!repository) return;
@@ -318,11 +297,16 @@ const ProductionPanel = ({ isOpen, onClose }: ProductionPanelProps) => {
             </div>
 
             {/* Draft Locking (scenes + pages together) */}
-            <div className={styles.section}>
+            <div className={`${styles.section} ${styles.section_flush}`}>
                 <div className={styles.row}>
                     <div className={styles.row_main}>
-                        <PencilLine size={14} className={styles.row_icon} />
                         <span className={styles.row_label}>{t("draftLocking")}</span>
+                        <span className={styles.hint} tabIndex={0}>
+                            <Info size={14} className={styles.hint_icon} />
+                            <span className={styles.hint_popover} role="tooltip">
+                                {t("draftLockingHint")}
+                            </span>
+                        </span>
                     </div>
                     <div className={styles.row_actions}>
                         {draftLocking && hasProvisionalDraft && (
@@ -345,11 +329,29 @@ const ProductionPanel = ({ isOpen, onClose }: ProductionPanelProps) => {
                 </div>
             </div>
 
+            {/* Advanced — a labeled separator that folds the scene/page/revision
+                controls. The label sits on the divider line under Draft locking. */}
+            <button
+                type="button"
+                className={styles.advanced_divider}
+                onClick={() => setAdvancedOpen((open) => !open)}
+                aria-expanded={advancedOpen}
+            >
+                <span className={styles.advanced_divider_label}>
+                    {t("advanced")}
+                    <ChevronDown
+                        size={13}
+                        className={`${styles.advanced_chevron} ${advancedOpen ? styles.advanced_chevron_open : ""}`}
+                    />
+                </span>
+            </button>
+
+            {advancedOpen && (
+                <>
             {/* Scene Locking */}
             <div className={styles.section}>
                 <div className={styles.row}>
                     <div className={styles.row_main}>
-                        <Clapperboard size={14} className={styles.row_icon} />
                         <span className={styles.row_label}>{t("sceneLocking")}</span>
                     </div>
                     <div className={styles.row_actions}>
@@ -377,10 +379,7 @@ const ProductionPanel = ({ isOpen, onClose }: ProductionPanelProps) => {
                         <div className={styles.provisional_title}>{t("provisionalTitle")}</div>
                         <div className={styles.provisional_list}>
                             {provisionalLabels.map((l, idx) => (
-                                <span
-                                    key={`${l.uuid}-${idx}`}
-                                    className={styles.provisional_label}
-                                >
+                                <span key={`${l.uuid}-${idx}`} className={styles.provisional_label}>
                                     {l.label}
                                 </span>
                             ))}
@@ -393,7 +392,6 @@ const ProductionPanel = ({ isOpen, onClose }: ProductionPanelProps) => {
             <div className={styles.section}>
                 <div className={styles.row}>
                     <div className={styles.row_main}>
-                        <BookOpen size={14} className={styles.row_icon} />
                         <span className={styles.row_label}>{t("pageLocking")}</span>
                     </div>
                     <div className={styles.row_actions}>
@@ -421,10 +419,7 @@ const ProductionPanel = ({ isOpen, onClose }: ProductionPanelProps) => {
                         <div className={styles.provisional_title}>{t("pageProvisionalTitle")}</div>
                         <div className={styles.provisional_list}>
                             {provisionalPageLabels.map((l, idx) => (
-                                <span
-                                    key={`${l.uuid}-${idx}`}
-                                    className={styles.provisional_label}
-                                >
+                                <span key={`${l.uuid}-${idx}`} className={styles.provisional_label}>
                                     {l.label}
                                 </span>
                             ))}
@@ -448,6 +443,8 @@ const ProductionPanel = ({ isOpen, onClose }: ProductionPanelProps) => {
                     className={styles.revision_select}
                 />
             </div>
+                </>
+            )}
         </div>
     );
 };
diff --git a/components/project/WritingTimer.tsx b/components/project/WritingTimer.tsx
index 2fa0dfdc..5485e6bb 100644
--- a/components/project/WritingTimer.tsx
+++ b/components/project/WritingTimer.tsx
@@ -12,7 +12,7 @@ type TimerMode = "countdown" | "stopwatch";
 const PRESETS = [10, 15, 25, 45];
 // Minutes added/removed per stepper click, and the allowed duration range (sec).
 const STEP = 5;
-const MIN_SECONDS = 30;
+const MIN_SECONDS = 1;
 const MAX_SECONDS = 180 * 60;
 
 const clampSeconds = (sec: number) => Math.min(MAX_SECONDS, Math.max(MIN_SECONDS, Math.round(sec)));
diff --git a/messages/de.json b/messages/de.json
index 5cd39367..baff18ef 100644
--- a/messages/de.json
+++ b/messages/de.json
@@ -487,6 +487,8 @@
   "production": {
     "title": "Produktion",
     "draftLocking": "Entwurf sperren",
+    "draftLockingHint": "Beim Sperren eines Entwurfs werden die aktuellen Szenen und Seiten automatisch gesperrt und zur nächsten Revision gewechselt. Öffnen Sie den Bereich „Erweitert“, um diese manuell zu konfigurieren.",
+    "advanced": "Erweitert",
     "draftRelock": "Erneut sperren",
     "settings": "Produktionseinstellungen",
     "unlockDraftTitle": "Entwurf entsperren",
diff --git a/messages/en.json b/messages/en.json
index c72afd3c..230c0599 100644
--- a/messages/en.json
+++ b/messages/en.json
@@ -486,6 +486,8 @@
   "production": {
     "title": "Production",
     "draftLocking": "Draft locking",
+    "draftLockingHint": "Locking a draft automatically locks current scenes, pages and switches to the next revision. Open the Advanced section to configure these manually.",
+    "advanced": "Advanced",
     "draftRelock": "Relock",
     "settings": "Production settings",
     "unlockDraftTitle": "Unlock draft",
diff --git a/messages/es.json b/messages/es.json
index d212320a..f952198f 100644
--- a/messages/es.json
+++ b/messages/es.json
@@ -486,6 +486,8 @@
   "production": {
     "title": "Producción",
     "draftLocking": "Bloquear borrador",
+    "draftLockingHint": "Bloquear un borrador bloquea automáticamente las escenas y páginas actuales y pasa a la siguiente revisión. Abre la sección Avanzado para configurarlas manualmente.",
+    "advanced": "Avanzado",
     "draftRelock": "Volver a bloquear",
     "settings": "Ajustes de producción",
     "unlockDraftTitle": "Desbloquear borrador",
diff --git a/messages/fr.json b/messages/fr.json
index df70cb12..e6f11028 100644
--- a/messages/fr.json
+++ b/messages/fr.json
@@ -487,6 +487,8 @@
   "production": {
     "title": "Production",
     "draftLocking": "Verrouillage du brouillon",
+    "draftLockingHint": "Verrouiller un brouillon verrouille automatiquement les scènes et pages actuelles et passe à la révision suivante. Ouvrez la section Avancé pour les configurer manuellement.",
+    "advanced": "Avancé",
     "draftRelock": "Reverrouiller",
     "settings": "Paramètres de production",
     "unlockDraftTitle": "Déverrouiller le brouillon",
diff --git a/messages/ja.json b/messages/ja.json
index 02b93ce6..314543d3 100644
--- a/messages/ja.json
+++ b/messages/ja.json
@@ -486,6 +486,8 @@
   "production": {
     "title": "プロダクション",
     "draftLocking": "ドラフトロック",
+    "draftLockingHint": "ドラフトをロックすると、現在のシーンとページが自動的にロックされ、次のリビジョンに切り替わります。手動で設定するには「詳細設定」セクションを開いてください。",
+    "advanced": "詳細設定",
     "draftRelock": "再ロック",
     "settings": "制作設定",
     "unlockDraftTitle": "ドラフトのロック解除",
diff --git a/messages/ko.json b/messages/ko.json
index 8d464cfc..fa4c2f24 100644
--- a/messages/ko.json
+++ b/messages/ko.json
@@ -486,6 +486,8 @@
   "production": {
     "title": "프로덕션",
     "draftLocking": "드래프트 잠금",
+    "draftLockingHint": "드래프트를 잠그면 현재 씬과 페이지가 자동으로 잠기고 다음 리비전으로 전환됩니다. 수동으로 설정하려면 고급 섹션을 여세요.",
+    "advanced": "고급",
     "draftRelock": "다시 잠그기",
     "settings": "프로덕션 설정",
     "unlockDraftTitle": "드래프트 잠금 해제",
diff --git a/messages/pl.json b/messages/pl.json
index d91a6f95..2c0c51f3 100644
--- a/messages/pl.json
+++ b/messages/pl.json
@@ -486,6 +486,8 @@
   "production": {
     "title": "Produkcja",
     "draftLocking": "Blokowanie wersji roboczej",
+    "draftLockingHint": "Zablokowanie wersji roboczej automatycznie blokuje bieżące sceny i strony oraz przełącza na następną wersję. Otwórz sekcję Zaawansowane, aby skonfigurować je ręcznie.",
+    "advanced": "Zaawansowane",
     "draftRelock": "Zablokuj ponownie",
     "settings": "Ustawienia produkcji",
     "unlockDraftTitle": "Odblokuj wersję roboczą",
diff --git a/messages/zh.json b/messages/zh.json
index 3bd3101e..3453b649 100644
--- a/messages/zh.json
+++ b/messages/zh.json
@@ -486,6 +486,8 @@
   "production": {
     "title": "制作",
     "draftLocking": "锁定草稿",
+    "draftLockingHint": "锁定草稿会自动锁定当前场景、页面并切换到下一个修订版本。打开「高级」部分可手动配置这些选项。",
+    "advanced": "高级",
     "draftRelock": "重新锁定",
     "settings": "制作设置",
     "unlockDraftTitle": "解锁草稿",
diff --git a/src/context/ProjectContext.tsx b/src/context/ProjectContext.tsx
index 5229e0c0..3d28f118 100644
--- a/src/context/ProjectContext.tsx
+++ b/src/context/ProjectContext.tsx
@@ -36,6 +36,7 @@ import {
 import { Screenplay } from "@src/lib/utils/types";
 import { ScreenplayElement, TitlePageElement, Style, PageFormat } from "@src/lib/utils/enums";
 import { SearchMatch } from "@src/lib/screenplay/extensions/search-highlight-extension";
+import { useAssetGc } from "@src/lib/assets/use-asset-gc";
 
 // Import types only - these don't cause module loading
 import type { ThrottledWebsocketProvider } from "@src/lib/cloud/utils";
@@ -47,6 +48,8 @@ import type { ProjectRepository } from "@src/lib/project/project-repository";
 
 export interface ProjectContextType {
     // Project data
+    /** The active project's id (stable for the provider's lifetime). */
+    projectId: string;
     project: ProjectMembershipPayload | null;
     updateProject: (project: ProjectMembershipPayload) => void;
 
@@ -176,6 +179,7 @@ export interface ProjectContextType {
 // -------------------------------- //
 
 const defaultContextValue: ProjectContextType = {
+    projectId: "",
     project: null,
     updateProject: () => {},
     repository: null,
@@ -437,6 +441,9 @@ export const ProjectProvider = ({ children, projectId }: ProjectProviderProps) =
         repository?.setReadOnly(isReadOnly);
     }, [repository, isReadOnly]);
 
+    // Keep IndexedDB image assets reconciled with the document (orphan sweep).
+    useAssetGc(projectId, repository, isYjsReady);
+
     // The DO pushes a role-changed message whenever an admin updates this
     // user's role. Mirror it into local state so isReadOnly flips and the
     // editor/repository gates apply immediately, without waiting for an SWR
@@ -918,6 +925,7 @@ export const ProjectProvider = ({ children, projectId }: ProjectProviderProps) =
 
     const contextValue = useMemo<ProjectContextType>(
         () => ({
+            projectId,
             project,
             updateProject,
             repository,
@@ -998,6 +1006,7 @@ export const ProjectProvider = ({ children, projectId }: ProjectProviderProps) =
             setBoardFocusCardId,
         }),
         [
+            projectId,
             project,
             updateProject,
             repository,
diff --git a/src/lib/adapters/scriptio/scriptio-adapter.ts b/src/lib/adapters/scriptio/scriptio-adapter.ts
index 474ef582..98245d85 100644
--- a/src/lib/adapters/scriptio/scriptio-adapter.ts
+++ b/src/lib/adapters/scriptio/scriptio-adapter.ts
@@ -1,4 +1,4 @@
-import { LayoutData, ProductionData, ProjectData, ProjectMetadata, ProjectState, screenplayOf, titlepageOf } from "@src/lib/project/project-state";
+import { ProjectData, ProjectState, applyProjectData, clearProjectData, projectDataOf } from "@src/lib/project/project-state";
 import { BaseExportOptions, ProjectAdapter } from "../screenplay-adapter";
 import { replaceScreenplay } from "../../screenplay/editor";
 import { Editor } from "@tiptap/react";
@@ -69,20 +69,9 @@ export class ScriptioAdapter extends ProjectAdapter<ScriptioExportOptions> {
         if (isReadable) {
             // Human-readable path: serialize the full project as indented JSON.
             // This produces a larger file but makes the content inspectable
-            // with any text editor.
-            const data: ProjectData = {
-                screenplay: screenplayOf(project),
-                titlepage: titlepageOf(project),
-                metadata: project.metadata().toJSON() as ProjectMetadata,
-                characters: project.characters().toJSON(),
-                scenes: project.scenes().toJSON(),
-                pages: project.pages().toJSON(),
-                locations: project.locations().toJSON(),
-                layout: project.layout().toJSON() as LayoutData,
-                production: project.production().toJSON() as ProductionData,
-                comments: project.comments().toJSON(),
-            };
-            payload = new TextEncoder().encode(JSON.stringify(data, null, 2));
+            // with any text editor. `projectDataOf` captures every map and
+            // fragment, so the readable export is just as lossless as binary.
+            payload = new TextEncoder().encode(JSON.stringify(projectDataOf(project), null, 2));
         } else {
             // Binary path: zlib-compress the raw Yjs state.
             // Preserves the full CRDT document, including collaboration history.
@@ -121,18 +110,7 @@ export class ScriptioAdapter extends ProjectAdapter<ScriptioExportOptions> {
             const decompressed = fflate.unzlibSync(payload);
             Y.applyUpdate(tmpDoc, decompressed);
 
-            return {
-                screenplay: screenplayOf(tmpDoc),
-                titlepage: titlepageOf(tmpDoc),
-                metadata: tmpDoc.metadata().toJSON() as ProjectMetadata,
-                characters: tmpDoc.characters().toJSON(),
-                scenes: tmpDoc.scenes().toJSON(),
-                pages: tmpDoc.pages().toJSON(),
-                locations: tmpDoc.locations().toJSON(),
-                layout: tmpDoc.layout().toJSON() as LayoutData,
-                production: tmpDoc.production().toJSON() as ProductionData,
-                comments: tmpDoc.comments().toJSON(),
-            };
+            return projectDataOf(tmpDoc);
         } catch (error) {
             console.error("Failed to parse .scriptio file", error);
             throw new Error("Invalid Scriptio file format");
@@ -152,32 +130,21 @@ export class ScriptioAdapter extends ProjectAdapter<ScriptioExportOptions> {
         const payload = data.subarray(payloadOffset);
         const isReadable = (flags & FLAG_READABLE_JSON) !== 0;
 
-        if (!isReadable && repository) {
+        if (repository) {
             const ydoc = repository.getState() as ProjectState;
             try {
-                const decompressed = fflate.unzlibSync(payload);
-
-                // To truly "replace" the state, we clear existing content
-                // to avoid merging with the previous project data.
-                ydoc.transact(() => {
-                    // Fragments - delete all content
-                    const screenplay = ydoc.screenplayFragment();
-                    if (screenplay.length > 0) screenplay.delete(0, screenplay.length);
-                    const titlepage = ydoc.titlepageFragment();
-                    if (titlepage.length > 0) titlepage.delete(0, titlepage.length);
-
-                    // Maps - clear all entries
-                    ydoc.metadata().clear();
-                    ydoc.characters().clear();
-                    ydoc.scenes().clear();
-                    ydoc.locations().clear();
-                    ydoc.layout().clear();
-                    ydoc.production().clear();
-                    ydoc.comments().clear();
-                });
-
-                // Apply the new state
-                Y.applyUpdate(ydoc, decompressed);
+                // Truly "replace" the project: wipe every existing map and
+                // fragment first so the import never merges with prior data.
+                clearProjectData(ydoc);
+
+                if (isReadable) {
+                    const json = new TextDecoder().decode(payload);
+                    applyProjectData(ydoc, JSON.parse(json) as ProjectData);
+                } else {
+                    // Applying the raw Yjs update preserves the full CRDT state,
+                    // including any collaboration history baked into the file.
+                    Y.applyUpdate(ydoc, fflate.unzlibSync(payload));
+                }
 
                 // Refresh editors if provided
                 const projectData = this.convertFrom(rawContent);
@@ -190,11 +157,11 @@ export class ScriptioAdapter extends ProjectAdapter<ScriptioExportOptions> {
 
                 return;
             } catch (error) {
-                console.warn("Failed to apply binary Scriptio update directly, falling back to base import.", error);
+                console.warn("Failed to apply Scriptio update directly, falling back to base import.", error);
             }
         }
 
-        // Fallback to the base implementation for readable JSON or if repository is missing
+        // Fallback to the base implementation if no repository is available.
         super.import(rawContent, editor, titlePageEditor, repository);
     }
 }
diff --git a/src/lib/assets/asset-gc.ts b/src/lib/assets/asset-gc.ts
new file mode 100644
index 00000000..7bd30100
--- /dev/null
+++ b/src/lib/assets/asset-gc.ts
@@ -0,0 +1,79 @@
+/**
+ * Asset garbage collection (reconcile-from-doc / mark-sweep).
+ *
+ * Image bytes live in IndexedDB, decoupled from Yjs; the board cards only carry
+ * the `assetId` (SHA-256). The set of assetIds referenced across every board in
+ * the document is therefore the source of truth for what is still in use. GC
+ * computes that set and deletes any stored blob not in it — robust against
+ * collaboration and crashes, with no persisted reference counter to drift.
+ */
+
+import type { BoardCardData } from "../project/project-doc";
+import type { ProjectState } from "../project/project-state";
+import { getStorageProvider } from "../persistence/storage-provider/storage-provider";
+
+/** Every asset hash referenced by an image card across all board documents. */
+export function collectReferencedHashes(ydoc: ProjectState): Set<string> {
+    const referenced = new Set<string>();
+    ydoc.documents().forEach((node) => {
+        if (node.type !== "board") return;
+        const raw = ydoc.boardData(node.id).get("cards");
+        if (!raw) return;
+        try {
+            const cards = JSON.parse(raw) as BoardCardData[];
+            for (const card of cards) {
+                if (card.type === "image" && card.assetId) referenced.add(card.assetId);
+            }
+        } catch {
+            // A malformed cards blob shouldn't make us delete live assets — skip.
+            // (Conservative: treat as "references unknown", handled below.)
+            throw new SkipGcError();
+        }
+    });
+    return referenced;
+}
+
+/** Internal sentinel: a parse failure means we can't safely reconcile this run. */
+class SkipGcError extends Error {}
+
+/**
+ * Delete every stored asset of `projectId` whose hash is not referenced by any
+ * board card in `ydoc`. No-ops safely if a board's cards blob can't be parsed.
+ */
+export async function gcProjectAssets(projectId: string, ydoc: ProjectState): Promise<void> {
+    let referenced: Set<string>;
+    try {
+        referenced = collectReferencedHashes(ydoc);
+    } catch (e) {
+        if (e instanceof SkipGcError) return;
+        throw e;
+    }
+
+    const provider = await getStorageProvider();
+    const stored = await provider.listAssetHashes(projectId);
+    const orphans = stored.filter((hash) => !referenced.has(hash));
+    await Promise.all(orphans.map((hash) => provider.deleteAsset(projectId, hash)));
+}
+
+// ── Debounced scheduler ──────────────────────────────────────────────────────
+
+const GC_DEBOUNCE_MS = 1500;
+const pending = new Map<string, ReturnType<typeof setTimeout>>();
+
+/**
+ * Schedule a debounced project-wide reconcile (per projectId). Rapid edits — a
+ * burst of card deletions, say — coalesce into a single sweep.
+ */
+export function scheduleAssetGc(projectId: string, ydoc: ProjectState): void {
+    const existing = pending.get(projectId);
+    if (existing) clearTimeout(existing);
+    pending.set(
+        projectId,
+        setTimeout(() => {
+            pending.delete(projectId);
+            void gcProjectAssets(projectId, ydoc).catch((e) =>
+                console.warn("[assets] GC failed:", e),
+            );
+        }, GC_DEBOUNCE_MS),
+    );
+}
diff --git a/src/lib/assets/asset-hash.ts b/src/lib/assets/asset-hash.ts
new file mode 100644
index 00000000..59be747f
--- /dev/null
+++ b/src/lib/assets/asset-hash.ts
@@ -0,0 +1,19 @@
+/**
+ * SHA-256 hashing for content-addressed assets.
+ *
+ * Assets (board images) are keyed by the hex SHA-256 of their bytes so the same
+ * image dropped twice is stored once. Uses the Web Crypto API, available in both
+ * the browser and the Tauri webview. This is the single client-side hashing
+ * helper — reuse it for the future cloud R2 upload path too.
+ */
+
+/** Hex SHA-256 digest of a byte buffer. */
+export async function sha256Hex(buffer: ArrayBuffer): Promise<string> {
+    const digest = await crypto.subtle.digest("SHA-256", buffer);
+    const bytes = new Uint8Array(digest);
+    let hex = "";
+    for (const byte of bytes) {
+        hex += byte.toString(16).padStart(2, "0");
+    }
+    return hex;
+}
diff --git a/src/lib/assets/asset-store.ts b/src/lib/assets/asset-store.ts
new file mode 100644
index 00000000..d2b8508a
--- /dev/null
+++ b/src/lib/assets/asset-store.ts
@@ -0,0 +1,88 @@
+/**
+ * Local asset store façade.
+ *
+ * The single chokepoint for reading/writing board image bytes, decoupled from
+ * the Yjs document. Assets are stored in IndexedDB content-addressed by SHA-256
+ * (so duplicates collapse) and scoped per project. A future cloud variant will
+ * extend this seam to also upload to / fetch from R2.
+ */
+
+import { getStorageProvider } from "../persistence/storage-provider/storage-provider";
+import { sha256Hex } from "./asset-hash";
+
+export interface AssetMeta {
+    /** SHA-256 hex — the assetId referenced by board cards. */
+    hash: string;
+    mime: string;
+    width: number;
+    height: number;
+}
+
+/** Read the intrinsic pixel size of an image file, with a decode fallback. */
+async function decodeImageSize(file: Blob): Promise<{ width: number; height: number }> {
+    if (typeof createImageBitmap === "function") {
+        try {
+            const bitmap = await createImageBitmap(file);
+            const size = { width: bitmap.width, height: bitmap.height };
+            bitmap.close();
+            return size;
+        } catch {
+            // fall through to the <img> path
+        }
+    }
+
+    const url = URL.createObjectURL(file);
+    try {
+        return await new Promise<{ width: number; height: number }>((resolve, reject) => {
+            const img = new Image();
+            img.onload = () => resolve({ width: img.naturalWidth, height: img.naturalHeight });
+            img.onerror = () => reject(new Error("Failed to decode image"));
+            img.src = url;
+        });
+    } finally {
+        URL.revokeObjectURL(url);
+    }
+}
+
+/**
+ * Store an image file for a project and return its metadata. Idempotent: if an
+ * asset with the same bytes already exists it is returned unchanged (dedup).
+ */
+export async function importImageFile(projectId: string, file: File): Promise<AssetMeta> {
+    const buffer = await file.arrayBuffer();
+    const hash = await sha256Hex(buffer);
+    const mime = file.type || "image/png";
+
+    const provider = await getStorageProvider();
+
+    const existing = await provider.getAsset(projectId, hash);
+    if (existing) {
+        return { hash, mime: existing.mime, width: existing.width, height: existing.height };
+    }
+
+    const { width, height } = await decodeImageSize(file);
+    await provider.putAsset({
+        key: `${projectId}/${hash}`,
+        projectId,
+        hash,
+        mime,
+        size: file.size,
+        width,
+        height,
+        data: buffer,
+        createdAt: Date.now(),
+    });
+
+    return { hash, mime, width, height };
+}
+
+/**
+ * Resolve an asset to an object URL for rendering, or null if it isn't stored
+ * locally. Callers own the URL and must `URL.revokeObjectURL` it when done.
+ */
+export async function loadAssetObjectUrl(projectId: string, hash: string): Promise<string | null> {
+    const provider = await getStorageProvider();
+    const asset = await provider.getAsset(projectId, hash);
+    if (!asset) return null;
+    return URL.createObjectURL(new Blob([asset.data], { type: asset.mime }));
+}
diff --git a/src/lib/assets/use-asset-gc.ts b/src/lib/assets/use-asset-gc.ts
new file mode 100644
index 00000000..024253fa
--- /dev/null
+++ b/src/lib/assets/use-asset-gc.ts
@@ -0,0 +1,31 @@
+"use client";
+
+/**
+ * Mount once per project (in ProjectProvider) to keep IndexedDB assets in sync
+ * with the document. Runs a reconcile when the project becomes ready (clears
+ * orphans left by prior sessions, remote deletions, or crashes) and again,
+ * debounced, whenever the document tree changes — board/folder deletions clear
+ * their board maps, which can orphan images. Per-card deletions are handled
+ * separately in BoardCanvas (they don't touch the documents map).
+ */
+
+import { useEffect } from "react";
+import type { ProjectRepository } from "../project/project-repository";
+import { gcProjectAssets, scheduleAssetGc } from "./asset-gc";
+
+export function useAssetGc(
+    projectId: string | null,
+    repository: ProjectRepository | null,
+    isReady: boolean,
+): void {
+    useEffect(() => {
+        if (!projectId || !repository || !isReady) return;
+        const ydoc = repository.getState();
+
+        void gcProjectAssets(projectId, ydoc).catch((e) =>
+            console.warn("[assets] initial GC failed:", e),
+        );
+
+        return repository.observeDocuments(() => scheduleAssetGc(projectId, ydoc));
+    }, [projectId, repository, isReady]);
+}
diff --git a/src/lib/assets/use-asset-url.ts b/src/lib/assets/use-asset-url.ts
new file mode 100644
index 00000000..713e50d3
--- /dev/null
+++ b/src/lib/assets/use-asset-url.ts
@@ -0,0 +1,71 @@
+"use client";
+
+/**
+ * Resolve a board image asset to an object URL for rendering.
+ *
+ * Backed by a module-level, ref-counted cache keyed by `${projectId}/${hash}`,
+ * so the same image used by several cards shares one object URL (no flicker) and
+ * the URL is revoked only when the last consumer unmounts (no leaks).
+ */
+
+import { useEffect, useState } from "react";
+import { loadAssetObjectUrl } from "./asset-store";
+
+interface CacheEntry {
+    refCount: number;
+    promise: Promise<string | null>;
+}
+
+const cache = new Map<string, CacheEntry>();
+
+const cacheKey = (projectId: string, hash: string) => `${projectId}/${hash}`;
+
+function acquire(projectId: string, hash: string): Promise<string | null> {
+    const key = cacheKey(projectId, hash);
+    let entry = cache.get(key);
+    if (!entry) {
+        entry = { refCount: 0, promise: loadAssetObjectUrl(projectId, hash) };
+        cache.set(key, entry);
+    }
+    entry.refCount++;
+    return entry.promise;
+}
+
+function release(projectId: string, hash: string): void {
+    const key = cacheKey(projectId, hash);
+    const entry = cache.get(key);
+    if (!entry) return;
+    entry.refCount--;
+    if (entry.refCount <= 0) {
+        cache.delete(key);
+        void entry.promise.then((url) => {
+            if (url) URL.revokeObjectURL(url);
+        });
+    }
+}
+
+/** Object URL for the asset, or null while loading / when not stored locally. */
+export function useAssetUrl(
+    projectId: string | null | undefined,
+    assetId: string | null | undefined,
+): string | null {
+    // Tag the loaded URL with its key so a stale image is never shown while a
+    // new asset loads (and so the no-asset case returns null without setState).
+    const key = projectId && assetId ? cacheKey(projectId, assetId) : null;
+    const [loaded, setLoaded] = useState<{ key: string; url: string } | null>(null);
+
+    useEffect(() => {
+        if (!projectId || !assetId) return;
+        const k = cacheKey(projectId, assetId);
+        let active = true;
+        void acquire(projectId, assetId).then((resolved) => {
+            if (active && resolved) setLoaded({ key: k, url: resolved });
+        });
+        return () => {
+            active = false;
+            release(projectId, assetId);
+        };
+    }, [projectId, assetId]);
+
+    return key && loaded?.key === key ? loaded.url : null;
+}
diff --git a/src/lib/import/import-project.ts b/src/lib/import/import-project.ts
index 2bdf31b3..4e9c3321 100644
--- a/src/lib/import/import-project.ts
+++ b/src/lib/import/import-project.ts
@@ -3,14 +3,11 @@
  * Creates remote projects for logged-in users, local projects for offline/desktop.
  */
 
-import { LayoutData, ProjectData, ProjectMetadata, ProjectState } from "@src/lib/project/project-state";
+import { ProjectData, ProjectState, applyProjectData } from "@src/lib/project/project-state";
 import { CURRENT_PROJECT_VERSION } from "@src/lib/project/migrations/project-migrations";
 import { getAdapterByFilename } from "@src/lib/adapters/registry";
 import { createCachedProject, createCachedProjectWithId } from "@src/lib/persistence/storage-provider/local-persistence";
 import { writeYjsDocumentLocally } from "@src/lib/persistence/y-local-provider";
-import { prosemirrorJSONToYXmlFragment } from "y-prosemirror";
-import { ScreenplaySchema } from "@src/lib/screenplay/editor";
-import { TitlePageSchema } from "@src/lib/titlepage/editor";
 import { Editor } from "@tiptap/react";
 import { createProject } from "@src/lib/utils/requests";
 import { CreateProjectBody } from "@src/lib/utils/api-bodies";
@@ -74,62 +71,18 @@ export async function importFileIntoProject(
 async function createLocalYjsDocument(projectId: string, projectData: ProjectData): Promise<void> {
     const ydoc = new ProjectState();
 
-    ydoc.transact(() => {
-        // Screenplay fragment
-        const screenplayFragment = ydoc.screenplayFragment();
-        prosemirrorJSONToYXmlFragment(
-            ScreenplaySchema,
-            { type: "doc", content: projectData.screenplay },
-            screenplayFragment,
-        );
-
-        // Titlepage fragment
-        if (projectData.titlepage) {
-            const titlepageFragment = ydoc.titlepageFragment();
-            prosemirrorJSONToYXmlFragment(
-                TitlePageSchema,
-                { type: "doc", content: projectData.titlepage },
-                titlepageFragment,
-            );
-        }
-
-        // Maps
-        const metadataMap = ydoc.metadata();
-        if (projectData.metadata) {
-            Object.entries(projectData.metadata).forEach(([key, value]) => metadataMap.set(key as keyof ProjectMetadata, value));
-        }
-        // Stamp the schema version: preserves the imported file's version if it
-        // had one (so future-version files surface a migration error on open),
-        // otherwise marks the doc as current so it skips migration on first load.
-        if (metadataMap.get("version") === undefined) {
-            metadataMap.set("version", CURRENT_PROJECT_VERSION);
-        }
-
-        if (projectData.characters) {
-            const charactersMap = ydoc.characters();
-            Object.entries(projectData.characters).forEach(([key, value]) => charactersMap.set(key, value));
-        }
-
-        if (projectData.locations) {
-            const locationsMap = ydoc.locations();
-            Object.entries(projectData.locations).forEach(([key, value]) => locationsMap.set(key, value));
-        }
-
-        if (projectData.scenes) {
-            const scenesMap = ydoc.scenes();
-            Object.entries(projectData.scenes).forEach(([key, value]) => scenesMap.set(key, value));
-        }
-
-        if (projectData.layout) {
-            const layoutMap = ydoc.layout();
-            Object.entries(projectData.layout).forEach(([key, value]) => layoutMap.set(key as keyof LayoutData, value));
-        }
-
-        if (projectData.comments) {
-            const commentsMap = ydoc.comments();
-            Object.entries(projectData.comments).forEach(([key, value]) => commentsMap.set(key, value));
-        }
-    });
+    // Write every map and fragment the adapter produced. Adapters that only
+    // parse a screenplay (fountain/fdx) supply a partial `ProjectData`;
+    // `applyProjectData` ignores the keys they leave out.
+    applyProjectData(ydoc, projectData);
+
+    // Stamp the schema version: preserves the imported file's version if it had
+    // one (so future-version files surface a migration error on open), otherwise
+    // marks the doc as current so it skips migration on first load.
+    const metadataMap = ydoc.metadata();
+    if (metadataMap.get("version") === undefined) {
+        ydoc.transact(() => metadataMap.set("version", CURRENT_PROJECT_VERSION));
+    }
 
     await writeYjsDocumentLocally(projectId, ydoc);
     ydoc.destroy();
diff --git a/src/lib/persistence/storage-provider/indexeddb-storage-provider.ts b/src/lib/persistence/storage-provider/indexeddb-storage-provider.ts
index 04d37191..28443517 100644
--- a/src/lib/persistence/storage-provider/indexeddb-storage-provider.ts
+++ b/src/lib/persistence/storage-provider/indexeddb-storage-provider.ts
@@ -7,8 +7,12 @@
  */
 
 import type { InstalledDictionary, UserSettings } from "@src/lib/utils/types";
-import { CachedProject, ProjectEntryInput, StorageProvider } from "./storage-provider";
-import { CURRENT_STORE_VERSION, STORE_NAMES } from "./migrations/store-migrations";
+import { CachedProject, ProjectEntryInput, StorageProvider, StoredAsset } from "./storage-provider";
+import {
+    ASSETS_BY_PROJECT_INDEX,
+    CURRENT_STORE_VERSION,
+    STORE_NAMES,
+} from "./migrations/store-migrations";
 import { runStoreMigrations } from "./migrations/store-migration-runner";
 import { StoreVersionTooNewError } from "./migrations/errors";
 
@@ -17,8 +21,12 @@ const PROJECTS_STORE = STORE_NAMES.PROJECTS;
 const SETTINGS_STORE = STORE_NAMES.SETTINGS;
 const DICTIONARIES_STORE = STORE_NAMES.DICTIONARIES;
 const MIGRATION_BACKUPS_STORE = STORE_NAMES.MIGRATION_BACKUPS;
+const ASSETS_STORE = STORE_NAMES.ASSETS;
 const SETTINGS_KEY = "global";
 
+/** Primary key for an asset record: `${projectId}/${hash}`. */
+const assetKey = (projectId: string, hash: string): string => `${projectId}/${hash}`;
+
 interface BrowserStoredProject {
     id: string;
     title: string;
@@ -340,4 +348,113 @@ export class IndexedDBStorageProvider implements StorageProvider {
             tx.onerror = () => reject(tx.error);
         });
     }
+
+    // ── Assets ────────────────────────────────────────────────────────────────
+
+    async putAsset(asset: StoredAsset): Promise<void> {
+        const db = await getBrowserDb();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(ASSETS_STORE, "readwrite");
+            tx.objectStore(ASSETS_STORE).put(asset);
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+
+    async hasAsset(projectId: string, hash: string): Promise<boolean> {
+        const db = await getBrowserDb();
+        return new Promise((resolve, reject) => {
+            const req = db
+                .transaction(ASSETS_STORE, "readonly")
+                .objectStore(ASSETS_STORE)
+                .getKey(assetKey(projectId, hash));
+            req.onsuccess = () => resolve(req.result !== undefined);
+            req.onerror = () => reject(req.error);
+        });
+    }
+
+    async getAsset(projectId: string, hash: string): Promise<StoredAsset | null> {
+        const db = await getBrowserDb();
+        return new Promise((resolve, reject) => {
+            const req = db
+                .transaction(ASSETS_STORE, "readonly")
+                .objectStore(ASSETS_STORE)
+                .get(assetKey(projectId, hash));
+            req.onsuccess = () => resolve((req.result as StoredAsset | undefined) ?? null);
+            req.onerror = () => reject(req.error);
+        });
+    }
+
+    async listAssetHashes(projectId: string): Promise<string[]> {
+        const db = await getBrowserDb();
+        return new Promise((resolve, reject) => {
+            const hashes: string[] = [];
+            const index = db
+                .transaction(ASSETS_STORE, "readonly")
+                .objectStore(ASSETS_STORE)
+                .index(ASSETS_BY_PROJECT_INDEX);
+            const req = index.openCursor(IDBKeyRange.only(projectId));
+            req.onsuccess = () => {
+                const cursor = req.result;
+                if (cursor) {
+                    hashes.push((cursor.value as StoredAsset).hash);
+                    cursor.continue();
+                } else {
+                    resolve(hashes);
+                }
+            };
+            req.onerror = () => reject(req.error);
+        });
+    }
+
+    async deleteAsset(projectId: string, hash: string): Promise<void> {
+        const db = await getBrowserDb();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(ASSETS_STORE, "readwrite");
+            tx.objectStore(ASSETS_STORE).delete(assetKey(projectId, hash));
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+
+    async deleteProjectAssets(projectId: string): Promise<void> {
+        const db = await getBrowserDb();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(ASSETS_STORE, "readwrite");
+            const store = tx.objectStore(ASSETS_STORE);
+            const req = store.index(ASSETS_BY_PROJECT_INDEX).openCursor(IDBKeyRange.only(projectId));
+            req.onsuccess = () => {
+                const cursor = req.result;
+                if (cursor) {
+                    cursor.delete();
+                    cursor.continue();
+                }
+            };
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+
+    async copyProjectAssets(fromProjectId: string, toProjectId: string): Promise<void> {
+        const db = await getBrowserDb();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(ASSETS_STORE, "readwrite");
+            const store = tx.objectStore(ASSETS_STORE);
+            const req = store.index(ASSETS_BY_PROJECT_INDEX).openCursor(IDBKeyRange.only(fromProjectId));
+            req.onsuccess = () => {
+                const cursor = req.result;
+                if (cursor) {
+                    const src = cursor.value as StoredAsset;
+                    store.put({
+                        ...src,
+                        key: assetKey(toProjectId, src.hash),
+                        projectId: toProjectId,
+                    });
+                    cursor.continue();
+                }
+            };
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+        });
+    }
 }
diff --git a/src/lib/persistence/storage-provider/local-persistence.ts b/src/lib/persistence/storage-provider/local-persistence.ts
index 1162f684..5f088766 100644
--- a/src/lib/persistence/storage-provider/local-persistence.ts
+++ b/src/lib/persistence/storage-provider/local-persistence.ts
@@ -58,7 +58,11 @@ export async function touchCachedProject(id: string): Promise<void> {
 }
 
 export async function deleteCachedProject(id: string): Promise<void> {
-    return (await getStorageProvider()).delete(id);
+    const provider = await getStorageProvider();
+    await provider.delete(id);
+    // Reclaim the project's binary assets (board images). This is the chokepoint
+    // every deletion flow funnels through (DangerZone + discardCloudProjectData).
+    await provider.deleteProjectAssets(id);
 }
 
 export async function isCachedProject(projectId: string): Promise<boolean> {
@@ -124,6 +128,10 @@ export async function migrateToCachedProject(
     newProvider.destroy();
     newDoc.destroy();
 
+    // 3b. Copy the project's binary assets to the new id (they are keyed by
+    // projectId, so the copied board cards would otherwise reference nothing).
+    await (await getStorageProvider()).copyProjectAssets(oldProjectId, newProject.id);
+
     // 4. Clean up old project data
     await discardCloudProjectData(oldProjectId);
 
diff --git a/src/lib/persistence/storage-provider/migrations/store-migrations.ts b/src/lib/persistence/storage-provider/migrations/store-migrations.ts
index c82909ef..3fbc4130 100644
--- a/src/lib/persistence/storage-provider/migrations/store-migrations.ts
+++ b/src/lib/persistence/storage-provider/migrations/store-migrations.ts
@@ -25,17 +25,23 @@ export const STORE_NAMES = {
     SETTINGS: "settings",
     DICTIONARIES: "dictionaries",
     MIGRATION_BACKUPS: "migration_backups",
+    ASSETS: "assets",
 } as const;
 
+/** Index on the `assets` store used to list/delete every asset of a project. */
+export const ASSETS_BY_PROJECT_INDEX = "byProject";
+
 /**
- * v0 → v1: baseline. Creates the three original stores. This is the schema
- * shipped before the migration framework existed; users already on v1 skip
- * this step.
+ * v0 → v1: baseline. Creates the original stores, including the binary
+ * `assets` store (board image resources, content-addressed by SHA-256, keyed
+ * `${projectId}/${hash}` with a `byProject` index). The app isn't released
+ * yet, so this is folded into the baseline rather than a separate migration
+ * step — existing local databases should just be reset.
  */
 const baselineV1: StoreMigration = {
     from: 0,
     to: 1,
-    description: "Baseline: create cached_projects, settings, dictionaries",
+    description: "Baseline: create cached_projects, settings, dictionaries, assets",
     run: (db) => {
         if (!db.objectStoreNames.contains(STORE_NAMES.PROJECTS)) {
             db.createObjectStore(STORE_NAMES.PROJECTS, { keyPath: "id" });
@@ -46,6 +52,10 @@ const baselineV1: StoreMigration = {
         if (!db.objectStoreNames.contains(STORE_NAMES.DICTIONARIES)) {
             db.createObjectStore(STORE_NAMES.DICTIONARIES, { keyPath: "code" });
         }
+        if (!db.objectStoreNames.contains(STORE_NAMES.ASSETS)) {
+            const assets = db.createObjectStore(STORE_NAMES.ASSETS, { keyPath: "key" });
+            assets.createIndex(ASSETS_BY_PROJECT_INDEX, "projectId", { unique: false });
+        }
     },
 };
 
@@ -65,7 +75,10 @@ const addMigrationBackupsStore: StoreMigration = {
     },
 };
 
-export const STORE_MIGRATIONS: StoreMigration[] = [baselineV1, addMigrationBackupsStore];
+export const STORE_MIGRATIONS: StoreMigration[] = [
+    baselineV1,
+    addMigrationBackupsStore,
+];
 
 export const CURRENT_STORE_VERSION =
     STORE_MIGRATIONS.length === 0 ? 1 : STORE_MIGRATIONS[STORE_MIGRATIONS.length - 1].to;
diff --git a/src/lib/persistence/storage-provider/storage-provider.ts b/src/lib/persistence/storage-provider/storage-provider.ts
index 4e5d4649..e5fe5023 100644
--- a/src/lib/persistence/storage-provider/storage-provider.ts
+++ b/src/lib/persistence/storage-provider/storage-provider.ts
@@ -25,6 +25,29 @@ export interface ProjectEntryInput {
     updatedAt: Date;
 }
 
+/**
+ * A binary resource (currently board images) stored locally, decoupled from the
+ * Yjs document. Content-addressed by SHA-256 so the same bytes are stored once.
+ * Scoped per project: the primary key is `${projectId}/${hash}`.
+ */
+export interface StoredAsset {
+    /** Primary key: `${projectId}/${hash}`. */
+    key: string;
+    /** Owning project id (indexed, for per-project list/delete). */
+    projectId: string;
+    /** SHA-256 hex digest of `blob` — this is the assetId referenced by cards. */
+    hash: string;
+    mime: string;
+    size: number;
+    /** Intrinsic pixel dimensions, used to size the card on first drop. */
+    width: number;
+    height: number;
+    /** Raw image bytes. Stored as ArrayBuffer (not Blob) for WebKit IndexedDB
+     *  compatibility, matching the dictionaries/migration-backup stores. */
+    data: ArrayBuffer;
+    createdAt: number;
+}
+
 export interface StorageProvider {
     // Project CRUD
     createProject(id: string, title: string, description?: string, synced?: boolean, author?: string): Promise<void>;
@@ -54,6 +77,18 @@ export interface StorageProvider {
     saveMigrationBackup(projectId: string, snapshot: Uint8Array, fromVersion: number): Promise<void>;
     loadMigrationBackup(projectId: string): Promise<{ snapshot: Uint8Array; fromVersion: number } | null>;
     clearMigrationBackup(projectId: string): Promise<void>;
+
+    // Assets: content-addressed binary resources (board images), per project.
+    putAsset(asset: StoredAsset): Promise<void>;
+    hasAsset(projectId: string, hash: string): Promise<boolean>;
+    getAsset(projectId: string, hash: string): Promise<StoredAsset | null>;
+    /** SHA-256 hashes of every asset stored for a project. */
+    listAssetHashes(projectId: string): Promise<string[]>;
+    deleteAsset(projectId: string, hash: string): Promise<void>;
+    /** Remove every asset belonging to a project (called on project deletion). */
+    deleteProjectAssets(projectId: string): Promise<void>;
+    /** Duplicate every asset of `fromProjectId` under `toProjectId` (id-changing copy). */
+    copyProjectAssets(fromProjectId: string, toProjectId: string): Promise<void>;
 }
 
 // Singleton cache
diff --git a/src/lib/project/project-doc.ts b/src/lib/project/project-doc.ts
index 596b2692..8c20cd45 100644
--- a/src/lib/project/project-doc.ts
+++ b/src/lib/project/project-doc.ts
@@ -155,6 +155,14 @@ export interface BoardCardData {
     y: number;
     width: number;
     height: number;
+    /** Card kind. `undefined`/"text" is the default note card; "image" renders a resource. */
+    type?: "text" | "image";
+    /**
+     * For `type: "image"` cards: the SHA-256 hash of the source image, which is
+     * stored separately in IndexedDB (decoupled from Yjs). The bytes never live
+     * in the document — only this reference does.
+     */
+    assetId?: string;
 }
 
 export interface BoardArrowData {
@@ -255,6 +263,14 @@ export type ProjectData = {
     production: ProductionData;
     comments?: Record<string, Comment>;
     shelf?: Record<string, ShelfEntry>;
+    /** Per-project custom dictionary words (keys are words, values are true). */
+    dictionary?: Record<string, boolean>;
+    /** Content of every `editor` document node's fragment, keyed by node id. */
+    documentContent?: Record<string, JSONContent[]>;
+    /** Board data (cards + arrows) for every `board` node, keyed by node id. */
+    boards?: Record<string, BoardData>;
+    /** Content of every shelf version, keyed by `${nodeId}::${versionId}`. */
+    shelfContent?: Record<string, JSONContent[]>;
 };
 
 /**
diff --git a/src/lib/project/project-state.ts b/src/lib/project/project-state.ts
index d033c1c7..120c06ef 100644
--- a/src/lib/project/project-state.ts
+++ b/src/lib/project/project-state.ts
@@ -9,11 +9,12 @@ import * as Y from "yjs";
 import type { ThrottledWebsocketProvider } from "../cloud/utils";
 import { ScreenplaySchema } from "../screenplay/editor";
 import { TitlePageSchema } from "../titlepage/editor";
-import { yXmlFragmentToProseMirrorRootNode } from "y-prosemirror";
+import { prosemirrorJSONToYXmlFragment, yXmlFragmentToProseMirrorRootNode } from "y-prosemirror";
 import type { YjsLocalProvider } from "../persistence/y-local-provider";
 import type { ProjectMigrationOutcome } from "./migrations/project-migration-runner";
 
 import { ProjectState } from "./project-doc";
+import type { BoardData, ProjectData } from "./project-doc";
 
 // Re-export all schema types & the class so existing consumers continue to
 // import from "@src/lib/project/project-state" without changes.
@@ -141,6 +142,190 @@ export const titlepageOf = (ydoc: ProjectState): JSONContent[] => {
     return proseMirrorNode.content.toJSON() as JSONContent[];
 };
 
+// -------------------------------- //
+//   FULL PROJECT (DE)SERIALIZATION //
+// -------------------------------- //
+
+/** Convert a screenplay-schema Y.XmlFragment (editor docs, shelf versions) to JSON. */
+const fragmentContentOf = (fragment: Y.XmlFragment): JSONContent[] =>
+    yXmlFragmentToProseMirrorRootNode(fragment, ScreenplaySchema).content.toJSON() as JSONContent[];
+
+/** Content of every `editor` document node's fragment, keyed by node id. */
+const documentContentOf = (ydoc: ProjectState): Record<string, JSONContent[]> => {
+    const result: Record<string, JSONContent[]> = {};
+    ydoc.documents().forEach((node) => {
+        if (node.type === "editor") result[node.id] = fragmentContentOf(ydoc.documentFragment(node.id));
+    });
+    return result;
+};
+
+/** Board data (cards + arrows) for every `board` node, keyed by node id. */
+const boardsOf = (ydoc: ProjectState): Record<string, BoardData> => {
+    const result: Record<string, BoardData> = {};
+    ydoc.documents().forEach((node) => {
+        if (node.type === "board") result[node.id] = ydoc.boardData(node.id).toJSON();
+    });
+    return result;
+};
+
+/** Content of every shelf version, keyed by `${nodeId}::${versionId}`. */
+const shelfContentOf = (ydoc: ProjectState): Record<string, JSONContent[]> => {
+    const result: Record<string, JSONContent[]> = {};
+    ydoc.shelf().forEach((entry, nodeId) => {
+        for (const version of entry.versions) {
+            result[`${nodeId}::${version.id}`] = fragmentContentOf(ydoc.shelfFragment(nodeId, version.id));
+        }
+    });
+    return result;
+};
+
+/**
+ * Serialize the entire project Y.Doc to a plain `ProjectData` — every map, both
+ * screenplay/title-page fragments, and the dynamic per-document / per-board /
+ * per-shelf-version content. Browser-only (uses ProseMirror conversion).
+ */
+export const projectDataOf = (ydoc: ProjectState): ProjectData => ({
+    screenplay: screenplayOf(ydoc),
+    titlepage: titlepageOf(ydoc),
+    metadata: ydoc.metadata().toJSON(),
+    characters: ydoc.characters().toJSON(),
+    scenes: ydoc.scenes().toJSON(),
+    pages: ydoc.pages().toJSON(),
+    locations: ydoc.locations().toJSON(),
+    layout: ydoc.layout().toJSON(),
+    production: ydoc.production().toJSON(),
+    comments: ydoc.comments().toJSON(),
+    documents: ydoc.documents().toJSON(),
+    outline: ydoc.outline().toJSON(),
+    shelf: ydoc.shelf().toJSON(),
+    dictionary: ydoc.dictionary().toJSON(),
+    documentContent: documentContentOf(ydoc),
+    boards: boardsOf(ydoc),
+    shelfContent: shelfContentOf(ydoc),
+});
+
+/** Loosened Y.Map view used to bulk-write a record into a typed/plain map. */
+const asMap = (m: object): Y.Map<unknown> => m as unknown as Y.Map<unknown>;
+
+const fillMap = (map: Y.Map<unknown>, record: Record<string, unknown> | undefined): void => {
+    if (!record) return;
+    for (const [key, value] of Object.entries(record)) map.set(key, value);
+};
+
+/**
+ * Write a (possibly partial) `ProjectData` into `ydoc`. Additive — it sets the
+ * keys/fragments present in `data` without removing what is already there, so a
+ * caller that needs a clean replace should `clearProjectData(ydoc)` first.
+ * Browser-only (rebuilds fragments via ProseMirror).
+ */
+export const applyProjectData = (ydoc: ProjectState, data: Partial<ProjectData>): void => {
+    ydoc.transact(() => {
+        if (data.screenplay && data.screenplay.length > 0) {
+            prosemirrorJSONToYXmlFragment(
+                ScreenplaySchema,
+                { type: "doc", content: data.screenplay },
+                ydoc.screenplayFragment(),
+            );
+        }
+        if (data.titlepage && data.titlepage.length > 0) {
+            prosemirrorJSONToYXmlFragment(
+                TitlePageSchema,
+                { type: "doc", content: data.titlepage },
+                ydoc.titlepageFragment(),
+            );
+        }
+
+        fillMap(asMap(ydoc.metadata()), data.metadata);
+        fillMap(asMap(ydoc.characters()), data.characters);
+        fillMap(asMap(ydoc.locations()), data.locations);
+        fillMap(asMap(ydoc.scenes()), data.scenes);
+        fillMap(asMap(ydoc.pages()), data.pages);
+        fillMap(asMap(ydoc.layout()), data.layout);
+        fillMap(asMap(ydoc.production()), data.production);
+        fillMap(asMap(ydoc.comments()), data.comments);
+        fillMap(asMap(ydoc.documents()), data.documents);
+        fillMap(asMap(ydoc.outline()), data.outline);
+        fillMap(asMap(ydoc.shelf()), data.shelf);
+        fillMap(asMap(ydoc.dictionary()), data.dictionary);
+
+        if (data.documentContent) {
+            for (const [id, content] of Object.entries(data.documentContent)) {
+                if (content.length === 0) continue;
+                prosemirrorJSONToYXmlFragment(
+                    ScreenplaySchema,
+                    { type: "doc", content },
+                    ydoc.documentFragment(id),
+                );
+            }
+        }
+        if (data.boards) {
+            for (const [id, board] of Object.entries(data.boards)) {
+                const map = ydoc.boardData(id);
+                for (const [key, value] of Object.entries(board)) {
+                    map.set(key as keyof BoardData, value as BoardData[keyof BoardData]);
+                }
+            }
+        }
+        if (data.shelfContent) {
+            for (const [key, content] of Object.entries(data.shelfContent)) {
+                if (content.length === 0) continue;
+                const sep = key.indexOf("::");
+                const nodeId = key.slice(0, sep);
+                const versionId = key.slice(sep + 2);
+                prosemirrorJSONToYXmlFragment(
+                    ScreenplaySchema,
+                    { type: "doc", content },
+                    ydoc.shelfFragment(nodeId, versionId),
+                );
+            }
+        }
+    });
+};
+
+/**
+ * Remove every shared type's content from `ydoc` — both fragments, all maps, and
+ * the dynamic per-document / per-board / per-shelf fragments — so an imported
+ * state can fully replace the existing project instead of merging with it.
+ */
+export const clearProjectData = (ydoc: ProjectState): void => {
+    ydoc.transact(() => {
+        const screenplay = ydoc.screenplayFragment();
+        if (screenplay.length > 0) screenplay.delete(0, screenplay.length);
+        const titlepage = ydoc.titlepageFragment();
+        if (titlepage.length > 0) titlepage.delete(0, titlepage.length);
+
+        // Clear dynamic fragments before their owning maps, while the nodes that
+        // reference them can still be enumerated.
+        ydoc.documents().forEach((node) => {
+            if (node.type === "editor") {
+                const frag = ydoc.documentFragment(node.id);
+                if (frag.length > 0) frag.delete(0, frag.length);
+            } else if (node.type === "board") {
+                ydoc.boardData(node.id).clear();
+            }
+        });
+        ydoc.shelf().forEach((entry, nodeId) => {
+            for (const version of entry.versions) {
+                const frag = ydoc.shelfFragment(nodeId, version.id);
+                if (frag.length > 0) frag.delete(0, frag.length);
+            }
+        });
+
+        ydoc.metadata().clear();
+        ydoc.characters().clear();
+        ydoc.scenes().clear();
+        ydoc.pages().clear();
+        ydoc.locations().clear();
+        ydoc.layout().clear();
+        ydoc.production().clear();
+        ydoc.comments().clear();
+        ydoc.documents().clear();
+        ydoc.outline().clear();
+        ydoc.shelf().clear();
+        ydoc.dictionary().clear();
+    });
+};
+
 // -------------------------------- //
 //        SESSION CACHE             //
 // -------------------------------- //
diff --git a/src/tests/assets/assets.test.ts b/src/tests/assets/assets.test.ts
new file mode 100644
index 00000000..084b6882
--- /dev/null
+++ b/src/tests/assets/assets.test.ts
@@ -0,0 +1,183 @@
+import { beforeAll, describe, it, expect } from "vitest";
+
+import { sha256Hex } from "@src/lib/assets/asset-hash";
+import { importImageFile, loadAssetObjectUrl } from "@src/lib/assets/asset-store";
+import { collectReferencedHashes, gcProjectAssets } from "@src/lib/assets/asset-gc";
+import {
+    getStorageProvider,
+    type StoredAsset,
+} from "@src/lib/persistence/storage-provider/storage-provider";
+import { ProjectState } from "@src/lib/project/project-state";
+import { createProjectRepository } from "@src/lib/project/project-repository";
+
+const pid = () => `test-${Math.random().toString(36).slice(2)}`;
+
+// The `assets` store is part of the baseline schema. A browser profile carrying
+// a stale `scriptio-local` from before the store existed would lack it (we don't
+// bump the store version — greenfield assumption), so reset it for a clean run.
+beforeAll(async () => {
+    await new Promise<void>((resolve) => {
+        const req = indexedDB.deleteDatabase("scriptio-local");
+        req.onsuccess = () => resolve();
+        req.onerror = () => resolve();
+        req.onblocked = () => resolve();
+    });
+});
+
+/** Base fields shared by the board cards used in GC tests. */
+const cardBase = { title: "", description: "", color: "", x: 0, y: 0, width: 1, height: 1 };
+
+async function putDummyAsset(projectId: string, hash: string): Promise<void> {
+    const provider = await getStorageProvider();
+    await provider.putAsset({
+        key: `${projectId}/${hash}`,
+        projectId,
+        hash,
+        mime: "image/png",
+        size: 3,
+        width: 1,
+        height: 1,
+        data: new TextEncoder().encode("abc").buffer as ArrayBuffer,
+        createdAt: Date.now(),
+    });
+}
+
+/** A real, decodable PNG so importImageFile's intrinsic-size decode succeeds. */
+async function makePngFile(name: string, w: number, h: number, fill: string): Promise<File> {
+    const canvas = document.createElement("canvas");
+    canvas.width = w;
+    canvas.height = h;
+    const ctx = canvas.getContext("2d")!;
+    ctx.fillStyle = fill;
+    ctx.fillRect(0, 0, w, h);
+    const blob = await new Promise<Blob>((resolve) => canvas.toBlob((b) => resolve(b!), "image/png"));
+    return new File([blob], name, { type: "image/png" });
+}
+
+describe("sha256Hex", () => {
+    it("is deterministic and matches the known vector for 'abc'", async () => {
+        const enc = (s: string) => new TextEncoder().encode(s).buffer as ArrayBuffer;
+        expect(await sha256Hex(enc("hello"))).toBe(await sha256Hex(enc("hello")));
+        expect(await sha256Hex(enc("hello"))).not.toBe(await sha256Hex(enc("world")));
+        expect(await sha256Hex(enc("abc"))).toBe(
+            "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
+        );
+    });
+});
+
+describe("asset storage provider", () => {
+    it("stores, lists, copies and deletes assets scoped per project", async () => {
+        const provider = await getStorageProvider();
+        const p1 = pid();
+        const p2 = pid();
+
+        const asset: StoredAsset = {
+            key: `${p1}/h1`,
+            projectId: p1,
+            hash: "h1",
+            mime: "image/png",
+            size: 3,
+            width: 2,
+            height: 4,
+            data: new TextEncoder().encode("abc").buffer as ArrayBuffer,
+            createdAt: Date.now(),
+        };
+        await provider.putAsset(asset);
+
+        expect(await provider.hasAsset(p1, "h1")).toBe(true);
+        expect(await provider.hasAsset(p1, "missing")).toBe(false);
+        expect((await provider.getAsset(p1, "h1"))?.height).toBe(4);
+        expect(await provider.listAssetHashes(p1)).toEqual(["h1"]);
+
+        // copy isolates by project key
+        await provider.copyProjectAssets(p1, p2);
+        expect(await provider.hasAsset(p2, "h1")).toBe(true);
+
+        // deleting one project leaves the other intact
+        await provider.deleteProjectAssets(p1);
+        expect(await provider.listAssetHashes(p1)).toEqual([]);
+        expect(await provider.hasAsset(p2, "h1")).toBe(true);
+
+        await provider.deleteProjectAssets(p2);
+    });
+});
+
+describe("importImageFile", () => {
+    it("dedups identical bytes and captures intrinsic dimensions", async () => {
+        const provider = await getStorageProvider();
+        const p = pid();
+        const file = await makePngFile("x.png", 20, 10, "#f00");
+
+        const first = await importImageFile(p, file);
+        expect(first.width).toBe(20);
+        expect(first.height).toBe(10);
+
+        const second = await importImageFile(p, file);
+        expect(second.hash).toBe(first.hash);
+        // Still exactly one stored record despite two imports.
+        expect(await provider.listAssetHashes(p)).toEqual([first.hash]);
+
+        const url = await loadAssetObjectUrl(p, first.hash);
+        expect(url).toMatch(/^blob:/);
+        if (url) URL.revokeObjectURL(url);
+
+        await provider.deleteProjectAssets(p);
+    });
+});
+
+describe("asset GC (reconcile from doc)", () => {
+    it("collects image assetIds across every board, ignoring text cards", () => {
+        const ydoc = new ProjectState();
+        const repo = createProjectRepository(ydoc)!;
+        const b1 = repo.createBoardDocument("B1");
+        const b2 = repo.createBoardDocument("B2");
+
+        ydoc.boardData(b1).set(
+            "cards",
+            JSON.stringify([
+                { id: "c1", type: "image", assetId: "A", ...cardBase },
+                { id: "c2", ...cardBase }, // plain text card — no assetId
+            ]),
+        );
+        ydoc.boardData(b2).set(
+            "cards",
+            JSON.stringify([{ id: "c3", type: "image", assetId: "B", ...cardBase }]),
+        );
+
+        expect(collectReferencedHashes(ydoc)).toEqual(new Set(["A", "B"]));
+        ydoc.destroy();
+    });
+
+    it("deletes only unreferenced assets, project-wide", async () => {
+        const provider = await getStorageProvider();
+        const p = pid();
+        const ydoc = new ProjectState();
+        const repo = createProjectRepository(ydoc)!;
+        const board = repo.createBoardDocument("B1");
+
+        ydoc.boardData(board).set(
+            "cards",
+            JSON.stringify([
+                { id: "c1", type: "image", assetId: "A", ...cardBase },
+                { id: "c2", type: "image", assetId: "B", ...cardBase },
+            ]),
+        );
+        await putDummyAsset(p, "A");
+        await putDummyAsset(p, "B");
+        await putDummyAsset(p, "C"); // never referenced
+
+        await gcProjectAssets(p, ydoc);
+        expect((await provider.listAssetHashes(p)).sort()).toEqual(["A", "B"]);
+
+        // Drop the only card referencing A → A becomes collectable, B stays.
+        ydoc.boardData(board).set(
+            "cards",
+            JSON.stringify([{ id: "c2", type: "image", assetId: "B", ...cardBase }]),
+        );
+        await gcProjectAssets(p, ydoc);
+        expect(await provider.listAssetHashes(p)).toEqual(["B"]);
+
+        await provider.deleteProjectAssets(p);
+        ydoc.destroy();
+    });
+});
diff --git a/src/tests/migrations/store-migration-runner.test.ts b/src/tests/migrations/store-migration-runner.test.ts
index 0bba24ca..e196d899 100644
--- a/src/tests/migrations/store-migration-runner.test.ts
+++ b/src/tests/migrations/store-migration-runner.test.ts
@@ -73,6 +73,7 @@ describe("runStoreMigrations", () => {
                 STORE_NAMES.SETTINGS,
                 STORE_NAMES.DICTIONARIES,
                 STORE_NAMES.MIGRATION_BACKUPS,
+                STORE_NAMES.ASSETS,
             ].sort(),
         );
         db.close();
diff --git a/src/tests/project/scriptio-roundtrip.test.ts b/src/tests/project/scriptio-roundtrip.test.ts
new file mode 100644
index 00000000..ea4269cd
--- /dev/null
+++ b/src/tests/project/scriptio-roundtrip.test.ts
@@ -0,0 +1,172 @@
+import { describe, expect, it } from "vitest";
+import { prosemirrorJSONToYXmlFragment } from "y-prosemirror";
+
+import {
+    ProjectState,
+    applyProjectData,
+    clearProjectData,
+    projectDataOf,
+} from "@src/lib/project/project-state";
+import { createProjectRepository } from "@src/lib/project/project-repository";
+import { ScreenplaySchema } from "@src/lib/screenplay/editor";
+import { ScriptioAdapter } from "@src/lib/adapters/scriptio/scriptio-adapter";
+
+const action = (id: string, text: string) => ({
+    type: "action",
+    attrs: { "data-id": id, class: "action" },
+    content: [{ type: "text", text }],
+});
+
+/**
+ * Build a project that exercises every shared type the adapter must preserve:
+ * screenplay + title-page fragments, all the metadata-ish maps, the document
+ * tree (folder / editor / board), an editor doc's own content, a board's data,
+ * the outline, a shelf entry with version content, and the custom dictionary.
+ */
+function buildPopulatedProject(): ProjectState {
+    const ydoc = new ProjectState();
+    const repo = createProjectRepository(ydoc)!;
+
+    repo.transact(() => {
+        // Screenplay
+        prosemirrorJSONToYXmlFragment(
+            ScreenplaySchema,
+            { type: "doc", content: [action("a1", "Hello world"), action("a2", "Second line")] },
+            ydoc.screenplayFragment(),
+        );
+
+        // Maps reachable through the repository
+        repo.setTitle("My Script");
+        repo.setAuthor("Ada");
+        ydoc.characters().set("c1", { name: "ALICE" } as never);
+        ydoc.locations().set("l1", { name: "OFFICE" } as never);
+        repo.upsertScene("s1", { synopsis: "Opening", color: "#ff0000" });
+        repo.upsertPage("p1", { splitOffset: 3 });
+        repo.setPageSize("A4" as never);
+        repo.setSceneLocking(true);
+        repo.setSkippedSceneLetters(["I", "O", "Q"]);
+        repo.addComment({ content: "note", resolved: false } as never);
+        ydoc.dictionary().set("zoetrope", true);
+    });
+
+    // Document tree: folder > editor doc + board
+    const folder = repo.createFolder("Act One");
+    const editorDoc = repo.createEditorDocument("Beat Sheet", folder);
+    const board = repo.createBoardDocument("Corkboard", folder);
+
+    // Editor doc content lives in its own fragment
+    repo.transact(() => {
+        prosemirrorJSONToYXmlFragment(
+            ScreenplaySchema,
+            { type: "doc", content: [action("b1", "Beat one")] },
+            ydoc.documentFragment(editorDoc),
+        );
+        ydoc.boardData(board).set("cards", JSON.stringify([{ id: "k1", title: "Idea" }]));
+        ydoc.boardData(board).set("arrows", JSON.stringify([]));
+    });
+
+    // Outline references the main screenplay
+    repo.addOutlineItem({
+        parentId: null,
+        source: "scene",
+        refDocId: "screenplay",
+        refId: "s1",
+        title: "Opening",
+        preview: "Hello world",
+    });
+
+    // Shelf entry with one version (writes a shelf_<node>_<version> fragment)
+    repo.shelveNode("s1", "Opening", "scene", [action("v1", "Shelved opening")]);
+
+    return ydoc;
+}
+
+const baseOptions = { title: "My Script", author: "Ada", includeNotes: false };
+
+async function exportBuffer(project: ProjectState, readable: boolean): Promise<ArrayBuffer> {
+    const adapter = new ScriptioAdapter();
+    const blob = await adapter.convertTo(project, { ...baseOptions, readable });
+    return blob.arrayBuffer();
+}
+
+/** Fields that should survive an export/import round trip untouched. */
+function snapshot(data: ReturnType<typeof projectDataOf>) {
+    return {
+        screenplay: data.screenplay,
+        titlepage: data.titlepage,
+        metadata: data.metadata,
+        characters: data.characters,
+        scenes: data.scenes,
+        pages: data.pages,
+        locations: data.locations,
+        layout: data.layout,
+        production: data.production,
+        comments: data.comments,
+        documents: data.documents,
+        outline: data.outline,
+        shelf: data.shelf,
+        dictionary: data.dictionary,
+        documentContent: data.documentContent,
+        boards: data.boards,
+        shelfContent: data.shelfContent,
+    };
+}
+
+describe("scriptio adapter full round trip", () => {
+    for (const readable of [false, true]) {
+        const label = readable ? "readable JSON" : "binary";
+
+        it(`preserves every shared type (${label})`, async () => {
+            const original = buildPopulatedProject();
+            const before = snapshot(projectDataOf(original));
+
+            const adapter = new ScriptioAdapter();
+            const buffer = await exportBuffer(original, readable);
+            const parsed = adapter.convertFrom(buffer);
+
+            // Rebuild a fresh document from the parsed data, exactly like the
+            // new-project import path does.
+            const rebuilt = new ProjectState();
+            applyProjectData(rebuilt, parsed);
+            const after = snapshot(projectDataOf(rebuilt));
+
+            expect(after).toEqual(before);
+
+            original.destroy();
+            rebuilt.destroy();
+        });
+    }
+
+    it("clearProjectData wipes maps and dynamic fragments before a replace", () => {
+        const ydoc = buildPopulatedProject();
+        clearProjectData(ydoc);
+
+        expect(ydoc.documents().size).toBe(0);
+        expect(ydoc.shelf().size).toBe(0);
+        expect(ydoc.scenes().size).toBe(0);
+        expect(ydoc.dictionary().size).toBe(0);
+        expect(ydoc.screenplayFragment().length).toBe(0);
+
+        ydoc.destroy();
+    });
+
+    it("clear-then-apply replaces rather than merges (no stale entries)", () => {
+        const original = buildPopulatedProject();
+        const exported = projectDataOf(original);
+
+        // Target already holds unrelated data that must not survive the import.
+        const target = buildPopulatedProject();
+        target.scenes().set("stale", { synopsis: "old" } as never);
+        target.dictionary().set("stale-word", true);
+
+        clearProjectData(target);
+        applyProjectData(target, exported);
+
+        expect(target.scenes().has("stale")).toBe(false);
+        expect(target.dictionary().has("stale-word")).toBe(false);
+        expect(projectDataOf(target).scenes).toEqual(exported.scenes);
+
+        original.destroy();
+        target.destroy();
+    });
+});

From e31a258474c8b7f382e28d59e6cd359686b66d7f Mon Sep 17 00:00:00 2001
From: Lycoon <hugo.bois@hotmail.fr>
Date: Thu, 11 Jun 2026 01:41:03 +0200
Subject: [PATCH 2/3] changed .scriptio file format to zipped folder, fixed
 image handling in board canvas

---
 components/board/BoardCanvas.tsx              | 128 +++++--
 .../dashboard/project/ExportProject.tsx       |   3 +-
 src/lib/adapters/scriptio/scriptio-adapter.ts | 358 +++++++++++++-----
 src/lib/import/import-project.ts              |  25 +-
 src/tests/assets/assets.test.ts               |  70 ++++
 src/tests/project/scriptio-roundtrip.test.ts  |  47 +++
 6 files changed, 494 insertions(+), 137 deletions(-)

diff --git a/components/board/BoardCanvas.tsx b/components/board/BoardCanvas.tsx
index e83497f4..f10a263f 100644
--- a/components/board/BoardCanvas.tsx
+++ b/components/board/BoardCanvas.tsx
@@ -55,7 +55,9 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
         }
     }
     const [isCameraReady, setIsCameraReady] = useState(false);
-    const [connectingFrom, setConnectingFrom] = useState<{ cardId: string; side: string } | null>(null);
+    const [connectingFrom, setConnectingFrom] = useState<{ cardId: string; side: string } | null>(
+        null,
+    );
     const [connectingLine, setConnectingLine] = useState<{ x: number; y: number } | null>(null);
     const [selectedCardIds, setSelectedCardIds] = useState<Set<string>>(new Set());
     const [selectionRect, setSelectionRect] = useState<{
@@ -137,7 +139,8 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
             const cardsData = boardMap.get("cards");
             if (cardsData) {
                 try {
-                    const parsed = typeof cardsData === "string" ? JSON.parse(cardsData) : cardsData;
+                    const parsed =
+                        typeof cardsData === "string" ? JSON.parse(cardsData) : cardsData;
                     setCards(parsed);
 
                     // Center camera on first load
@@ -168,7 +171,8 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
             const arrowsData = boardMap.get("arrows");
             if (arrowsData) {
                 try {
-                    const parsed = typeof arrowsData === "string" ? JSON.parse(arrowsData) : arrowsData;
+                    const parsed =
+                        typeof arrowsData === "string" ? JSON.parse(arrowsData) : arrowsData;
                     setArrows(parsed);
                 } catch (e) {
                     console.error("[BoardCanvas] Failed to parse arrows:", e);
@@ -387,7 +391,12 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
                         const cardRight = card.x + card.width;
                         const cardBottom = card.y + card.height;
 
-                        if (card.x < right && cardRight > left && card.y < bottom && cardBottom > top) {
+                        if (
+                            card.x < right &&
+                            cardRight > left &&
+                            card.y < bottom &&
+                            cardBottom > top
+                        ) {
                             selected.add(card.id);
                         }
                     }
@@ -481,7 +490,8 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
             const x = (e.clientX - rect.left - offset.x) / scale;
             const y = (e.clientY - rect.top - offset.y) / scale;
 
-            const randomColor = DEFAULT_ITEM_COLORS[Math.floor(Math.random() * DEFAULT_ITEM_COLORS.length)];
+            const randomColor =
+                DEFAULT_ITEM_COLORS[Math.floor(Math.random() * DEFAULT_ITEM_COLORS.length)];
 
             const newCard: BoardCardData = {
                 id: uuidv7(),
@@ -526,7 +536,9 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
             setIsDraggingFile(false);
             if (isReadOnly || !projectId) return;
 
-            const files = Array.from(e.dataTransfer.files).filter((f) => f.type.startsWith("image/"));
+            const files = Array.from(e.dataTransfer.files).filter((f) =>
+                f.type.startsWith("image/"),
+            );
             if (files.length === 0) return;
 
             const container = containerRef.current;
@@ -559,11 +571,9 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
             }
             if (created.length === 0) return;
 
-            setCards((prev) => {
-                const next = [...prev, ...created];
-                saveCards(next);
-                return next;
-            });
+            const newCards = [...cardsRef.current, ...created];
+            setCards(newCards);
+            saveCards(newCards);
         },
         [isReadOnly, projectId, offset, scale, saveCards],
     );
@@ -579,11 +589,14 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
                     const dy = updatedCard.y - oldCard.y;
                     // Only apply multi-drag for position changes, not resize
                     if (dx !== 0 || dy !== 0) {
-                        const isResize = updatedCard.width !== oldCard.width || updatedCard.height !== oldCard.height;
+                        const isResize =
+                            updatedCard.width !== oldCard.width ||
+                            updatedCard.height !== oldCard.height;
                         if (!isResize) {
                             const newCards = cards.map((c) => {
                                 if (c.id === updatedCard.id) return updatedCard;
-                                if (selectedCardIds.has(c.id)) return { ...c, x: c.x + dx, y: c.y + dy };
+                                if (selectedCardIds.has(c.id))
+                                    return { ...c, x: c.x + dx, y: c.y + dy };
                                 return c;
                             });
                             setCards(newCards);
@@ -693,26 +706,32 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
     );
 
     // Get connection point position for a card
-    const getConnectionPoint = useCallback((card: BoardCardData, side: "top" | "right" | "bottom" | "left") => {
-        const centerX = card.x + card.width / 2;
-        const centerY = card.y + card.height / 2;
-
-        switch (side) {
-            case "top":
-                return { x: centerX, y: card.y };
-            case "right":
-                return { x: card.x + card.width, y: centerY };
-            case "bottom":
-                return { x: centerX, y: card.y + card.height };
-            case "left":
-                return { x: card.x, y: centerY };
-        }
-    }, []);
+    const getConnectionPoint = useCallback(
+        (card: BoardCardData, side: "top" | "right" | "bottom" | "left") => {
+            const centerX = card.x + card.width / 2;
+            const centerY = card.y + card.height / 2;
+
+            switch (side) {
+                case "top":
+                    return { x: centerX, y: card.y };
+                case "right":
+                    return { x: card.x + card.width, y: centerY };
+                case "bottom":
+                    return { x: centerX, y: card.y + card.height };
+                case "left":
+                    return { x: card.x, y: centerY };
+            }
+        },
+        [],
+    );
 
     // Calculate best connection points between two cards with perpendicular tangent directions
     const getArrowPoints = useCallback(
         (fromCard: BoardCardData, toCard: BoardCardData) => {
-            const fromCenter = { x: fromCard.x + fromCard.width / 2, y: fromCard.y + fromCard.height / 2 };
+            const fromCenter = {
+                x: fromCard.x + fromCard.width / 2,
+                y: fromCard.y + fromCard.height / 2,
+            };
             const toCenter = { x: toCard.x + toCard.width / 2, y: toCard.y + toCard.height / 2 };
 
             const dx = toCenter.x - fromCenter.x;
@@ -756,10 +775,13 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
     );
 
     // Handle starting a connection from a card
-    const handleStartConnection = useCallback((cardId: string, side: string, initialX: number, initialY: number) => {
-        setConnectingFrom({ cardId, side });
-        setConnectingLine({ x: initialX, y: initialY });
-    }, []);
+    const handleStartConnection = useCallback(
+        (cardId: string, side: string, initialX: number, initialY: number) => {
+            setConnectingFrom({ cardId, side });
+            setConnectingLine({ x: initialX, y: initialY });
+        },
+        [],
+    );
 
     // Handle mouse move while connecting
     const handleConnectionMouseMove = useCallback(
@@ -870,7 +892,10 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
                             const points = getArrowPoints(fromCard, toCard);
 
                             // Calculate distance for control point offset (perpendicular to border)
-                            const dist = Math.hypot(points.to.x - points.from.x, points.to.y - points.from.y);
+                            const dist = Math.hypot(
+                                points.to.x - points.from.x,
+                                points.to.y - points.from.y,
+                            );
                             const controlDist = Math.max(50, dist * 0.4);
 
                             // Control points extend perpendicular to the borders
@@ -886,10 +911,22 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
 
                             // Arrowhead points matching original marker shape: M 0 0 L 12 4 L 0 8 L 3 4 Z
                             // Back corners (perpendicular to arrow direction)
-                            const ax1 = points.to.x - arrowLength * Math.cos(angle) + arrowWidth * Math.sin(angle);
-                            const ay1 = points.to.y - arrowLength * Math.sin(angle) - arrowWidth * Math.cos(angle);
-                            const ax2 = points.to.x - arrowLength * Math.cos(angle) - arrowWidth * Math.sin(angle);
-                            const ay2 = points.to.y - arrowLength * Math.sin(angle) + arrowWidth * Math.cos(angle);
+                            const ax1 =
+                                points.to.x -
+                                arrowLength * Math.cos(angle) +
+                                arrowWidth * Math.sin(angle);
+                            const ay1 =
+                                points.to.y -
+                                arrowLength * Math.sin(angle) -
+                                arrowWidth * Math.cos(angle);
+                            const ax2 =
+                                points.to.x -
+                                arrowLength * Math.cos(angle) -
+                                arrowWidth * Math.sin(angle);
+                            const ay2 =
+                                points.to.y -
+                                arrowLength * Math.sin(angle) +
+                                arrowWidth * Math.cos(angle);
                             // Inner notch (25% from back toward tip)
                             const notchDepth = arrowLength * 0.75;
                             const axm = points.to.x - notchDepth * Math.cos(angle);
@@ -920,7 +957,11 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
                                         strokeWidth={2.5}
                                     />
                                     {/* Arrowhead */}
-                                    <path className={styles.arrow_head} d={arrowheadD} fill="var(--secondary-text)" />
+                                    <path
+                                        className={styles.arrow_head}
+                                        d={arrowheadD}
+                                        fill="var(--secondary-text)"
+                                    />
                                 </g>
                             );
                         })}
@@ -951,7 +992,10 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
                                 }
 
                                 const fromPoint = getConnectionPoint(fromCard, fromSide);
-                                const dist = Math.hypot(connectingLine.x - fromPoint.x, connectingLine.y - fromPoint.y);
+                                const dist = Math.hypot(
+                                    connectingLine.x - fromPoint.x,
+                                    connectingLine.y - fromPoint.y,
+                                );
                                 const controlDist = Math.max(30, dist * 0.3);
 
                                 const cx = fromPoint.x + fromDir.x * controlDist;
@@ -1020,7 +1064,9 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
                                         key={color}
                                         className={`${styles.context_menu_color_swatch} ${cardContextMenu.card.color === color ? styles.context_menu_color_swatch_active : ""}`}
                                         style={{ backgroundColor: color }}
-                                        onClick={() => handleChangeCardColor(cardContextMenu.card.id, color)}
+                                        onClick={() =>
+                                            handleChangeCardColor(cardContextMenu.card.id, color)
+                                        }
                                     />
                                 ))}
                             </div>
diff --git a/components/dashboard/project/ExportProject.tsx b/components/dashboard/project/ExportProject.tsx
index 7ceb25f1..affeb671 100644
--- a/components/dashboard/project/ExportProject.tsx
+++ b/components/dashboard/project/ExportProject.tsx
@@ -71,7 +71,7 @@ const ExportProject = () => {
 
         const confirmImport = async () => {
             try {
-                await importFileIntoProject(file, editor, titlePageEditor, repository);
+                await importFileIntoProject(file, projectId, editor, titlePageEditor, repository);
             } catch (error) {
                 console.error("Import failed:", error);
             }
@@ -127,6 +127,7 @@ const ExportProject = () => {
             const scriptioOptions: ScriptioExportOptions = {
                 ...baseOptions,
                 readable: readableExport,
+                projectId,
             };
             await adapter.export(ydoc, scriptioOptions as BaseExportOptions);
         } else {
diff --git a/src/lib/adapters/scriptio/scriptio-adapter.ts b/src/lib/adapters/scriptio/scriptio-adapter.ts
index 98245d85..bb415c9f 100644
--- a/src/lib/adapters/scriptio/scriptio-adapter.ts
+++ b/src/lib/adapters/scriptio/scriptio-adapter.ts
@@ -3,120 +3,301 @@ import { BaseExportOptions, ProjectAdapter } from "../screenplay-adapter";
 import { replaceScreenplay } from "../../screenplay/editor";
 import { Editor } from "@tiptap/react";
 import { ProjectRepository } from "../../project/project-repository";
-import { CURRENT_PROJECT_VERSION } from "../../project/migrations/project-migrations";
+import { collectReferencedHashes } from "@src/lib/assets/asset-gc";
+import {
+    getStorageProvider,
+    type StoredAsset,
+} from "@src/lib/persistence/storage-provider/storage-provider";
 import * as fflate from "fflate";
 import * as Y from "yjs";
 
-// ─── File Header ──────────────────────────────────────────────────────────────
+// ─── Container format ──────────────────────────────────────────────────────────
 //
-//  Offset  Size  Description
-//  ──────  ────  ──────────────────────────────────────────────────────────────
-//   0       8    Magic bytes: ASCII "SCRIPTIO"
-//   8       1    Version (u8):  see CURRENT_PROJECT_VERSION
-//   9       1    Flags   (u8):  bit 0 → 0 = zlib-compressed binary Yjs state
-//                                        1 = human-readable JSON (ProjectData)
-//  10       …    Payload
+// A `.scriptio` file is a ZIP archive:
 //
-const MAGIC = new Uint8Array([0x53, 0x43, 0x52, 0x49, 0x50, 0x54, 0x49, 0x4f]); // "SCRIPTIO"
-const HEADER_SIZE = MAGIC.length + 1 + 1; // 8 magic + 1 version + 1 flags = 10 bytes
+//   mimetype               `application/vnd.scriptio+zip`. First entry, STORED
+//                          (uncompressed) so the type is sniffable by content at
+//                          a fixed offset — the EPUB/ODF/OOXML convention.
+//   document.json   ─┐     Exactly one document entry, named by its type:
+//   document.ydoc   ─┘       · document.json — readable export: the project
+//                              serialized as JSON (ProjectData). A snapshot, so
+//                              it carries no CRDT collaboration history.
+//                            · document.ydoc — binary export: the raw Yjs
+//                              document update, preserving the full CRDT state.
+//                          Either way the bytes are deflated by the ZIP itself;
+//                          there is no inner header — the entry name says how to
+//                          read it, and the schema version lives in the doc's
+//                          `metadata.version` (the migration runner gates on it).
+//   assets/manifest.json   Metadata for every bundled asset (mime, size, dims).
+//   assets/<hash>.<ext>    Raw bytes of each board image, content-addressed by
+//                          its SHA-256 (the `assetId` referenced by board cards).
+//
+// Image bytes are decoupled from the Yjs document (they live in IndexedDB at
+// runtime); bundling them under `assets/` is what makes an exported project
+// self-contained.
+
+// ZIP local-file-header magic ("PK\x03\x04"), used to recognise the archive.
+const ZIP_MAGIC = [0x50, 0x4b, 0x03, 0x04];
 
-const FLAG_READABLE_JSON = 0x01; // bit 0: payload is UTF-8 JSON, not compressed Yjs
+/**
+ * Content type identifying the archive. Written as the first entry, uncompressed,
+ * so a sniffer (libmagic/`file`, the OS) can recognise a `.scriptio` by content
+ * even if it's renamed — the same trick EPUB and OpenDocument use. The `+zip`
+ * suffix (RFC 6839) advertises the ZIP-based structure.
+ */
+const SCRIPTIO_MIMETYPE = "application/vnd.scriptio+zip";
+
+const ZIP_MIMETYPE_ENTRY = "mimetype";
+const ZIP_DOCUMENT_JSON = "document.json"; // readable export (ProjectData JSON)
+const ZIP_DOCUMENT_YDOC = "document.ydoc"; // binary export (raw Yjs update)
+const ZIP_ASSET_DIR = "assets/";
+const ZIP_ASSET_MANIFEST = "assets/manifest.json";
 
 export type ScriptioExportOptions = BaseExportOptions & {
-    /** When true, the payload is indented JSON (ProjectData) instead of compressed binary Yjs state. */
+    /** When true, the document is indented JSON (ProjectData) instead of binary Yjs state. */
     readable?: boolean;
+    /**
+     * Owning project id, used to read the project's board image assets from
+     * local storage and bundle them under `assets/`. When omitted, the archive
+     * carries the document only (no assets).
+     */
+    projectId?: string;
 };
 
-function buildHeader(version: number, flags: number): Uint8Array {
-    const header = new Uint8Array(HEADER_SIZE);
-    header.set(MAGIC, 0);
-    header[MAGIC.length] = version;
-    header[MAGIC.length + 1] = flags;
-    return header;
+interface AssetManifestEntry {
+    /** ZIP entry path of the bytes, e.g. `assets/<hash>.png`. */
+    file: string;
+    /** SHA-256 hex — the assetId referenced by board cards. */
+    hash: string;
+    mime: string;
+    width: number;
+    height: number;
+    size: number;
+}
+
+interface AssetManifest {
+    version: 1;
+    assets: AssetManifestEntry[];
+}
+
+/** Does this buffer start with the ZIP local-file-header magic? */
+function isZipArchive(data: Uint8Array): boolean {
+    return data.length >= ZIP_MAGIC.length && ZIP_MAGIC.every((b, i) => data[i] === b);
 }
 
-function parseHeader(data: Uint8Array): { version: number; flags: number; payloadOffset: number } {
-    if (data.length < HEADER_SIZE) {
-        throw new Error("File is too short to be a valid .scriptio file");
+/** File extension (with leading dot) for a bundled asset of the given mime. */
+function extensionForMime(mime: string): string {
+    switch (mime) {
+        case "image/png":
+            return ".png";
+        case "image/jpeg":
+            return ".jpg";
+        case "image/gif":
+            return ".gif";
+        case "image/webp":
+            return ".webp";
+        case "image/avif":
+            return ".avif";
+        case "image/bmp":
+            return ".bmp";
+        case "image/svg+xml":
+            return ".svg";
+        default:
+            return "";
     }
+}
+
+// ── Reading the document entry ───────────────────────────────────────────────────
+
+/** Decompress just the document entry (skip assets) from a ZIP archive. */
+function unzipDocument(data: Uint8Array): fflate.Unzipped {
+    if (!isZipArchive(data)) throw new Error("Not a .scriptio archive");
+    return fflate.unzipSync(data, {
+        filter: (f) => f.name === ZIP_DOCUMENT_JSON || f.name === ZIP_DOCUMENT_YDOC,
+    });
+}
+
+/** Read a Yjs update into a throwaway doc and serialize it to ProjectData. */
+function projectDataFromYjsUpdate(update: Uint8Array): ProjectData {
+    const tmpDoc = new ProjectState();
+    try {
+        Y.applyUpdate(tmpDoc, update);
+        return projectDataOf(tmpDoc);
+    } finally {
+        tmpDoc.destroy();
+    }
+}
 
-    for (let i = 0; i < MAGIC.length; i++) {
-        if (data[i] !== MAGIC[i]) {
-            throw new Error("Invalid .scriptio file: magic bytes not found");
+/** Parse the document entry of a ZIP archive into ProjectData. */
+function parseZipDocument(unzipped: fflate.Unzipped): ProjectData {
+    const json = unzipped[ZIP_DOCUMENT_JSON];
+    if (json) {
+        try {
+            return JSON.parse(fflate.strFromU8(json)) as ProjectData;
+        } catch (error) {
+            console.error("Failed to parse readable Scriptio document", error);
+            throw new Error("Invalid Scriptio file format");
         }
     }
 
-    const version = data[MAGIC.length];
-    if (version > CURRENT_PROJECT_VERSION) {
-        throw new Error(`Unsupported .scriptio file version: ${version}. Please update Scriptio.`);
+    const ydoc = unzipped[ZIP_DOCUMENT_YDOC];
+    if (ydoc) {
+        try {
+            return projectDataFromYjsUpdate(ydoc);
+        } catch (error) {
+            console.error("Failed to parse Scriptio document", error);
+            throw new Error("Invalid Scriptio file format");
+        }
     }
 
-    const flags = data[MAGIC.length + 1];
-    return { version, flags, payloadOffset: HEADER_SIZE };
+    throw new Error("Invalid .scriptio archive: missing document entry");
 }
 
-export class ScriptioAdapter extends ProjectAdapter<ScriptioExportOptions> {
-    label = "Scriptio";
-    extension = "scriptio";
+// ── Asset bundling ───────────────────────────────────────────────────────────────
 
-    convertTo(project: ProjectState, options: ScriptioExportOptions): Promise<Blob> {
-        const isReadable = options.readable ?? false;
-        const flags = isReadable ? FLAG_READABLE_JSON : 0x00;
-        const header = buildHeader(CURRENT_PROJECT_VERSION, flags);
-
-        let payload: Uint8Array;
-
-        if (isReadable) {
-            // Human-readable path: serialize the full project as indented JSON.
-            // This produces a larger file but makes the content inspectable
-            // with any text editor. `projectDataOf` captures every map and
-            // fragment, so the readable export is just as lossless as binary.
-            payload = new TextEncoder().encode(JSON.stringify(projectDataOf(project), null, 2));
-        } else {
-            // Binary path: zlib-compress the raw Yjs state.
-            // Preserves the full CRDT document, including collaboration history.
-            const yjsState = Y.encodeStateAsUpdate(project);
-            payload = fflate.zlibSync(yjsState, { level: 9 });
-        }
+/**
+ * Read the project's board image assets from local storage and turn them into
+ * ZIP entries (raw bytes + a manifest). Returns an empty map when the project
+ * references no images or none are stored locally.
+ */
+async function buildAssetEntries(
+    projectId: string,
+    project: ProjectState,
+): Promise<fflate.Zippable> {
+    const entries: fflate.Zippable = {};
+
+    let referenced: Set<string>;
+    try {
+        referenced = collectReferencedHashes(project);
+    } catch {
+        // A board with an unparseable cards blob — bundle the document anyway.
+        return entries;
+    }
+    if (referenced.size === 0) return entries;
+
+    const provider = await getStorageProvider();
+    const manifest: AssetManifest = { version: 1, assets: [] };
 
-        const file = new Uint8Array(header.length + payload.length);
-        file.set(header, 0);
-        file.set(payload, header.length);
+    for (const hash of referenced) {
+        const asset = await provider.getAsset(projectId, hash);
+        if (!asset) continue; // referenced but not stored locally — skip
 
-        return Promise.resolve(new Blob([file], { type: "application/octet-stream" }));
+        const file = `${ZIP_ASSET_DIR}${hash}${extensionForMime(asset.mime)}`;
+        // Images are already compressed; storing them with level 0 avoids a
+        // pointless second deflate pass over the whole archive's bytes.
+        entries[file] = [new Uint8Array(asset.data), { level: 0 }];
+        manifest.assets.push({
+            file,
+            hash,
+            mime: asset.mime,
+            width: asset.width,
+            height: asset.height,
+            size: asset.size,
+        });
     }
 
-    convertFrom(rawContent: ArrayBuffer): ProjectData {
-        const data = new Uint8Array(rawContent);
-        const { flags, payloadOffset } = parseHeader(data);
-        const payload = data.subarray(payloadOffset);
+    if (manifest.assets.length > 0) {
+        entries[ZIP_ASSET_MANIFEST] = fflate.strToU8(JSON.stringify(manifest, null, 2));
+    }
+    return entries;
+}
+
+/**
+ * Restore the board image assets bundled in a `.scriptio` archive into local
+ * storage under `projectId`. No-ops for archives without an asset manifest, and
+ * safe to call for any imported file — non-archive content is ignored.
+ */
+export async function restoreScriptioAssets(
+    projectId: string,
+    rawContent: ArrayBuffer,
+): Promise<void> {
+    const data = new Uint8Array(rawContent);
+    if (!isZipArchive(data)) return;
+
+    let unzipped: fflate.Unzipped;
+    try {
+        unzipped = fflate.unzipSync(data, { filter: (f) => f.name.startsWith(ZIP_ASSET_DIR) });
+    } catch (error) {
+        console.warn("[Scriptio] Failed to read bundled assets:", error);
+        return;
+    }
+
+    const manifestBytes = unzipped[ZIP_ASSET_MANIFEST];
+    if (!manifestBytes) return;
+
+    let manifest: AssetManifest;
+    try {
+        manifest = JSON.parse(fflate.strFromU8(manifestBytes)) as AssetManifest;
+    } catch (error) {
+        console.warn("[Scriptio] Invalid asset manifest:", error);
+        return;
+    }
+
+    const provider = await getStorageProvider();
+    await Promise.all(
+        manifest.assets.map(async (entry) => {
+            const bytes = unzipped[entry.file];
+            if (!bytes) return;
+
+            // `slice()` copies the bytes into a standalone ArrayBuffer so the
+            // stored asset doesn't retain the entire decompressed archive.
+            const asset: StoredAsset = {
+                key: `${projectId}/${entry.hash}`,
+                projectId,
+                hash: entry.hash,
+                mime: entry.mime,
+                size: entry.size ?? bytes.byteLength,
+                width: entry.width,
+                height: entry.height,
+                data: bytes.slice().buffer,
+                createdAt: Date.now(),
+            };
+            await provider.putAsset(asset);
+        }),
+    );
+}
+
+export class ScriptioAdapter extends ProjectAdapter<ScriptioExportOptions> {
+    label = "Scriptio";
+    extension = "scriptio";
+
+    async convertTo(project: ProjectState, options: ScriptioExportOptions): Promise<Blob> {
+        const readable = options.readable ?? false;
+
+        // Readable: pretty-printed ProjectData JSON (a snapshot, no CRDT history).
+        // Binary: the raw Yjs update, preserving full collaboration history. The
+        // ZIP deflates either one — there's no inner header.
+        const documentName = readable ? ZIP_DOCUMENT_JSON : ZIP_DOCUMENT_YDOC;
+        const documentBytes = readable
+            ? fflate.strToU8(JSON.stringify(projectDataOf(project), null, 2))
+            : new Uint8Array(Y.encodeStateAsUpdate(project));
 
-        const isReadable = (flags & FLAG_READABLE_JSON) !== 0;
+        // Insertion order is preserved by fflate, so `mimetype` stays first.
+        // Stored (level 0) and first, its value lands at the fixed byte offset
+        // where content sniffers expect it.
+        const zipEntries: fflate.Zippable = {
+            [ZIP_MIMETYPE_ENTRY]: [fflate.strToU8(SCRIPTIO_MIMETYPE), { level: 0 }],
+            [documentName]: [documentBytes, { level: 9 }],
+        };
 
-        if (isReadable) {
-            // JSON path: decode UTF-8 and parse directly into ProjectData.
+        if (options.projectId) {
             try {
-                const json = new TextDecoder().decode(payload);
-                return JSON.parse(json) as ProjectData;
+                Object.assign(zipEntries, await buildAssetEntries(options.projectId, project));
             } catch (error) {
-                console.error("Failed to parse readable .scriptio file", error);
-                throw new Error("Invalid Scriptio file format");
+                // Never fail the whole export over an asset read hiccup — the
+                // document is the essential part.
+                console.warn("[Scriptio] Failed to bundle assets:", error);
             }
         }
 
-        // Binary path: decompress Yjs state, apply to a temporary doc, read fields.
-        const tmpDoc = new ProjectState();
-        try {
-            const decompressed = fflate.unzlibSync(payload);
-            Y.applyUpdate(tmpDoc, decompressed);
+        const archive = fflate.zipSync(zipEntries, { level: 6 });
+        // Re-wrap as an ArrayBuffer-backed view: fflate types its output as
+        // Uint8Array<ArrayBufferLike>, which BlobPart won't accept directly.
+        return new Blob([new Uint8Array(archive)], { type: SCRIPTIO_MIMETYPE });
+    }
 
-            return projectDataOf(tmpDoc);
-        } catch (error) {
-            console.error("Failed to parse .scriptio file", error);
-            throw new Error("Invalid Scriptio file format");
-        } finally {
-            tmpDoc.destroy();
-        }
+    convertFrom(rawContent: ArrayBuffer): ProjectData {
+        return parseZipDocument(unzipDocument(new Uint8Array(rawContent)));
     }
 
     public import(
@@ -125,25 +306,24 @@ export class ScriptioAdapter extends ProjectAdapter<ScriptioExportOptions> {
         titlePageEditor?: Editor | null,
         repository?: ProjectRepository | null,
     ): void {
-        const data = new Uint8Array(rawContent);
-        const { flags, payloadOffset } = parseHeader(data);
-        const payload = data.subarray(payloadOffset);
-        const isReadable = (flags & FLAG_READABLE_JSON) !== 0;
-
         if (repository) {
             const ydoc = repository.getState() as ProjectState;
             try {
+                const unzipped = unzipDocument(new Uint8Array(rawContent));
+
                 // Truly "replace" the project: wipe every existing map and
                 // fragment first so the import never merges with prior data.
                 clearProjectData(ydoc);
 
-                if (isReadable) {
-                    const json = new TextDecoder().decode(payload);
-                    applyProjectData(ydoc, JSON.parse(json) as ProjectData);
-                } else {
+                const ydocUpdate = unzipped[ZIP_DOCUMENT_YDOC];
+                if (ydocUpdate) {
                     // Applying the raw Yjs update preserves the full CRDT state,
                     // including any collaboration history baked into the file.
-                    Y.applyUpdate(ydoc, fflate.unzlibSync(payload));
+                    Y.applyUpdate(ydoc, ydocUpdate);
+                } else {
+                    const json = unzipped[ZIP_DOCUMENT_JSON];
+                    if (!json) throw new Error("Invalid .scriptio archive: missing document entry");
+                    applyProjectData(ydoc, JSON.parse(fflate.strFromU8(json)) as ProjectData);
                 }
 
                 // Refresh editors if provided
diff --git a/src/lib/import/import-project.ts b/src/lib/import/import-project.ts
index 4e9c3321..16efc25a 100644
--- a/src/lib/import/import-project.ts
+++ b/src/lib/import/import-project.ts
@@ -6,6 +6,7 @@
 import { ProjectData, ProjectState, applyProjectData } from "@src/lib/project/project-state";
 import { CURRENT_PROJECT_VERSION } from "@src/lib/project/migrations/project-migrations";
 import { getAdapterByFilename } from "@src/lib/adapters/registry";
+import { restoreScriptioAssets } from "@src/lib/adapters/scriptio/scriptio-adapter";
 import { createCachedProject, createCachedProjectWithId } from "@src/lib/persistence/storage-provider/local-persistence";
 import { writeYjsDocumentLocally } from "@src/lib/persistence/y-local-provider";
 import { Editor } from "@tiptap/react";
@@ -25,13 +26,12 @@ export interface ImportResult {
 /**
  * Parse a file and extract project content.
  */
-async function parseFile(file: File): Promise<ProjectData> {
-    const adapter = getAdapterByFilename(file.name);
+function parseProjectData(filename: string, content: ArrayBuffer): ProjectData {
+    const adapter = getAdapterByFilename(filename);
     if (!adapter) {
-        throw new Error(`Unsupported file type: ${file.name.split(".").pop()}`);
+        throw new Error(`Unsupported file type: ${filename.split(".").pop()}`);
     }
 
-    const content = await file.arrayBuffer();
     const projectData = adapter.convertFrom(content) as ProjectData;
 
     if (!projectData.screenplay || projectData.screenplay.length === 0) {
@@ -43,9 +43,14 @@ async function parseFile(file: File): Promise<ProjectData> {
 
 /**
  * Import a file into an existing project.
+ *
+ * `projectId` identifies the target project so bundled board image assets land
+ * under the right key in local storage; it's the currently-open project, not
+ * the (possibly different) id stamped inside the imported file.
  */
 export async function importFileIntoProject(
     file: File,
+    projectId: string,
     editor?: Editor | null,
     titlePageEditor?: Editor | null,
     repository?: ProjectRepository | null,
@@ -62,6 +67,8 @@ export async function importFileIntoProject(
 
     const content = await file.arrayBuffer();
     adapter.import(content, editor, titlePageEditor, repository);
+    // Restore any bundled board image assets (no-op for non-Scriptio files).
+    await restoreScriptioAssets(projectId, content);
     if (editor) editor.commands.focus();
 }
 
@@ -123,8 +130,10 @@ export async function importFileAsProject(
     isPro?: boolean,
 ): Promise<ImportResult> {
     try {
-        // Parse the file content
-        const projectData = await parseFile(file);
+        // Parse the file content (kept as a buffer so bundled assets can be
+        // restored after the new project id is known).
+        const content = await file.arrayBuffer();
+        const projectData = parseProjectData(file.name, content);
 
         // Create project title from filename if not provided
         const projectTitle = title || file.name.replace(/\.[^/.]+$/, "");
@@ -158,6 +167,10 @@ export async function importFileAsProject(
         // Create Yjs document with the project content
         await createLocalYjsDocument(projectId, projectData);
 
+        // Restore any bundled board image assets under the new project id
+        // (no-op for non-Scriptio files).
+        await restoreScriptioAssets(projectId, content);
+
         return {
             success: true,
             projectId,
diff --git a/src/tests/assets/assets.test.ts b/src/tests/assets/assets.test.ts
index 084b6882..48d84e56 100644
--- a/src/tests/assets/assets.test.ts
+++ b/src/tests/assets/assets.test.ts
@@ -9,6 +9,7 @@ import {
 } from "@src/lib/persistence/storage-provider/storage-provider";
 import { ProjectState } from "@src/lib/project/project-state";
 import { createProjectRepository } from "@src/lib/project/project-repository";
+import { ScriptioAdapter, restoreScriptioAssets } from "@src/lib/adapters/scriptio/scriptio-adapter";
 
 const pid = () => `test-${Math.random().toString(36).slice(2)}`;
 
@@ -181,3 +182,72 @@ describe("asset GC (reconcile from doc)", () => {
         ydoc.destroy();
     });
 });
+
+describe("scriptio asset bundling", () => {
+    it("bundles board image assets into the archive and restores them", async () => {
+        const provider = await getStorageProvider();
+        const src = pid();
+
+        // A board referencing a real stored image.
+        const file = await makePngFile("pic.png", 12, 8, "#0f0");
+        const { hash } = await importImageFile(src, file);
+
+        const ydoc = new ProjectState();
+        const repo = createProjectRepository(ydoc)!;
+        const board = repo.createBoardDocument("B");
+        ydoc.boardData(board).set(
+            "cards",
+            JSON.stringify([{ id: "c1", type: "image", assetId: hash, ...cardBase }]),
+        );
+
+        const adapter = new ScriptioAdapter();
+        const blob = await adapter.convertTo(ydoc, {
+            title: "t",
+            author: "a",
+            includeNotes: false,
+            projectId: src,
+        });
+        const buffer = await blob.arrayBuffer();
+
+        // The document still parses out of the zip and carries the board card.
+        const parsed = adapter.convertFrom(buffer);
+        expect(parsed.boards?.[board]?.cards).toContain(hash);
+
+        // Assets restore into a *different* project id (the import target).
+        const dest = pid();
+        expect(await provider.hasAsset(dest, hash)).toBe(false);
+        await restoreScriptioAssets(dest, buffer);
+
+        const restored = await provider.getAsset(dest, hash);
+        expect(restored?.width).toBe(12);
+        expect(restored?.height).toBe(8);
+        expect(restored?.mime).toBe("image/png");
+        // Bytes survive the round trip intact.
+        expect(await sha256Hex(restored!.data)).toBe(hash);
+
+        await provider.deleteProjectAssets(src);
+        await provider.deleteProjectAssets(dest);
+        ydoc.destroy();
+    });
+
+    it("exports a document with no assets and restore is a no-op", async () => {
+        const ydoc = new ProjectState();
+        const repo = createProjectRepository(ydoc)!;
+        repo.createBoardDocument("B"); // empty board, no image cards
+
+        const adapter = new ScriptioAdapter();
+        const blob = await adapter.convertTo(ydoc, {
+            title: "t",
+            author: "a",
+            includeNotes: false,
+            projectId: pid(),
+        });
+        const buffer = await blob.arrayBuffer();
+
+        const dest = pid();
+        await restoreScriptioAssets(dest, buffer); // must not throw
+        expect(await (await getStorageProvider()).listAssetHashes(dest)).toEqual([]);
+
+        ydoc.destroy();
+    });
+});
diff --git a/src/tests/project/scriptio-roundtrip.test.ts b/src/tests/project/scriptio-roundtrip.test.ts
index ea4269cd..ff715a2c 100644
--- a/src/tests/project/scriptio-roundtrip.test.ts
+++ b/src/tests/project/scriptio-roundtrip.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { prosemirrorJSONToYXmlFragment } from "y-prosemirror";
+import * as fflate from "fflate";
 
 import {
     ProjectState,
@@ -137,6 +138,52 @@ describe("scriptio adapter full round trip", () => {
         });
     }
 
+    it("names the document entry by type and writes a header-free readable JSON", async () => {
+        const project = buildPopulatedProject();
+        const adapter = new ScriptioAdapter();
+
+        const readableZip = fflate.unzipSync(
+            new Uint8Array(await (await adapter.convertTo(project, { ...baseOptions, readable: true })).arrayBuffer()),
+        );
+        expect(Object.keys(readableZip)).toContain("document.json");
+        expect(Object.keys(readableZip)).not.toContain("document.ydoc");
+
+        // The readable entry is pure JSON — no binary header to strip first.
+        const text = fflate.strFromU8(readableZip["document.json"]);
+        expect(text.trimStart().startsWith("{")).toBe(true);
+        expect(JSON.parse(text).metadata.title).toBe("My Script");
+
+        const binaryZip = fflate.unzipSync(
+            new Uint8Array(await (await adapter.convertTo(project, { ...baseOptions, readable: false })).arrayBuffer()),
+        );
+        expect(Object.keys(binaryZip)).toContain("document.ydoc");
+        expect(Object.keys(binaryZip)).not.toContain("document.json");
+
+        project.destroy();
+    });
+
+    it("writes an uncompressed mimetype as the first archive entry", async () => {
+        const project = buildPopulatedProject();
+        const adapter = new ScriptioAdapter();
+        const blob = await adapter.convertTo(project, { ...baseOptions, readable: false });
+        const bytes = new Uint8Array(await blob.arrayBuffer());
+
+        // First ZIP local file header, then its filename and (stored) content.
+        expect(Array.from(bytes.slice(0, 4))).toEqual([0x50, 0x4b, 0x03, 0x04]);
+        const nameLen = bytes[26] | (bytes[27] << 8);
+        const extraLen = bytes[28] | (bytes[29] << 8);
+        expect(new TextDecoder().decode(bytes.slice(30, 30 + nameLen))).toBe("mimetype");
+
+        // Stored (not deflated): the value appears verbatim right after the name.
+        const dataStart = 30 + nameLen + extraLen;
+        const mimetype = "application/vnd.scriptio+zip";
+        expect(new TextDecoder().decode(bytes.slice(dataStart, dataStart + mimetype.length))).toBe(
+            mimetype,
+        );
+
+        project.destroy();
+    });
+
     it("clearProjectData wipes maps and dynamic fragments before a replace", () => {
         const ydoc = buildPopulatedProject();
         clearProjectData(ydoc);

From 423f11580db2b636fbaa7a78365482b042d7d8ef Mon Sep 17 00:00:00 2001
From: Lycoon <hugo.bois@hotmail.fr>
Date: Thu, 11 Jun 2026 02:50:20 +0200
Subject: [PATCH 3/3] added voice recording handling to boards, tweaked some
 board styling

---
 components/board/BoardCanvas.module.css       | 194 +++++++-
 components/board/BoardCanvas.tsx              | 174 +++++++-
 components/board/BoardCard.tsx                | 415 ++++++++++++++----
 components/board/use-audio-recorder.ts        | 118 +++++
 messages/de.json                              |   9 +-
 messages/en.json                              |   9 +-
 messages/es.json                              |   9 +-
 messages/fr.json                              |   9 +-
 messages/ja.json                              |   9 +-
 messages/ko.json                              |   9 +-
 messages/pl.json                              |   9 +-
 messages/zh.json                              |   9 +-
 src/lib/adapters/scriptio/scriptio-adapter.ts |  13 +
 src/lib/assets/asset-gc.ts                    |   5 +-
 src/lib/assets/asset-store.ts                 |  44 ++
 src/lib/project/project-doc.ts                |  13 +-
 src/tests/assets/assets.test.ts               |  45 +-
 styles/themes.css                             |   7 +
 18 files changed, 983 insertions(+), 117 deletions(-)
 create mode 100644 components/board/use-audio-recorder.ts

diff --git a/components/board/BoardCanvas.module.css b/components/board/BoardCanvas.module.css
index 0b566473..24174924 100644
--- a/components/board/BoardCanvas.module.css
+++ b/components/board/BoardCanvas.module.css
@@ -17,7 +17,13 @@
     pointer-events: none;
     background: linear-gradient(to bottom, var(--editor-shadow) 0%, transparent 100%);
     mask-image: linear-gradient(to right, transparent 0%, black 20%, black 80%, transparent 100%);
-    -webkit-mask-image: linear-gradient(to right, transparent 0%, black 20%, black 80%, transparent 100%);
+    -webkit-mask-image: linear-gradient(
+        to right,
+        transparent 0%,
+        black 20%,
+        black 80%,
+        transparent 100%
+    );
 }
 
 .container {
@@ -64,8 +70,6 @@
     position: absolute;
     display: flex;
     flex-direction: column;
-    border-radius: 8px;
-    border: 8px solid;
     box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
     cursor: move;
     user-select: none;
@@ -105,6 +109,124 @@
     background-color: rgba(0, 0, 0, 0.05);
 }
 
+/* Audio voice-note card: a colored header (title) over a play/timeline row. */
+.card.audio_card {
+    overflow: hidden;
+}
+
+.audio_content {
+    flex: 1;
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    padding: 0 12px;
+    overflow: hidden;
+}
+
+/* Remaining-time readout next to the play button. */
+.audio_time {
+    flex-shrink: 0;
+    font-size: 12px;
+    font-variant-numeric: tabular-nums;
+    color: var(--board-card-body-text);
+    user-select: none;
+}
+
+/* Seekable timeline. The card content is always a light tint, so the track uses
+   theme greys (--separator / --secondary-text) that read across every theme.
+   `--audio-progress` (set from JS) fills the track up to the cursor on WebKit;
+   Firefox uses its native ::-moz-range-progress. */
+.audio_timeline {
+    flex: 1;
+    min-width: 0;
+    height: 16px;
+    margin: 0;
+    padding: 0;
+    cursor: pointer;
+    background: transparent;
+    -webkit-appearance: none;
+    appearance: none;
+    --audio-progress: 0%;
+}
+
+.audio_timeline::-webkit-slider-runnable-track {
+    height: 4px;
+    border-radius: 999px;
+    background: linear-gradient(
+        to right,
+        var(--secondary-text) var(--audio-progress),
+        var(--separator) var(--audio-progress)
+    );
+}
+
+.audio_timeline::-moz-range-track {
+    height: 4px;
+    border-radius: 999px;
+    background: var(--separator);
+}
+
+.audio_timeline::-moz-range-progress {
+    height: 4px;
+    border-radius: 999px;
+    background: var(--secondary-text);
+}
+
+.audio_timeline::-webkit-slider-thumb {
+    -webkit-appearance: none;
+    appearance: none;
+    box-sizing: border-box;
+    width: 12px;
+    height: 12px;
+    margin-top: -4px;
+    border: 2px solid var(--secondary);
+    border-radius: 50%;
+    background: var(--secondary-text);
+    box-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
+    transition: transform 0.1s ease;
+}
+
+.audio_timeline::-moz-range-thumb {
+    box-sizing: border-box;
+    width: 12px;
+    height: 12px;
+    border: 2px solid var(--secondary);
+    border-radius: 50%;
+    background: var(--secondary-text);
+    box-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
+}
+
+.audio_timeline:hover:not(:disabled)::-webkit-slider-thumb {
+    transform: scale(1.15);
+}
+
+.audio_timeline:disabled {
+    cursor: default;
+    opacity: 0.5;
+}
+
+.audio_play_btn {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex-shrink: 0;
+    width: 32px;
+    height: 32px;
+    border: none;
+    border-radius: 50%;
+    background-color: var(--secondary);
+    color: var(--secondary-text);
+    cursor: pointer;
+}
+
+.audio_play_btn:hover:not(:disabled) {
+    background-color: var(--secondary-hover);
+}
+
+.audio_play_btn:disabled {
+    opacity: 0.4;
+    cursor: default;
+}
+
 .card_header {
     position: relative;
     display: flex;
@@ -286,6 +408,72 @@
     background-color: var(--context-menu-item-hover);
 }
 
+.context_menu_item_disabled {
+    opacity: 0.45;
+    cursor: default;
+}
+
+.context_menu_item_disabled:hover {
+    background-color: transparent;
+}
+
+/* Recording indicator: a pill in the top toolbar row, right of the zoom controls. */
+.recording_indicator {
+    position: absolute;
+    top: 8px;
+    left: 180px;
+    z-index: 11;
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    height: 36px;
+    padding: 0 10px;
+    border-radius: 16px;
+    background-color: var(--secondary);
+    color: var(--secondary-text);
+    user-select: none;
+}
+
+.recording_dot {
+    width: 10px;
+    height: 10px;
+    border-radius: 50%;
+    background-color: #e5484d;
+    animation: recording_pulse 1s ease-in-out infinite;
+}
+
+@keyframes recording_pulse {
+    0%,
+    100% {
+        opacity: 1;
+    }
+    50% {
+        opacity: 0.3;
+    }
+}
+
+.recording_time {
+    font-size: 13px;
+    font-variant-numeric: tabular-nums;
+}
+
+.recording_stop {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    padding: 4px 10px;
+    border: none;
+    border-radius: 12px;
+    background-color: #e5484d;
+    color: white;
+    font-size: 13px;
+    cursor: pointer;
+}
+
+.recording_stop:hover {
+    background-color: #d33b40;
+}
+
 .context_menu_colors {
     display: flex;
     flex-wrap: wrap;
diff --git a/components/board/BoardCanvas.tsx b/components/board/BoardCanvas.tsx
index f10a263f..cd187e44 100644
--- a/components/board/BoardCanvas.tsx
+++ b/components/board/BoardCanvas.tsx
@@ -6,17 +6,33 @@ import { BoardCardData, BoardArrowData } from "@src/lib/project/project-state";
 import BoardCard from "./BoardCard";
 import styles from "./BoardCanvas.module.css";
 import { v7 as uuidv7 } from "uuid";
-import { Trash2, Plus, Minus, Copy, ListTree } from "lucide-react";
+import { Trash2, Plus, Minus, Copy, ListTree, Mic, Square } from "lucide-react";
 import { useTranslations } from "next-intl";
 import { DEFAULT_ITEM_COLORS } from "@src/lib/utils/colors";
-import { importImageFile } from "@src/lib/assets/asset-store";
+import { importImageFile, importAudioFile } from "@src/lib/assets/asset-store";
 import { scheduleAssetGc } from "@src/lib/assets/asset-gc";
+import { useAudioRecorder } from "./use-audio-recorder";
 
 const GRID_SIZE = 20;
 const MIN_SCALE = 0.25;
 const MAX_SCALE = 2;
 /** Largest edge (in canvas px) an image card is sized to on first drop. */
 const MAX_IMAGE_CARD_SIZE = 400;
+/** Default size (in canvas px) of an audio voice-note card. */
+const AUDIO_CARD_WIDTH = 260;
+const AUDIO_CARD_HEIGHT = 96;
+
+/** A random swatch from the default palette (used for new colored cards). */
+function randomCardColor(): string {
+    return DEFAULT_ITEM_COLORS[Math.floor(Math.random() * DEFAULT_ITEM_COLORS.length)];
+}
+
+/** Seconds → `m:ss` for the recording indicator. */
+function formatRecordingTime(seconds: number): string {
+    const m = Math.floor(seconds / 60);
+    const s = seconds % 60;
+    return `${m}:${s.toString().padStart(2, "0")}`;
+}
 
 interface CardContextMenuState {
     position: { x: number; y: number };
@@ -28,6 +44,14 @@ interface ArrowContextMenuState {
     arrow: BoardArrowData;
 }
 
+interface CanvasContextMenuState {
+    /** Viewport position for placing the menu. */
+    position: { x: number; y: number };
+    /** Canvas-space coords where a new card should be created. */
+    canvasX: number;
+    canvasY: number;
+}
+
 const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }) => {
     const { projectId, repository, isYjsReady, isReadOnly, boardFocusCardId, setBoardFocusCardId } =
         useContext(ProjectContext);
@@ -45,6 +69,8 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
     const [isSnapping, setIsSnapping] = useState(true);
     const [cardContextMenu, setCardContextMenu] = useState<CardContextMenuState | null>(null);
     const [arrowContextMenu, setArrowContextMenu] = useState<ArrowContextMenuState | null>(null);
+    const [canvasContextMenu, setCanvasContextMenu] = useState<CanvasContextMenuState | null>(null);
+    const recorder = useAudioRecorder();
     const [prevIsVisible, setPrevIsVisible] = useState(isVisible);
     if (prevIsVisible !== isVisible) {
         setPrevIsVisible(isVisible);
@@ -52,6 +78,7 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
             setIsSnapping(true);
             if (cardContextMenu) setCardContextMenu(null);
             if (arrowContextMenu) setArrowContextMenu(null);
+            if (canvasContextMenu) setCanvasContextMenu(null);
         }
     }
     const [isCameraReady, setIsCameraReady] = useState(false);
@@ -243,13 +270,14 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
         const handleClick = () => {
             if (cardContextMenu) setCardContextMenu(null);
             if (arrowContextMenu) setArrowContextMenu(null);
+            if (canvasContextMenu) setCanvasContextMenu(null);
         };
 
         window.addEventListener("click", handleClick);
         return () => {
             window.removeEventListener("click", handleClick);
         };
-    }, [cardContextMenu, arrowContextMenu, isVisible]);
+    }, [cardContextMenu, arrowContextMenu, canvasContextMenu, isVisible]);
 
     // Panning with middle-click
     const handlePanMouseDown = useCallback(
@@ -334,6 +362,8 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
     const offsetRef = useRef(offset);
     const scaleRef = useRef(scale);
     const cardsRef = useRef(cards);
+    /** Canvas-space coords captured when recording starts, for the resulting card. */
+    const recordCoords = useRef({ x: 0, y: 0 });
     useEffect(() => {
         offsetRef.current = offset;
     }, [offset]);
@@ -490,14 +520,11 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
             const x = (e.clientX - rect.left - offset.x) / scale;
             const y = (e.clientY - rect.top - offset.y) / scale;
 
-            const randomColor =
-                DEFAULT_ITEM_COLORS[Math.floor(Math.random() * DEFAULT_ITEM_COLORS.length)];
-
             const newCard: BoardCardData = {
                 id: uuidv7(),
                 title: "",
                 description: "",
-                color: randomColor,
+                color: randomCardColor(),
                 x: isSnapping ? Math.round(x / GRID_SIZE) * GRID_SIZE : x,
                 y: isSnapping ? Math.round(y / GRID_SIZE) * GRID_SIZE : y,
                 width: 450,
@@ -536,8 +563,8 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
             setIsDraggingFile(false);
             if (isReadOnly || !projectId) return;
 
-            const files = Array.from(e.dataTransfer.files).filter((f) =>
-                f.type.startsWith("image/"),
+            const files = Array.from(e.dataTransfer.files).filter(
+                (f) => f.type.startsWith("image/") || f.type.startsWith("audio/"),
             );
             if (files.length === 0) return;
 
@@ -549,10 +576,26 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
 
             const created: BoardCardData[] = [];
             for (const file of files) {
+                const i = created.length;
                 try {
+                    if (file.type.startsWith("audio/")) {
+                        const { hash } = await importAudioFile(projectId, file);
+                        created.push({
+                            id: uuidv7(),
+                            type: "audio",
+                            assetId: hash,
+                            title: "",
+                            description: "",
+                            color: randomCardColor(),
+                            x: dropX + i * 24,
+                            y: dropY + i * 24,
+                            width: AUDIO_CARD_WIDTH,
+                            height: AUDIO_CARD_HEIGHT,
+                        });
+                        continue;
+                    }
                     const { hash, width, height } = await importImageFile(projectId, file);
                     const fit = Math.min(1, MAX_IMAGE_CARD_SIZE / Math.max(width, height, 1));
-                    const i = created.length;
                     created.push({
                         id: uuidv7(),
                         type: "image",
@@ -566,7 +609,7 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
                         height: Math.max(60, Math.round(height * fit)),
                     });
                 } catch (err) {
-                    console.error("[BoardCanvas] Failed to import image:", err);
+                    console.error("[BoardCanvas] Failed to import dropped file:", err);
                 }
             }
             if (created.length === 0) return;
@@ -578,6 +621,76 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
         [isReadOnly, projectId, offset, scale, saveCards],
     );
 
+    // Right-clicking empty canvas opens a menu (record audio). Cards and arrows
+    // have their own menus, so bail when the click landed on one.
+    const handleCanvasContextMenu = useCallback(
+        (e: React.MouseEvent) => {
+            if (isReadOnly) return;
+            const target = e.target as HTMLElement;
+            if (
+                target.closest(`.${styles.card}`) ||
+                target.closest(`.${styles.arrow_group}`) ||
+                target.closest(`.${styles.context_menu}`) ||
+                target.closest(`.${styles.zoom_controls}`) ||
+                target.closest(`.${styles.hints}`)
+            )
+                return;
+
+            const container = containerRef.current;
+            if (!container) return;
+            const rect = container.getBoundingClientRect();
+            e.preventDefault();
+            setCardContextMenu(null);
+            setArrowContextMenu(null);
+            setCanvasContextMenu({
+                // Match the card/arrow menus: positioned with raw viewport coords.
+                position: { x: e.clientX, y: e.clientY },
+                canvasX: (e.clientX - rect.left - offset.x) / scale,
+                canvasY: (e.clientY - rect.top - offset.y) / scale,
+            });
+        },
+        [isReadOnly, offset, scale],
+    );
+
+    // Begin recording from the canvas menu; remember where to drop the card.
+    const handleStartRecording = useCallback(async () => {
+        if (!canvasContextMenu) return;
+        recordCoords.current = { x: canvasContextMenu.canvasX, y: canvasContextMenu.canvasY };
+        setCanvasContextMenu(null);
+        try {
+            await recorder.start();
+        } catch (err) {
+            console.error("[BoardCanvas] Microphone access failed:", err);
+        }
+    }, [canvasContextMenu, recorder]);
+
+    // Stop recording, store the clip as an asset, and drop an audio card.
+    const handleStopRecording = useCallback(async () => {
+        const blob = await recorder.stop();
+        if (!blob || !projectId) return;
+        try {
+            const { hash } = await importAudioFile(projectId, blob);
+            const { x, y } = recordCoords.current;
+            const newCard: BoardCardData = {
+                id: uuidv7(),
+                type: "audio",
+                assetId: hash,
+                title: "",
+                description: "",
+                color: randomCardColor(),
+                x,
+                y,
+                width: AUDIO_CARD_WIDTH,
+                height: AUDIO_CARD_HEIGHT,
+            };
+            const newCards = [...cardsRef.current, newCard];
+            setCards(newCards);
+            saveCards(newCards);
+        } catch (err) {
+            console.error("[BoardCanvas] Failed to store recording:", err);
+        }
+    }, [recorder, projectId, saveCards]);
+
     // Update card (with multi-drag support)
     const handleUpdateCard = useCallback(
         (updatedCard: BoardCardData) => {
@@ -868,6 +981,7 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
                 className={`${styles.container} ${isPanning ? styles.panning : ""} ${isDraggingFile ? styles.drag_over : ""}`}
                 onMouseDown={handleContainerMouseDown}
                 onDoubleClick={handleDoubleClick}
+                onContextMenu={handleCanvasContextMenu}
                 onWheel={handleWheel}
                 onDragOver={handleDragOver}
                 onDragLeave={handleDragLeave}
@@ -1056,7 +1170,7 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
                             left: cardContextMenu.position.x,
                         }}
                     >
-                        {/* Color + outline apply to text notes; image cards have neither. */}
+                        {/* Color applies to text + audio notes; image cards have none. */}
                         {cardContextMenu.card.type !== "image" && (
                             <div className={styles.context_menu_colors}>
                                 {DEFAULT_ITEM_COLORS.map((color) => (
@@ -1078,7 +1192,7 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
                             <Copy size={16} />
                             <p className="unselectable">{t("duplicate")}</p>
                         </div>
-                        {cardContextMenu.card.type !== "image" && (
+                        {(cardContextMenu.card.type ?? "text") === "text" && (
                             <div
                                 className={styles.context_menu_item}
                                 onClick={() => handleSendToOutline(cardContextMenu.card)}
@@ -1097,6 +1211,40 @@ const BoardCanvas = ({ isVisible, docId }: { isVisible: boolean; docId: string }
                     </div>
                 )}
 
+                {/* Canvas Context Menu (empty-area right-click) */}
+                {canvasContextMenu && (
+                    <div
+                        className={styles.context_menu}
+                        style={{
+                            top: canvasContextMenu.position.y,
+                            left: canvasContextMenu.position.x,
+                        }}
+                    >
+                        <div
+                            className={`${styles.context_menu_item} ${recorder.isSupported ? "" : styles.context_menu_item_disabled}`}
+                            title={recorder.isSupported ? undefined : t("audioUnsupported")}
+                            onClick={recorder.isSupported ? handleStartRecording : undefined}
+                        >
+                            <Mic size={16} />
+                            <p className="unselectable">{t("recordAudio")}</p>
+                        </div>
+                    </div>
+                )}
+
+                {/* Recording indicator */}
+                {recorder.isRecording && (
+                    <div className={styles.recording_indicator}>
+                        <span className={styles.recording_dot} />
+                        <span className={styles.recording_time}>
+                            {formatRecordingTime(recorder.elapsed)}
+                        </span>
+                        <button className={styles.recording_stop} onClick={handleStopRecording}>
+                            <Square size={12} />
+                            <span className="unselectable">{t("stopRecording")}</span>
+                        </button>
+                    </div>
+                )}
+
                 {/* Arrow Context Menu */}
                 {arrowContextMenu && (
                     <div
diff --git a/components/board/BoardCard.tsx b/components/board/BoardCard.tsx
index 60166e9f..c2b3d963 100644
--- a/components/board/BoardCard.tsx
+++ b/components/board/BoardCard.tsx
@@ -3,9 +3,281 @@
 import { useRef, useState, useCallback, useEffect } from "react";
 import styles from "./BoardCanvas.module.css";
 import { useTranslations } from "next-intl";
+import { Play, Pause } from "lucide-react";
 import { BoardCardData } from "@src/lib/project/project-state";
 import { useAssetUrl } from "@src/lib/assets/use-asset-url";
 
+/** Join truthy class names (false/undefined are skipped). */
+const cx = (...parts: (string | false | undefined)[]) => parts.filter(Boolean).join(" ");
+
+/** The card kind, defaulting legacy/undefined cards to plain text notes. */
+type CardKind = NonNullable<BoardCardData["type"]>;
+const kindOf = (card: BoardCardData): CardKind => card.type ?? "text";
+
+/** Smallest height (canvas px) a card can be resized to, by kind. */
+const minHeightFor = (kind: CardKind) => (kind === "audio" ? 76 : 100);
+
+/** Seconds → `m:ss` (clamped at 0), for the audio timer. */
+function formatTime(seconds: number): string {
+    const total = Math.max(0, Math.floor(seconds || 0));
+    const m = Math.floor(total / 60);
+    const s = total % 60;
+    return `${m}:${s.toString().padStart(2, "0")}`;
+}
+
+/**
+ * Inline color for the card chrome. Images are bare; text and audio notes carry
+ * a colored header/border like every other card.
+ */
+function cardColorStyle(card: BoardCardData): React.CSSProperties {
+    if (kindOf(card) === "image") return {};
+    return { borderColor: card.color, backgroundColor: card.color };
+}
+
+// ── Shared inline-editable title ─────────────────────────────────────────────
+
+interface TitleEditing {
+    editing: boolean;
+    value: string;
+    onChange: (value: string) => void;
+    onBlur: () => void;
+    onKeyDown: (e: React.KeyboardEvent) => void;
+    onStartEdit: (e: React.MouseEvent) => void;
+}
+
+interface EditableTitleProps extends TitleEditing {
+    /** Text shown when not editing (e.g. the title or a placeholder hint). */
+    display: string;
+    placeholder: string;
+    inputClassName: string;
+    labelClassName: string;
+    /** Optional tooltip on the read-only label. */
+    labelTitle?: string;
+}
+
+const EditableTitle = ({
+    editing,
+    value,
+    display,
+    placeholder,
+    inputClassName,
+    labelClassName,
+    labelTitle,
+    onChange,
+    onBlur,
+    onKeyDown,
+    onStartEdit,
+}: EditableTitleProps) =>
+    editing ? (
+        <input
+            type="text"
+            className={inputClassName}
+            value={value}
+            onChange={(e) => onChange(e.target.value)}
+            onBlur={onBlur}
+            onKeyDown={onKeyDown}
+            onClick={(e) => e.stopPropagation()}
+            onMouseDown={(e) => e.stopPropagation()}
+            placeholder={placeholder}
+            autoFocus
+        />
+    ) : (
+        <span className={labelClassName} onDoubleClick={onStartEdit} title={labelTitle}>
+            {display}
+        </span>
+    );
+
+// ── Card body variants ───────────────────────────────────────────────────────
+
+const ImageBody = ({ projectId, card }: { projectId: string; card: BoardCardData }) => {
+    const imageUrl = useAssetUrl(projectId, card.assetId);
+    if (!imageUrl) return <div className={styles.card_image_placeholder} />;
+    // Blob object URLs can't be optimized by next/image; a plain <img> is correct here.
+    // eslint-disable-next-line @next/next/no-img-element
+    return <img src={imageUrl} alt="" draggable={false} className={styles.card_image} />;
+};
+
+const AudioBody = ({
+    projectId,
+    card,
+    title,
+}: {
+    projectId: string;
+    card: BoardCardData;
+    title: TitleEditing;
+}) => {
+    const t = useTranslations("board");
+    const assetUrl = useAssetUrl(projectId, card.assetId);
+    const audioRef = useRef<HTMLAudioElement>(null);
+    const [isPlaying, setIsPlaying] = useState(false);
+    const [duration, setDuration] = useState(0);
+    const [currentTime, setCurrentTime] = useState(0);
+    // MediaRecorder blobs report duration as Infinity until forced to seek past
+    // the end; this flag drives the one-shot fix-up below.
+    const fixDuration = useRef(false);
+
+    const togglePlay = useCallback((e: React.MouseEvent) => {
+        e.stopPropagation();
+        const audio = audioRef.current;
+        if (!audio) return;
+        if (audio.paused) void audio.play();
+        else audio.pause();
+    }, []);
+
+    const handleLoadedMetadata = useCallback(() => {
+        const audio = audioRef.current;
+        if (!audio) return;
+        if (isFinite(audio.duration)) {
+            setDuration(audio.duration);
+        } else {
+            fixDuration.current = true;
+            audio.currentTime = 1e7; // nudge the browser to compute real duration
+        }
+    }, []);
+
+    const handleTimeUpdate = useCallback(() => {
+        const audio = audioRef.current;
+        if (!audio) return;
+        if (fixDuration.current) {
+            fixDuration.current = false;
+            setDuration(isFinite(audio.duration) ? audio.duration : 0);
+            audio.currentTime = 0;
+            setCurrentTime(0);
+            return;
+        }
+        setCurrentTime(audio.currentTime);
+    }, []);
+
+    const handleSeek = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+        const value = Number(e.target.value);
+        if (audioRef.current) audioRef.current.currentTime = value;
+        setCurrentTime(value);
+    }, []);
+
+    return (
+        <>
+            <div className={styles.card_header} style={{ backgroundColor: card.color }}>
+                <EditableTitle
+                    {...title}
+                    display={card.title || t("audioHint")}
+                    placeholder={t("titlePlaceholder")}
+                    inputClassName={styles.card_header_title_input}
+                    labelClassName={styles.card_header_title}
+                    labelTitle={t("rename")}
+                />
+            </div>
+
+            <div
+                className={styles.audio_content}
+                style={{ backgroundColor: `color-mix(in srgb, ${card.color} 20%, white)` }}
+            >
+                <button
+                    className={styles.audio_play_btn}
+                    onClick={togglePlay}
+                    onMouseDown={(e) => e.stopPropagation()}
+                    title={isPlaying ? t("pause") : t("play")}
+                    disabled={!assetUrl}
+                >
+                    {isPlaying ? <Pause size={16} /> : <Play size={16} />}
+                </button>
+                <span className={styles.audio_time}>
+                    {formatTime(duration ? duration - currentTime : 0)}
+                </span>
+                <input
+                    type="range"
+                    className={styles.audio_timeline}
+                    min={0}
+                    max={duration || 0}
+                    step={0.01}
+                    value={Math.min(currentTime, duration || 0)}
+                    onChange={handleSeek}
+                    onMouseDown={(e) => e.stopPropagation()}
+                    disabled={!assetUrl || !duration}
+                    style={
+                        {
+                            "--audio-progress": `${duration ? (Math.min(currentTime, duration) / duration) * 100 : 0}%`,
+                        } as React.CSSProperties
+                    }
+                />
+                {assetUrl && (
+                    <audio
+                        ref={audioRef}
+                        src={assetUrl}
+                        onPlay={() => setIsPlaying(true)}
+                        onPause={() => setIsPlaying(false)}
+                        onEnded={() => setIsPlaying(false)}
+                        onLoadedMetadata={handleLoadedMetadata}
+                        onTimeUpdate={handleTimeUpdate}
+                    />
+                )}
+            </div>
+        </>
+    );
+};
+
+interface DescriptionEditing {
+    editing: boolean;
+    value: string;
+    onChange: (value: string) => void;
+    onBlur: () => void;
+    onKeyDown: (e: React.KeyboardEvent) => void;
+}
+
+const TextBody = ({
+    card,
+    title,
+    description,
+    onStartEditDescription,
+}: {
+    card: BoardCardData;
+    title: TitleEditing;
+    description: DescriptionEditing;
+    onStartEditDescription: (e: React.MouseEvent) => void;
+}) => {
+    const t = useTranslations("board");
+    return (
+        <>
+            <div className={styles.card_header} style={{ backgroundColor: card.color }}>
+                <EditableTitle
+                    {...title}
+                    display={card.title || t("untitled")}
+                    placeholder={t("titlePlaceholder")}
+                    inputClassName={styles.card_header_title_input}
+                    labelClassName={styles.card_header_title}
+                />
+            </div>
+
+            <div
+                className={styles.card_content}
+                style={{ backgroundColor: `color-mix(in srgb, ${card.color} 20%, white)` }}
+                onDoubleClick={onStartEditDescription}
+            >
+                <p
+                    className={styles.card_description}
+                    style={{ display: description.editing ? "none" : undefined }}
+                >
+                    {card.description}
+                </p>
+                {description.editing && (
+                    <textarea
+                        className={styles.card_description_input}
+                        value={description.value}
+                        onChange={(e) => description.onChange(e.target.value)}
+                        onBlur={description.onBlur}
+                        onKeyDown={description.onKeyDown}
+                        onClick={(e) => e.stopPropagation()}
+                        onMouseDown={(e) => e.stopPropagation()}
+                        placeholder={t("descriptionPlaceholder")}
+                        autoFocus
+                    />
+                )}
+            </div>
+        </>
+    );
+};
+
+// ── Card container (shared chrome: drag, resize, connect, context menu) ───────
+
 interface BoardCardProps {
     card: BoardCardData;
     projectId: string;
@@ -33,10 +305,7 @@ const BoardCard = ({
     isConnecting,
     isSelected,
 }: BoardCardProps) => {
-    const isImage = card.type === "image";
-    // Only resolves bytes for image cards (null assetId is a no-op for text notes).
-    const imageUrl = useAssetUrl(projectId, isImage ? card.assetId : null);
-    const t = useTranslations("board");
+    const kind = kindOf(card);
     const cardRef = useRef<HTMLDivElement>(null);
     const [isDragging, setIsDragging] = useState(false);
     const [isEditing, setIsEditing] = useState(false);
@@ -70,7 +339,11 @@ const BoardCard = ({
 
     const handleMouseDown = useCallback(
         (e: React.MouseEvent) => {
-            if (isEditing || isEditingTitle || (e.target as HTMLElement).closest(`.${styles.card_resize_handle}`))
+            if (
+                isEditing ||
+                isEditingTitle ||
+                (e.target as HTMLElement).closest(`.${styles.card_resize_handle}`)
+            )
                 return;
             e.stopPropagation();
             e.preventDefault(); // Prevent Chromium's text selection from interfering with drag
@@ -99,11 +372,7 @@ const BoardCard = ({
                 const newX = (e.clientX - parentRect.left) / scale - dragOffset.current.x;
                 const newY = (e.clientY - parentRect.top) / scale - dragOffset.current.y;
 
-                onUpdate({
-                    ...card,
-                    x: snapToGrid(newX),
-                    y: snapToGrid(newY),
-                });
+                onUpdate({ ...card, x: snapToGrid(newX), y: snapToGrid(newY) });
             }
 
             if (isResizing) {
@@ -111,16 +380,12 @@ const BoardCard = ({
                 const dy = (e.clientY - resizeStart.current.y) / scale;
 
                 const newWidth = Math.max(150, resizeStart.current.width + dx);
-                const newHeight = Math.max(100, resizeStart.current.height + dy);
+                const newHeight = Math.max(minHeightFor(kind), resizeStart.current.height + dy);
 
-                onUpdate({
-                    ...card,
-                    width: snapToGrid(newWidth),
-                    height: snapToGrid(newHeight),
-                });
+                onUpdate({ ...card, width: snapToGrid(newWidth), height: snapToGrid(newHeight) });
             }
         },
-        [isDragging, isResizing, card, onUpdate, scale, snapToGrid],
+        [isDragging, isResizing, kind, card, onUpdate, scale, snapToGrid],
     );
 
     const handleMouseUp = useCallback(() => {
@@ -154,12 +419,12 @@ const BoardCard = ({
         }
     }, [isDragging, isResizing, handleMouseMove, handleMouseUp]);
 
-    const handleDoubleClick = useCallback((e: React.MouseEvent) => {
+    const handleStartEditDescription = useCallback((e: React.MouseEvent) => {
         e.stopPropagation();
         setIsEditing(true);
     }, []);
 
-    const handleTitleDoubleClick = useCallback((e: React.MouseEvent) => {
+    const handleStartEditTitle = useCallback((e: React.MouseEvent) => {
         e.stopPropagation();
         setIsEditingTitle(true);
     }, []);
@@ -167,20 +432,14 @@ const BoardCard = ({
     const handleTitleBlur = useCallback(() => {
         setIsEditingTitle(false);
         if (localTitle !== card.title) {
-            onUpdate({
-                ...card,
-                title: localTitle,
-            });
+            onUpdate({ ...card, title: localTitle });
         }
     }, [card, localTitle, onUpdate]);
 
     const handleDescriptionBlur = useCallback(() => {
         setIsEditing(false);
         if (localDescription !== card.description) {
-            onUpdate({
-                ...card,
-                description: localDescription,
-            });
+            onUpdate({ ...card, description: localDescription });
         }
     }, [card, localDescription, onUpdate]);
 
@@ -240,77 +499,63 @@ const BoardCard = ({
         [card.id, isConnecting, onCompleteConnection],
     );
 
+    const titleEditing: TitleEditing = {
+        editing: isEditingTitle,
+        value: localTitle,
+        onChange: setLocalTitle,
+        onBlur: handleTitleBlur,
+        onKeyDown: handleTitleKeyDown,
+        onStartEdit: handleStartEditTitle,
+    };
+
+    const renderBody = () => {
+        switch (kind) {
+            case "image":
+                return <ImageBody projectId={projectId} card={card} />;
+            case "audio":
+                return <AudioBody projectId={projectId} card={card} title={titleEditing} />;
+            default:
+                return (
+                    <TextBody
+                        card={card}
+                        title={titleEditing}
+                        description={{
+                            editing: isEditing,
+                            value: localDescription,
+                            onChange: setLocalDescription,
+                            onBlur: handleDescriptionBlur,
+                            onKeyDown: handleDescriptionKeyDown,
+                        }}
+                        onStartEditDescription={handleStartEditDescription}
+                    />
+                );
+        }
+    };
+
     return (
         <div
             ref={cardRef}
-            className={`${styles.card} ${isImage ? styles.image_card : ""} ${isDragging ? styles.card_dragging : ""} ${isConnecting ? styles.card_connecting : ""} ${isSelected ? styles.card_selected : ""}`}
+            className={cx(
+                styles.card,
+                kind === "image" && styles.image_card,
+                kind === "audio" && styles.audio_card,
+                isDragging && styles.card_dragging,
+                isConnecting && styles.card_connecting,
+                isSelected && styles.card_selected,
+            )}
             style={{
                 left: card.x,
                 top: card.y,
                 width: card.width,
                 height: card.height,
-                ...(isImage ? {} : { borderColor: card.color, backgroundColor: card.color }),
+                ...cardColorStyle(card),
             }}
             onMouseDown={handleMouseDown}
             onMouseUp={handleCardMouseUp}
-            onDoubleClick={isImage ? undefined : handleDoubleClick}
+            onDoubleClick={kind === "text" ? handleStartEditDescription : undefined}
             onContextMenu={handleRightClick}
         >
-            {isImage ? (
-                imageUrl ? (
-                    // Blob object URLs can't be optimized by next/image; a plain <img> is correct here.
-                    // eslint-disable-next-line @next/next/no-img-element
-                    <img src={imageUrl} alt="" draggable={false} className={styles.card_image} />
-                ) : (
-                    <div className={styles.card_image_placeholder} />
-                )
-            ) : (
-                <>
-                    <div className={styles.card_header} style={{ backgroundColor: card.color }}>
-                        {isEditingTitle ? (
-                            <input
-                                type="text"
-                                className={styles.card_header_title_input}
-                                value={localTitle}
-                                onChange={(e) => setLocalTitle(e.target.value)}
-                                onBlur={handleTitleBlur}
-                                onKeyDown={handleTitleKeyDown}
-                                onClick={(e) => e.stopPropagation()}
-                                onMouseDown={(e) => e.stopPropagation()}
-                                placeholder={t("titlePlaceholder")}
-                                autoFocus
-                            />
-                        ) : (
-                            <span className={styles.card_header_title} onDoubleClick={handleTitleDoubleClick}>
-                                {card.title || t("untitled")}
-                            </span>
-                        )}
-                    </div>
-
-                    <div
-                        className={styles.card_content}
-                        style={{ backgroundColor: `color-mix(in srgb, ${card.color} 20%, white)` }}
-                        onDoubleClick={handleDoubleClick}
-                    >
-                        <p className={styles.card_description} style={{ display: isEditing ? "none" : undefined }}>
-                            {card.description}
-                        </p>
-                        {isEditing && (
-                            <textarea
-                                className={styles.card_description_input}
-                                value={localDescription}
-                                onChange={(e) => setLocalDescription(e.target.value)}
-                                onBlur={handleDescriptionBlur}
-                                onKeyDown={handleDescriptionKeyDown}
-                                onClick={(e) => e.stopPropagation()}
-                                onMouseDown={(e) => e.stopPropagation()}
-                                placeholder={t("descriptionPlaceholder")}
-                                autoFocus
-                            />
-                        )}
-                    </div>
-                </>
-            )}
+            {renderBody()}
 
             <div className={styles.card_resize_handle} onMouseDown={handleResizeStart} />
 
diff --git a/components/board/use-audio-recorder.ts b/components/board/use-audio-recorder.ts
new file mode 100644
index 00000000..fbfea0a6
--- /dev/null
+++ b/components/board/use-audio-recorder.ts
@@ -0,0 +1,118 @@
+"use client";
+
+/**
+ * Minimal microphone recorder for board voice notes.
+ *
+ * Recording is gated to MP4/AAC (`audio/mp4`) so every captured clip plays in
+ * any browser and survives `.scriptio` export/import. Browsers whose
+ * `MediaRecorder` can't produce MP4 (e.g. Firefox) report `isSupported: false`;
+ * the UI then hides the record action and the user drags in an audio file
+ * instead. Dropped files keep their original format.
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/** The single recording mime we accept — AAC in an MP4 container. */
+export const RECORDING_MIME = "audio/mp4";
+
+/** Can this browser record directly to MP4/AAC? */
+export function isAudioRecordingSupported(): boolean {
+    return (
+        typeof MediaRecorder !== "undefined" &&
+        typeof MediaRecorder.isTypeSupported === "function" &&
+        MediaRecorder.isTypeSupported(RECORDING_MIME)
+    );
+}
+
+export interface AudioRecorder {
+    /** True only when in-browser MP4/AAC recording is available. */
+    isSupported: boolean;
+    /** True while a recording is in progress. */
+    isRecording: boolean;
+    /** Elapsed recording time in whole seconds. */
+    elapsed: number;
+    /** Begin recording; resolves once the mic stream is live. */
+    start: () => Promise<void>;
+    /** Stop recording and resolve the captured clip (`null` if nothing/failed). */
+    stop: () => Promise<Blob | null>;
+    /** Stop and discard the current recording. */
+    cancel: () => void;
+}
+
+export function useAudioRecorder(): AudioRecorder {
+    // Lazy init: `false` during SSR (MediaRecorder is undefined there). Nothing
+    // depending on it is in the initial DOM, so the client value can't mismatch.
+    const [isSupported] = useState(() => isAudioRecordingSupported());
+    const [isRecording, setIsRecording] = useState(false);
+    const [elapsed, setElapsed] = useState(0);
+
+    const recorderRef = useRef<MediaRecorder | null>(null);
+    const chunksRef = useRef<Blob[]>([]);
+    const streamRef = useRef<MediaStream | null>(null);
+    const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+
+    const teardown = useCallback(() => {
+        if (timerRef.current) {
+            clearInterval(timerRef.current);
+            timerRef.current = null;
+        }
+        streamRef.current?.getTracks().forEach((track) => track.stop());
+        streamRef.current = null;
+        recorderRef.current = null;
+        setIsRecording(false);
+    }, []);
+
+    const start = useCallback(async () => {
+        if (recorderRef.current) return;
+        const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+        streamRef.current = stream;
+        chunksRef.current = [];
+
+        const recorder = new MediaRecorder(stream, { mimeType: RECORDING_MIME });
+        recorder.ondataavailable = (e) => {
+            if (e.data.size > 0) chunksRef.current.push(e.data);
+        };
+        recorderRef.current = recorder;
+        recorder.start();
+
+        setElapsed(0);
+        setIsRecording(true);
+        timerRef.current = setInterval(() => setElapsed((s) => s + 1), 1000);
+    }, []);
+
+    const stop = useCallback((): Promise<Blob | null> => {
+        const recorder = recorderRef.current;
+        if (!recorder) return Promise.resolve(null);
+
+        return new Promise<Blob | null>((resolve) => {
+            recorder.onstop = () => {
+                const blob = chunksRef.current.length
+                    ? new Blob(chunksRef.current, { type: RECORDING_MIME })
+                    : null;
+                chunksRef.current = [];
+                teardown();
+                resolve(blob);
+            };
+            recorder.stop();
+        });
+    }, [teardown]);
+
+    const cancel = useCallback(() => {
+        const recorder = recorderRef.current;
+        if (recorder) {
+            recorder.onstop = null;
+            try {
+                recorder.stop();
+            } catch {
+                // already inactive
+            }
+        }
+        chunksRef.current = [];
+        teardown();
+    }, [teardown]);
+
+    // Release the mic if the component unmounts mid-recording.
+    useEffect(() => () => teardown(), [teardown]);
+
+    return { isSupported, isRecording, elapsed, start, stop, cancel };
+}
diff --git a/messages/de.json b/messages/de.json
index baff18ef..6d5cdadf 100644
--- a/messages/de.json
+++ b/messages/de.json
@@ -482,7 +482,14 @@
     },
     "untitled": "Unbenannt",
     "titlePlaceholder": "Titel",
-    "descriptionPlaceholder": "Beschreibung"
+    "descriptionPlaceholder": "Beschreibung",
+    "recordAudio": "Audio aufnehmen",
+    "stopRecording": "Stopp",
+    "audioUnsupported": "Audioaufnahme wird in diesem Browser nicht unterstützt – ziehen Sie stattdessen eine Audiodatei hierher",
+    "audioHint": "Sprachnotiz",
+    "play": "Abspielen",
+    "pause": "Pause",
+    "rename": "Zum Umbenennen doppelklicken"
   },
   "production": {
     "title": "Produktion",
diff --git a/messages/en.json b/messages/en.json
index 230c0599..b1074dae 100644
--- a/messages/en.json
+++ b/messages/en.json
@@ -481,7 +481,14 @@
     },
     "untitled": "Untitled",
     "titlePlaceholder": "Title",
-    "descriptionPlaceholder": "Description"
+    "descriptionPlaceholder": "Description",
+    "recordAudio": "Record audio",
+    "stopRecording": "Stop",
+    "audioUnsupported": "Audio recording isn't supported in this browser — drag in an audio file instead",
+    "audioHint": "Voice note",
+    "play": "Play",
+    "pause": "Pause",
+    "rename": "Double-click to rename"
   },
   "production": {
     "title": "Production",
diff --git a/messages/es.json b/messages/es.json
index f952198f..dc9f87e7 100644
--- a/messages/es.json
+++ b/messages/es.json
@@ -481,7 +481,14 @@
     },
     "untitled": "Sin título",
     "titlePlaceholder": "Título",
-    "descriptionPlaceholder": "Descripción"
+    "descriptionPlaceholder": "Descripción",
+    "recordAudio": "Grabar audio",
+    "stopRecording": "Detener",
+    "audioUnsupported": "La grabación de audio no es compatible con este navegador: arrastra un archivo de audio en su lugar",
+    "audioHint": "Nota de voz",
+    "play": "Reproducir",
+    "pause": "Pausar",
+    "rename": "Doble clic para renombrar"
   },
   "production": {
     "title": "Producción",
diff --git a/messages/fr.json b/messages/fr.json
index e6f11028..7944f2e5 100644
--- a/messages/fr.json
+++ b/messages/fr.json
@@ -482,7 +482,14 @@
     },
     "untitled": "Sans titre",
     "titlePlaceholder": "Titre",
-    "descriptionPlaceholder": "Description"
+    "descriptionPlaceholder": "Description",
+    "recordAudio": "Enregistrer un audio",
+    "stopRecording": "Arrêter",
+    "audioUnsupported": "L'enregistrement audio n'est pas pris en charge par ce navigateur — glissez plutôt un fichier audio",
+    "audioHint": "Note vocale",
+    "play": "Lire",
+    "pause": "Pause",
+    "rename": "Double-cliquez pour renommer"
   },
   "production": {
     "title": "Production",
diff --git a/messages/ja.json b/messages/ja.json
index 314543d3..dfd4307f 100644
--- a/messages/ja.json
+++ b/messages/ja.json
@@ -481,7 +481,14 @@
     },
     "untitled": "無題",
     "titlePlaceholder": "タイトル",
-    "descriptionPlaceholder": "説明"
+    "descriptionPlaceholder": "説明",
+    "recordAudio": "音声を録音",
+    "stopRecording": "停止",
+    "audioUnsupported": "このブラウザは音声録音に対応していません。代わりに音声ファイルをドラッグしてください",
+    "audioHint": "ボイスメモ",
+    "play": "再生",
+    "pause": "一時停止",
+    "rename": "ダブルクリックで名前を変更"
   },
   "production": {
     "title": "プロダクション",
diff --git a/messages/ko.json b/messages/ko.json
index fa4c2f24..66a42000 100644
--- a/messages/ko.json
+++ b/messages/ko.json
@@ -481,7 +481,14 @@
     },
     "untitled": "제목 없음",
     "titlePlaceholder": "제목",
-    "descriptionPlaceholder": "설명"
+    "descriptionPlaceholder": "설명",
+    "recordAudio": "오디오 녹음",
+    "stopRecording": "정지",
+    "audioUnsupported": "이 브라우저에서는 오디오 녹음을 지원하지 않습니다. 대신 오디오 파일을 끌어다 놓으세요",
+    "audioHint": "음성 메모",
+    "play": "재생",
+    "pause": "일시정지",
+    "rename": "더블클릭하여 이름 변경"
   },
   "production": {
     "title": "프로덕션",
diff --git a/messages/pl.json b/messages/pl.json
index 2c0c51f3..fa8714cb 100644
--- a/messages/pl.json
+++ b/messages/pl.json
@@ -481,7 +481,14 @@
     },
     "untitled": "Bez tytułu",
     "titlePlaceholder": "Tytuł",
-    "descriptionPlaceholder": "Opis"
+    "descriptionPlaceholder": "Opis",
+    "recordAudio": "Nagraj dźwięk",
+    "stopRecording": "Zatrzymaj",
+    "audioUnsupported": "Nagrywanie dźwięku nie jest obsługiwane w tej przeglądarce — przeciągnij plik audio",
+    "audioHint": "Notatka głosowa",
+    "play": "Odtwórz",
+    "pause": "Wstrzymaj",
+    "rename": "Kliknij dwukrotnie, aby zmienić nazwę"
   },
   "production": {
     "title": "Produkcja",
diff --git a/messages/zh.json b/messages/zh.json
index 3453b649..c2f1eeb9 100644
--- a/messages/zh.json
+++ b/messages/zh.json
@@ -481,7 +481,14 @@
     },
     "untitled": "未命名",
     "titlePlaceholder": "标题",
-    "descriptionPlaceholder": "描述"
+    "descriptionPlaceholder": "描述",
+    "recordAudio": "录制音频",
+    "stopRecording": "停止",
+    "audioUnsupported": "此浏览器不支持录音，请改为拖入音频文件",
+    "audioHint": "语音备注",
+    "play": "播放",
+    "pause": "暂停",
+    "rename": "双击重命名"
   },
   "production": {
     "title": "制作",
diff --git a/src/lib/adapters/scriptio/scriptio-adapter.ts b/src/lib/adapters/scriptio/scriptio-adapter.ts
index bb415c9f..9d194e8c 100644
--- a/src/lib/adapters/scriptio/scriptio-adapter.ts
+++ b/src/lib/adapters/scriptio/scriptio-adapter.ts
@@ -102,6 +102,19 @@ function extensionForMime(mime: string): string {
             return ".bmp";
         case "image/svg+xml":
             return ".svg";
+        case "audio/mp4":
+            return ".m4a";
+        case "audio/aac":
+            return ".aac";
+        case "audio/mpeg":
+            return ".mp3";
+        case "audio/wav":
+        case "audio/x-wav":
+            return ".wav";
+        case "audio/ogg":
+            return ".ogg";
+        case "audio/webm":
+            return ".webm";
         default:
             return "";
     }
diff --git a/src/lib/assets/asset-gc.ts b/src/lib/assets/asset-gc.ts
index 7bd30100..5a679a08 100644
--- a/src/lib/assets/asset-gc.ts
+++ b/src/lib/assets/asset-gc.ts
@@ -12,7 +12,7 @@ import type { BoardCardData } from "../project/project-doc";
 import type { ProjectState } from "../project/project-state";
 import { getStorageProvider } from "../persistence/storage-provider/storage-provider";
 
-/** Every asset hash referenced by an image card across all board documents. */
+/** Every asset hash referenced by an image or audio card across all board documents. */
 export function collectReferencedHashes(ydoc: ProjectState): Set<string> {
     const referenced = new Set<string>();
     ydoc.documents().forEach((node) => {
@@ -22,7 +22,8 @@ export function collectReferencedHashes(ydoc: ProjectState): Set<string> {
         try {
             const cards = JSON.parse(raw) as BoardCardData[];
             for (const card of cards) {
-                if (card.type === "image" && card.assetId) referenced.add(card.assetId);
+                if ((card.type === "image" || card.type === "audio") && card.assetId)
+                    referenced.add(card.assetId);
             }
         } catch {
             // A malformed cards blob shouldn't make us delete live assets — skip.
diff --git a/src/lib/assets/asset-store.ts b/src/lib/assets/asset-store.ts
index d2b8508a..3be5829b 100644
--- a/src/lib/assets/asset-store.ts
+++ b/src/lib/assets/asset-store.ts
@@ -76,6 +76,50 @@ export async function importImageFile(projectId: string, file: File): Promise<As
     return { hash, mime, width, height };
 }
 
+/** The base mime type without any `;codecs=...` parameters. */
+function baseMime(mime: string): string {
+    return mime.split(";")[0].trim();
+}
+
+/**
+ * Store an audio file (a recording or a dropped file) for a project and return
+ * its metadata. Like {@link importImageFile} but audio has no intrinsic pixel
+ * size, so `width`/`height` are stored as `0`. Idempotent (dedup by SHA-256).
+ *
+ * `mime` may be passed explicitly because recorded blobs sometimes carry a
+ * `;codecs=...` suffix; it is normalized to the base type before storing.
+ */
+export async function importAudioFile(
+    projectId: string,
+    file: Blob,
+    mime?: string,
+): Promise<AssetMeta> {
+    const buffer = await file.arrayBuffer();
+    const hash = await sha256Hex(buffer);
+    const resolvedMime = baseMime(mime || file.type || "audio/mp4");
+
+    const provider = await getStorageProvider();
+
+    const existing = await provider.getAsset(projectId, hash);
+    if (existing) {
+        return { hash, mime: existing.mime, width: existing.width, height: existing.height };
+    }
+
+    await provider.putAsset({
+        key: `${projectId}/${hash}`,
+        projectId,
+        hash,
+        mime: resolvedMime,
+        size: file.size,
+        width: 0,
+        height: 0,
+        data: buffer,
+        createdAt: Date.now(),
+    });
+
+    return { hash, mime: resolvedMime, width: 0, height: 0 };
+}
+
 /**
  * Resolve an asset to an object URL for rendering, or null if it isn't stored
  * locally. Callers own the URL and must `URL.revokeObjectURL` it when done.
diff --git a/src/lib/project/project-doc.ts b/src/lib/project/project-doc.ts
index 8c20cd45..19411c2b 100644
--- a/src/lib/project/project-doc.ts
+++ b/src/lib/project/project-doc.ts
@@ -155,12 +155,15 @@ export interface BoardCardData {
     y: number;
     width: number;
     height: number;
-    /** Card kind. `undefined`/"text" is the default note card; "image" renders a resource. */
-    type?: "text" | "image";
     /**
-     * For `type: "image"` cards: the SHA-256 hash of the source image, which is
-     * stored separately in IndexedDB (decoupled from Yjs). The bytes never live
-     * in the document — only this reference does.
+     * Card kind. `undefined`/"text" is the default note card; "image" renders a
+     * picture resource; "audio" renders a voice note with a play/pause control.
+     */
+    type?: "text" | "image" | "audio";
+    /**
+     * For `type: "image"`/`"audio"` cards: the SHA-256 hash of the source bytes,
+     * which are stored separately in IndexedDB (decoupled from Yjs). The bytes
+     * never live in the document — only this reference does.
      */
     assetId?: string;
 }
diff --git a/src/tests/assets/assets.test.ts b/src/tests/assets/assets.test.ts
index 48d84e56..71519a4e 100644
--- a/src/tests/assets/assets.test.ts
+++ b/src/tests/assets/assets.test.ts
@@ -1,7 +1,7 @@
 import { beforeAll, describe, it, expect } from "vitest";
 
 import { sha256Hex } from "@src/lib/assets/asset-hash";
-import { importImageFile, loadAssetObjectUrl } from "@src/lib/assets/asset-store";
+import { importImageFile, importAudioFile, loadAssetObjectUrl } from "@src/lib/assets/asset-store";
 import { collectReferencedHashes, gcProjectAssets } from "@src/lib/assets/asset-gc";
 import {
     getStorageProvider,
@@ -230,6 +230,49 @@ describe("scriptio asset bundling", () => {
         ydoc.destroy();
     });
 
+    it("bundles board audio assets into the archive and restores them", async () => {
+        const provider = await getStorageProvider();
+        const src = pid();
+
+        // A board referencing a recorded/dropped audio clip (synthetic bytes).
+        const blobIn = new Blob([new Uint8Array([1, 2, 3, 4, 5])], { type: "audio/mp4" });
+        const { hash } = await importAudioFile(src, blobIn);
+
+        const ydoc = new ProjectState();
+        const repo = createProjectRepository(ydoc)!;
+        const board = repo.createBoardDocument("B");
+        ydoc.boardData(board).set(
+            "cards",
+            JSON.stringify([{ id: "c1", type: "audio", assetId: hash, ...cardBase }]),
+        );
+
+        const adapter = new ScriptioAdapter();
+        const blob = await adapter.convertTo(ydoc, {
+            title: "t",
+            author: "a",
+            includeNotes: false,
+            projectId: src,
+        });
+        const buffer = await blob.arrayBuffer();
+
+        const parsed = adapter.convertFrom(buffer);
+        expect(parsed.boards?.[board]?.cards).toContain(hash);
+
+        // Audio cards keep their assets referenced (GC must not drop them).
+        expect(collectReferencedHashes(ydoc).has(hash)).toBe(true);
+
+        const dest = pid();
+        await restoreScriptioAssets(dest, buffer);
+
+        const restored = await provider.getAsset(dest, hash);
+        expect(restored?.mime).toBe("audio/mp4");
+        expect(await sha256Hex(restored!.data)).toBe(hash);
+
+        await provider.deleteProjectAssets(src);
+        await provider.deleteProjectAssets(dest);
+        ydoc.destroy();
+    });
+
     it("exports a document with no assets and restore is a no-op", async () => {
         const ydoc = new ProjectState();
         const repo = createProjectRepository(ydoc)!;
diff --git a/styles/themes.css b/styles/themes.css
index ff2484af..ce4c0626 100644
--- a/styles/themes.css
+++ b/styles/themes.css
@@ -44,6 +44,7 @@ html.light {
     --editor-style-bg-active: #f1f5f9;
     --editor-element-hover: #f8fafc;
     --editor-shadow: rgba(0, 0, 0, 0.15);
+    --board-card-body-text: var(--primary-text);
 
     --editor-scroll-bg: var(--secondary);
     --editor-scroll-btn: var(--tertiary);
@@ -91,6 +92,7 @@ html.dark {
     --editor-style-bg-active: #5d5d5d;
     --editor-element-hover: #eeeeee;
     --editor-shadow: rgba(0, 0, 0, 0.4);
+    --board-card-body-text: var(--primary);
 
     --editor-scroll-bg: var(--secondary);
     --editor-scroll-btn: var(--tertiary);
@@ -142,6 +144,7 @@ html.latte {
     --editor-style-bg-active: var(--primary-hover);
     --editor-element-hover: #f8fafc;
     --editor-shadow: #c7b28563;
+    --board-card-body-text: var(--primary-text);
 
     --editor-scroll-bg: var(--secondary);
     --editor-scroll-btn: var(--tertiary);
@@ -189,6 +192,7 @@ html.wonka {
     --editor-style-bg-active: var(--primary-hover);
     --editor-element-hover: #f8fafc;
     --editor-shadow: rgba(0, 0, 0, 0.4);
+    --board-card-body-text: var(--primary);
 
     --editor-scroll-bg: var(--secondary);
     --editor-scroll-btn: var(--tertiary);
@@ -236,6 +240,7 @@ html.mint {
     --editor-style-bg-active: var(--primary-hover);
     --editor-element-hover: #f8fafc;
     --editor-shadow: #9bc29e81;
+    --board-card-body-text: var(--primary-text);
 
     --editor-scroll-bg: var(--secondary);
     --editor-scroll-btn: var(--tertiary);
@@ -283,6 +288,7 @@ html.blossom {
     --editor-style-bg-active: var(--primary-hover);
     --editor-element-hover: #f8fafc;
     --editor-shadow: #ffbaffa6;
+    --board-card-body-text: var(--primary-text);
 
     --editor-scroll-bg: var(--secondary);
     --editor-scroll-btn: var(--tertiary);
@@ -330,6 +336,7 @@ html.midnight {
     --editor-style-bg-active: #263554;
     --editor-element-hover: #c8d8f0;
     --editor-shadow: rgba(0, 0, 30, 0.6);
+    --board-card-body-text: var(--primary);
 
     --editor-scroll-bg: var(--secondary);
     --editor-scroll-btn: var(--tertiary);