diff --git a/components/board/BoardCanvas.tsx b/components/board/BoardCanvas.tsx
index 91bfcd93..b0dee478 100644
--- a/components/board/BoardCanvas.tsx
+++ b/components/board/BoardCanvas.tsx
@@ -2,7 +2,7 @@
 
 import { useContext, useRef, useState, useCallback, useEffect, useMemo } from "react";
 import { ProjectContext } from "@src/context/ProjectContext";
-import { getBoardMap, BoardCardData, BoardArrowData } from "@src/lib/project/project-state";
+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";
@@ -36,9 +36,9 @@ interface ArrowContextMenuState {
 }
 
 const BoardCanvas = ({ isVisible }: { isVisible: boolean }) => {
-    const { repository, isYjsReady } = useContext(ProjectContext);
+    const { repository, isYjsReady, isReadOnly } = useContext(ProjectContext);
     const t = useTranslations("board");
-    const ydoc = repository?.getState();
+    const projectState = repository?.getState();
     const containerRef = useRef<HTMLDivElement>(null);
     const canvasRef = useRef<HTMLDivElement>(null);
 
@@ -123,9 +123,9 @@ const BoardCanvas = ({ isVisible }: { isVisible: boolean }) => {
 
     // Sync cards with Yjs
     useEffect(() => {
-        if (!ydoc || !isYjsReady) return;
+        if (!projectState || !isYjsReady) return;
 
-        const boardMap = getBoardMap(ydoc);
+        const boardMap = projectState.board();
 
         const syncCards = () => {
             const cardsData = boardMap.get("cards");
@@ -176,26 +176,26 @@ const BoardCanvas = ({ isVisible }: { isVisible: boolean }) => {
         return () => {
             boardMap.unobserve(syncCards);
         };
-    }, [ydoc, isYjsReady, centerCameraOnCards]);
+    }, [projectState, isYjsReady, centerCameraOnCards]);
 
     // Save cards to Yjs
     const saveCards = useCallback(
         (newCards: BoardCardData[]) => {
-            if (!ydoc || !isYjsReady) return;
-            const boardMap = getBoardMap(ydoc);
+            if (!projectState || !isYjsReady || isReadOnly) return;
+            const boardMap = projectState.board();
             boardMap.set("cards", JSON.stringify(newCards));
         },
-        [ydoc, isYjsReady],
+        [projectState, isYjsReady, isReadOnly],
     );
 
     // Save arrows to Yjs
     const saveArrows = useCallback(
         (newArrows: BoardArrowData[]) => {
-            if (!ydoc || !isYjsReady) return;
-            const boardMap = getBoardMap(ydoc);
+            if (!projectState || !isYjsReady || isReadOnly) return;
+            const boardMap = projectState.board();
             boardMap.set("arrows", JSON.stringify(newArrows));
         },
-        [ydoc, isYjsReady],
+        [projectState, isYjsReady, isReadOnly],
     );
 
     // Handle keyboard events for snapping
diff --git a/components/dashboard/project/CollaboratorsSettings.tsx b/components/dashboard/project/CollaboratorsSettings.tsx
index 286bf601..05f4b053 100644
--- a/components/dashboard/project/CollaboratorsSettings.tsx
+++ b/components/dashboard/project/CollaboratorsSettings.tsx
@@ -15,9 +15,7 @@ import styles from "./CollaboratorsSettings.module.css";
 import { deleteInvite, inviteCollaborator, kickCollaborator, updateMemberRole } from "@src/lib/utils/requests";
 
 import * as Roles from "@src/lib/utils/roles";
-import { ApiResponse } from "@src/lib/utils/api-utils";
 import { DashboardContext } from "@src/context/DashboardContext";
-import { redirect } from "next/navigation";
 import Link from "next/link";
 
 const MAX_COLLABORATORS = 5;
@@ -169,18 +167,17 @@ const MemberSlot = ({ data, membership, mutateCollaborators, user }: MemberSlotP
 
     const handleKick = async () => {
         const res = await kickCollaborator(membership.project.id, data.user.id);
-
-        if (res.ok) {
-            if (res.status !== 204) {
-                // If user left the project by himself, redirect him to home
-                const json = (await res.json()) as ApiResponse<{ redirectUrl: string }>;
-                if (json.data && json.data.redirectUrl) {
-                    closeDashboard();
-                    redirect(json.data.redirectUrl);
-                }
-            } else {
-                mutateCollaborators();
-            }
+        if (!res.ok) return;
+
+        if (isSelf) {
+            // Self-leave: the server has already deleted the membership and
+            // blacklisted the user on the WS, so a 4003 close is on its way.
+            // The cloud-sync hook surfaces ProjectUnavailableDialog from there,
+            // letting the leaver decide whether to keep a local copy or discard.
+            // We just close the dashboard so the dialog isn't covered.
+            closeDashboard();
+        } else {
+            mutateCollaborators();
         }
     };
 
diff --git a/components/editor/DocumentEditorPanel.tsx b/components/editor/DocumentEditorPanel.tsx
index d4d51123..cf5dada4 100644
--- a/components/editor/DocumentEditorPanel.tsx
+++ b/components/editor/DocumentEditorPanel.tsx
@@ -6,6 +6,8 @@ import { EditorContent } from "@tiptap/react";
 
 import { applyElement, insertElement, SCREENPLAY_FORMATS } from "@src/lib/screenplay/editor";
 import { ScreenplayElement } from "@src/lib/utils/enums";
+import { Eye } from "lucide-react";
+import { useTranslations } from "next-intl";
 import { DUAL_DIALOGUE_COLUMN } from "@src/lib/screenplay/nodes/dual-dialogue-column-node";
 import { DEFAULT_ELEMENT_MARGINS, DEFAULT_ELEMENT_STYLES } from "@src/lib/project/project-state";
 import { join } from "@src/lib/utils/misc";
@@ -59,6 +61,7 @@ const DocumentEditorPanel = ({
     const projectCtx = useContext(ProjectContext);
     const {
         isYjsReady,
+        isReadOnly,
         selectedElement,
         setSelectedElement,
         setSelectedStyles,
@@ -124,6 +127,17 @@ const DocumentEditorPanel = ({
         };
     }, [editor, onEditorCreated]);
 
+    // Read-only enforcement for VIEWER role.
+    //
+    // The server already drops doc writes from viewers (see protocol.ts), but
+    // disabling tiptap locally avoids a confusing "I typed but nothing
+    // happened" experience: keystrokes are blocked at the editor level and
+    // collaboration carets/awareness still render normally.
+    useEffect(() => {
+        if (!editor || editor.isDestroyed) return;
+        editor.setEditable(!isReadOnly);
+    }, [editor, isReadOnly]);
+
     // Ready state
     useEffect(() => {
         if (editor && isYjsReady) {
@@ -514,6 +528,15 @@ const DocumentEditorPanel = ({
     const focusType =
         focusedTypeOverride ?? (config.type === "screenplay" ? "screenplay" : "title");
 
+    const pageSize = SCREENPLAY_FORMATS[pageFormat as keyof typeof SCREENPLAY_FORMATS];
+    const wrapperStyle = pageSize
+        ? ({
+              "--page-width": `${pageSize.pageWidth}px`,
+              "--page-height": `${pageSize.pageHeight}px`,
+          } as React.CSSProperties)
+        : undefined;
+
+    const t = useTranslations("navbar");
     const isLocalAccess = isTauri() || isLocalOnly;
     if (!isLocalAccess && (!membership || isLoading)) return <Loading />;
 
@@ -524,13 +547,30 @@ const DocumentEditorPanel = ({
                 onScroll={onScroll}
                 onMouseDown={handleContainerMouseDown}
                 onFocus={() => setFocusedEditorType(focusType)}
+                onPasteCapture={
+                    isReadOnly
+                        ? (e) => {
+                              e.preventDefault();
+                              e.stopPropagation();
+                          }
+                        : undefined
+                }
             >
                 <div
                     className={`${styles.editor_wrapper} ${isEndlessScroll ? styles.endless_scroll : ""}`}
+                    style={wrapperStyle}
                 >
                     <div
                         className={join(styles.editor_shadow, isScrolled ? styles.show_shadow : "")}
                     />
+                    {isReadOnly && (
+                        <div className={styles.viewOnlyBannerWrapper}>
+                            <div className={styles.viewOnlyBanner} title={t("viewOnlyHint")}>
+                                <Eye size={14} />
+                                <span>{t("viewOnly")}</span>
+                            </div>
+                        </div>
+                    )}
                     <div onContextMenu={onEditorContextMenu}>
                         <EditorContent editor={editor} spellCheck={false} />
                     </div>
diff --git a/components/editor/EditorPanel.module.css b/components/editor/EditorPanel.module.css
index eeade120..9d5221f8 100644
--- a/components/editor/EditorPanel.module.css
+++ b/components/editor/EditorPanel.module.css
@@ -24,6 +24,22 @@
     contain: layout;
 }
 
+/* Default page-shaped sizing for the ProseMirror element so it is correctly
+ * dimensioned from its very first paint. The pagination extension's onCreate
+ * fires asynchronously (Tiptap emits 'create' via setTimeout(0)), which would
+ * otherwise leave a gap where .ProseMirror exists without the .pagination
+ * class — stretching to the full wrapper width before snapping back to the
+ * page width. The wrapper sets --page-width / --page-height inline based on
+ * pageFormat, and the !important rule from the pagination extension's
+ * stylesheet still wins once the class is added (with the same value, so no
+ * visible change). */
+.editor_wrapper :global(.ProseMirror) {
+    width: var(--page-width);
+    min-height: var(--page-height);
+    margin: 0 auto;
+    box-sizing: border-box;
+}
+
 .editor_shadow {
     position: sticky;
     top: 0;
@@ -40,7 +56,48 @@
     transition: opacity 0.7s ease;
     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%
+    );
+}
+
+/* Zero-height sticky container so the banner overlays the editor without
+ * shifting any content — overflow: visible lets the banner render beyond it. */
+.viewOnlyBannerWrapper {
+    position: sticky;
+    top: 0;
+    z-index: 51;
+    height: 0;
+    overflow: visible;
+    pointer-events: none;
+    width: 100%;
+}
+
+/* Read-only banner shown to VIEWER role at the top of the editor scroll area. */
+.viewOnlyBanner {
+    pointer-events: auto;
+    width: fit-content;
+    margin: 0 auto;
+
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    gap: 6px;
+    padding: 4px 14px;
+    border-radius: 0 0 12px 12px;
+
+    background-color: var(--main-bg);
+    border-top: none;
+    color: var(--secondary-text);
+    font-size: 0.75rem;
+    font-weight: 500;
+    user-select: none;
+    cursor: default;
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
 }
 
 .show_shadow {
diff --git a/components/editor/sidebar/ContextMenu.tsx b/components/editor/sidebar/ContextMenu.tsx
index 86b8a744..36a21ac2 100644
--- a/components/editor/sidebar/ContextMenu.tsx
+++ b/components/editor/sidebar/ContextMenu.tsx
@@ -107,7 +107,7 @@ export type SceneContextProps = {
 const SceneItemMenu = ({ props }: SubMenuProps<SceneContextProps>) => {
     const t = useTranslations("contextMenu");
     const userCtx = useContext(UserContext);
-    const { editor } = useContext(ProjectContext);
+    const { editor, isReadOnly } = useContext(ProjectContext);
     const scene: Scene = props.scene;
 
     return (
@@ -121,12 +121,16 @@ const SceneItemMenu = ({ props }: SubMenuProps<SceneContextProps>) => {
                 text={t("selectInEditor")}
                 action={() => selectTextInEditor(editor!, scene.position, scene.nextPosition)}
             />
-            <div className={context.menu_separator} />
-            <ContextMenuItem text={t("edit")} icon={Pencil} action={() => editScenePopup(scene, userCtx)} />
-            <ContextMenuItem
-                text={t("cut")}
-                action={() => cutText(editor!, scene.position, scene.nextPosition)}
-            />
+            {!isReadOnly && (
+                <>
+                    <div className={context.menu_separator} />
+                    <ContextMenuItem text={t("edit")} icon={Pencil} action={() => editScenePopup(scene, userCtx)} />
+                    <ContextMenuItem
+                        text={t("cut")}
+                        action={() => cutText(editor!, scene.position, scene.nextPosition)}
+                    />
+                </>
+            )}
         </>
     );
 };
@@ -148,18 +152,22 @@ const CharacterItemMenu = ({ props }: SubMenuProps<CharacterContextProps>) => {
     const t = useTranslations("contextMenu");
     const userCtx = useContext(UserContext);
     const projectCtx = useContext(ProjectContext);
-    const { toggleCharacterHighlight } = projectCtx;
+    const { toggleCharacterHighlight, isReadOnly } = projectCtx;
     const character: CharacterData = props.character;
 
     return (
         <>
-            <ContextMenuItem text={t("edit")} icon={Pencil} action={() => editCharacterPopup(character, userCtx)} />
-            <ContextMenuItem text={t("remove")} action={() => deleteCharacter(character.name, projectCtx)} />
-            <ContextMenuItem
-                text={t("paste")}
-                action={() => pasteText(projectCtx.editor!, character.name)}
-            />
-            <div className={context.menu_separator} />
+            {!isReadOnly && (
+                <>
+                    <ContextMenuItem text={t("edit")} icon={Pencil} action={() => editCharacterPopup(character, userCtx)} />
+                    <ContextMenuItem text={t("remove")} action={() => deleteCharacter(character.name, projectCtx)} />
+                    <ContextMenuItem
+                        text={t("paste")}
+                        action={() => pasteText(projectCtx.editor!, character.name)}
+                    />
+                    <div className={context.menu_separator} />
+                </>
+            )}
             <ContextMenuItem
                 text={t("highlight")}
                 icon={Highlighter}
@@ -186,8 +194,11 @@ export type LocationContextProps = {
 const LocationItemMenu = ({ props }: SubMenuProps<LocationContextProps>) => {
     const t = useTranslations("contextMenu");
     const projectCtx = useContext(ProjectContext);
+    const { isReadOnly } = projectCtx;
     const location: LocationData = props.location;
 
+    if (isReadOnly) return null;
+
     return (
         <>
             <ContextMenuItem icon={Trash2} text={t("remove")} action={() => deleteLocation(location.name, projectCtx)} />
@@ -212,7 +223,7 @@ export type EditorSelectionContextProps = {
 const EditorSelectionMenu = ({ props }: SubMenuProps<EditorSelectionContextProps>) => {
     const t = useTranslations("contextMenu");
     const projectCtx = useContext(ProjectContext);
-    const { editor } = projectCtx;
+    const { editor, isReadOnly } = projectCtx;
     const { updateContextMenu } = useContext(UserContext);
     const { from, to, onAddComment } = props;
     const hasSelection = from !== to;
@@ -225,7 +236,7 @@ const EditorSelectionMenu = ({ props }: SubMenuProps<EditorSelectionContextProps
     };
 
     const handleCut = async () => {
-        if (!editor) return;
+        if (!editor || isReadOnly) return;
         const text = editor.state.doc.textBetween(from, to, "\n");
         await navigator.clipboard.writeText(text);
         editor.commands.deleteRange({ from, to });
@@ -233,7 +244,7 @@ const EditorSelectionMenu = ({ props }: SubMenuProps<EditorSelectionContextProps
     };
 
     const handlePaste = async () => {
-        if (!editor) return;
+        if (!editor || isReadOnly) return;
         editor.commands.insertContent(await readClipboardText());
         updateContextMenu(undefined);
     };
@@ -246,12 +257,16 @@ const EditorSelectionMenu = ({ props }: SubMenuProps<EditorSelectionContextProps
     return (
         <>
             {hasSelection && <ContextMenuItem text={t("copy")} icon={Copy} action={handleCopy} />}
-            {hasSelection && <ContextMenuItem text={t("cut")} action={handleCut} />}
-            <ContextMenuItem text={t("paste")} icon={hasSelection ? undefined : ClipboardPaste} action={handlePaste} />
+            {hasSelection && !isReadOnly && <ContextMenuItem text={t("cut")} action={handleCut} />}
+            {!isReadOnly && (
+                <ContextMenuItem text={t("paste")} icon={hasSelection ? undefined : ClipboardPaste} action={handlePaste} />
+            )}
             {hasSelection && (
                 <>
                     <div className={context.menu_separator} />
-                    <ContextMenuItem text={t("addComment")} icon={MessageSquarePlus} action={onAddComment} />
+                    {!isReadOnly && (
+                        <ContextMenuItem text={t("addComment")} icon={MessageSquarePlus} action={onAddComment} />
+                    )}
                     <ContextMenuItem text={t("searchOnWeb")} action={handleSearchOnWeb} />
                 </>
             )}
@@ -345,10 +360,12 @@ const SpellcheckMenu = ({ props }: SubMenuProps<SpellcheckContextProps>) => {
 
 const DualDialogueMenu = ({ props }: SubMenuProps<{ pos: number }>) => {
     const t = useTranslations("contextMenu");
-    const { editor } = useContext(ProjectContext);
+    const { editor, isReadOnly } = useContext(ProjectContext);
     const { updateContextMenu } = useContext(UserContext);
     const { pos } = props;
 
+    if (isReadOnly) return null;
+
     return (
         <ContextMenuItem
             text={t("makeDualDialogue")}
@@ -367,12 +384,12 @@ const DualDialogueMenu = ({ props }: SubMenuProps<{ pos: number }>) => {
 
 const ShelveNodeMenu = ({ props }: SubMenuProps<{ pos: number; nodeClass: string }>) => {
     const t = useTranslations("contextMenu");
-    const { editor, repository } = useContext(ProjectContext);
+    const { editor, repository, isReadOnly } = useContext(ProjectContext);
     const { updateContextMenu } = useContext(UserContext);
     const { pos, nodeClass } = props;
 
     const handleShelve = () => {
-        if (!editor || !repository) return;
+        if (!editor || !repository || isReadOnly) return;
         const candidate = extractShelveCandidate(editor, pos);
         if (candidate) {
             repository.shelveNode(candidate.nodeId, candidate.title, candidate.type, candidate.content);
@@ -406,6 +423,8 @@ const ShelveNodeMenu = ({ props }: SubMenuProps<{ pos: number; nodeClass: string
               ? t("shelveDialogue")
               : t("shelveAction");
 
+    if (isReadOnly) return null;
+
     return (
         <>
             <ContextMenuItem text={shelveLabel} icon={Archive} action={handleShelve} />
@@ -437,7 +456,7 @@ export type EditorContextMenuProps = {
 
 const EditorContextMenu = ({ props }: SubMenuProps<EditorContextMenuProps>) => {
     const t = useTranslations("contextMenu");
-    const { editor, repository } = useContext(ProjectContext);
+    const { editor, repository, isReadOnly } = useContext(ProjectContext);
     const { worker } = useSpellcheck();
     const { updateContextMenu } = useContext(UserContext);
     const { from, to, onAddComment, spellError, nodePos, nodeClass } = props;
@@ -466,20 +485,20 @@ const EditorContextMenu = ({ props }: SubMenuProps<EditorContextMenuProps>) => {
     };
 
     const handleCut = async () => {
-        if (!editor) return;
+        if (!editor || isReadOnly) return;
         await navigator.clipboard.writeText(editor.state.doc.textBetween(from, to, "\n"));
         editor.commands.deleteRange({ from, to });
         updateContextMenu(undefined);
     };
 
     const handlePaste = async () => {
-        if (!editor) return;
+        if (!editor || isReadOnly) return;
         editor.commands.insertContent(await readClipboardText());
         updateContextMenu(undefined);
     };
 
     const handleSpellReplace = (suggestion: string) => {
-        if (!editor || !spellError) return;
+        if (!editor || !spellError || isReadOnly) return;
         const tr = editor.state.tr.replaceWith(spellError.from, spellError.to, editor.state.schema.text(suggestion));
         editor.view.dispatch(tr);
         updateContextMenu(undefined);
@@ -503,7 +522,7 @@ const EditorContextMenu = ({ props }: SubMenuProps<EditorContextMenuProps>) => {
     };
 
     const handleShelve = () => {
-        if (!editor || !repository || nodePos === undefined) return;
+        if (!editor || !repository || nodePos === undefined || isReadOnly) return;
         const candidate = extractShelveCandidate(editor, nodePos);
         if (candidate) {
             repository.shelveNode(candidate.nodeId, candidate.title, candidate.type, candidate.content);
@@ -554,27 +573,33 @@ const EditorContextMenu = ({ props }: SubMenuProps<EditorContextMenuProps>) => {
                             <p className="unselectable">{s}</p>
                         </div>
                     ))}
-                    <ContextMenuItem text={t("addToDictionary")} icon={BookPlus} action={handleAddToDictionary} />
+                    {!isReadOnly && (
+                        <ContextMenuItem text={t("addToDictionary")} icon={BookPlus} action={handleAddToDictionary} />
+                    )}
                     <div className={context.menu_separator} />
                 </>
             )}
 
-            {/* Clipboard — always visible */}
-            <ContextMenuItem text={t("cut")} icon={Scissors} action={handleCut} disabled={!hasSelection} />
+            {/* Clipboard — copy is always visible; cut/paste hidden for viewers */}
+            {!isReadOnly && (
+                <ContextMenuItem text={t("cut")} icon={Scissors} action={handleCut} disabled={!hasSelection} />
+            )}
             <ContextMenuItem text={t("copy")} action={handleCopy} disabled={!hasSelection} />
-            <ContextMenuItem text={t("paste")} action={handlePaste} />
+            {!isReadOnly && <ContextMenuItem text={t("paste")} action={handlePaste} />}
 
             {/* Selection actions — only when there's a selection and no spellcheck error */}
             {hasSelection && !spellError && (
                 <>
                     <div className={context.menu_separator} />
-                    <ContextMenuItem text={t("addComment")} icon={MessageSquarePlus} action={onAddComment} />
+                    {!isReadOnly && (
+                        <ContextMenuItem text={t("addComment")} icon={MessageSquarePlus} action={onAddComment} />
+                    )}
                     <ContextMenuItem text={t("searchOnWeb")} action={handleSearchOnWeb} />
                 </>
             )}
 
             {/* Node actions — shelve and optional dual dialogue */}
-            {isShelvable && (
+            {isShelvable && !isReadOnly && (
                 <>
                     <div className={context.menu_separator} />
                     <ContextMenuItem
diff --git a/components/navbar/ScreenplayFormatDropdown.tsx b/components/navbar/ScreenplayFormatDropdown.tsx
index ddd6f2b5..8342544b 100644
--- a/components/navbar/ScreenplayFormatDropdown.tsx
+++ b/components/navbar/ScreenplayFormatDropdown.tsx
@@ -63,6 +63,7 @@ const ScreenplayFormatDropdown = () => {
         setSelectedTitlePageElement,
         focusedEditorType,
         draftEditor,
+        isReadOnly,
     } = useContext(ProjectContext);
 
     const [isOpen, setIsOpen] = useState(false);
@@ -89,6 +90,7 @@ const ScreenplayFormatDropdown = () => {
 
     const handleElementSelect = useCallback(
         (element: ScreenplayElement | TitlePageElement) => {
+            if (isReadOnly) return;
             if (isTitleContext) {
                 setSelectedTitlePageElement(element as TitlePageElement);
                 if (titlePageEditor) applyTitlePageElement(titlePageEditor, element as TitlePageElement);
@@ -103,6 +105,7 @@ const ScreenplayFormatDropdown = () => {
 
     const toggleStyle = useCallback(
         (style: Style) => {
+            if (isReadOnly) return;
             setSelectedStyles((prev) => (prev ^ style) as Style);
             if (isTitleContext && titlePageEditor) {
                 applyTitlePageMarkToggle(titlePageEditor, style);
@@ -137,6 +140,7 @@ const ScreenplayFormatDropdown = () => {
 
     const setAlignment = useCallback(
         (align: string) => {
+            if (isReadOnly) return;
             setSelectedAlign(align);
             if (isTitleContext) {
                 if (!titlePageEditor) return;
@@ -208,7 +212,7 @@ const ScreenplayFormatDropdown = () => {
 
             {/* Element dropdown */}
             <div className={styles.dropdown_wrapper}>
-                <button className={styles.dropdown_trigger} onClick={() => setIsOpen(!isOpen)}>
+                <button className={styles.dropdown_trigger} onClick={() => !isReadOnly && setIsOpen(!isOpen)}>
                     <span className={styles.selected_label}>
                         {activeLabels[activeSelected as keyof typeof activeLabels]}
                     </span>
diff --git a/components/projects/ProjectItem.module.css b/components/projects/ProjectItem.module.css
index 8eec44fd..b3da288a 100644
--- a/components/projects/ProjectItem.module.css
+++ b/components/projects/ProjectItem.module.css
@@ -12,21 +12,15 @@
     align-items: center;
     gap: 16px;
 
-    border-radius: 18px;
-    border: none;
+    border-radius: 24px;
+    border: 2px solid var(--separator);
     background-color: var(--project-item-bg);
-    box-shadow: var(--panel-shadow);
 
-    transition: background-color 0.15s ease, transform 0.15s ease;
-}
-
-.container:hover {
-    background-color: var(--secondary-hover);
-    transform: translateY(-1px);
+    transition: transform 0.15s ease;
 }
 
 .container:active {
-    transform: scale(0.99);
+    transform: scale(0.98);
     transition: transform 0.07s;
 }
 
@@ -53,8 +47,7 @@
     font-family: var(--font-inter), sans-serif;
     font-style: italic;
     font-weight: 400;
-    font-size: 1.3rem;
-    text-align: left;
+    font-size: 1.4rem;
 
     white-space: nowrap;
     overflow: hidden;
diff --git a/components/projects/ProjectPageContainer.module.css b/components/projects/ProjectPageContainer.module.css
index 55239e01..fa2265f3 100644
--- a/components/projects/ProjectPageContainer.module.css
+++ b/components/projects/ProjectPageContainer.module.css
@@ -39,7 +39,7 @@
 }
 
 .create_btn {
-    font-weight: 500;
+    font-weight: 600;
     padding-inline: 40px !important;
     border-width: 3px;
 }
@@ -50,7 +50,7 @@
     align-items: center;
     white-space: nowrap;
 
-    font-weight: 500;
+    font-weight: 600;
     padding-inline: 40px !important;
     border-width: 3px;
     background: none !important;
diff --git a/messages/de.json b/messages/de.json
index d1e89246..2af8fbfd 100644
--- a/messages/de.json
+++ b/messages/de.json
@@ -14,7 +14,9 @@
     "focusMode": "Fokus-Modus",
     "splitPanel": "Panel teilen",
     "unsplitPanel": "Panel schließen",
-    "draftEditor": "Entwurfseditor"
+    "draftEditor": "Entwurfseditor",
+    "viewOnly": "Nur ansehen",
+    "viewOnlyHint": "Sie haben Lesezugriff. Die Bearbeitung ist deaktiviert."
   },
   "common": {
     "save": "Änderungen speichern",
diff --git a/messages/en.json b/messages/en.json
index ef72b2b6..f6b085c3 100644
--- a/messages/en.json
+++ b/messages/en.json
@@ -13,7 +13,9 @@
     "focusMode": "Focus Mode",
     "splitPanel": "Split Panel",
     "unsplitPanel": "Unsplit Panel",
-    "draftEditor": "Draft Editor"
+    "draftEditor": "Draft Editor",
+    "viewOnly": "View only",
+    "viewOnlyHint": "You have viewer access. Editing is disabled."
   },
   "common": {
     "save": "Save",
diff --git a/messages/es.json b/messages/es.json
index c1bf0dbe..d4bb3972 100644
--- a/messages/es.json
+++ b/messages/es.json
@@ -13,7 +13,9 @@
         "focusMode": "Modo concentración",
         "splitPanel": "Dividir panel",
         "unsplitPanel": "Unir panel",
-        "draftEditor": "Editor de borrador"
+        "draftEditor": "Editor de borrador",
+        "viewOnly": "Solo lectura",
+        "viewOnlyHint": "Tienes acceso de solo visualización. La edición está desactivada."
     },
     "common": {
         "save": "Guardar cambios",
diff --git a/messages/fr.json b/messages/fr.json
index c34f72f0..84060b90 100644
--- a/messages/fr.json
+++ b/messages/fr.json
@@ -14,7 +14,9 @@
     "focusMode": "Mode concentration",
     "splitPanel": "Diviser le panneau",
     "unsplitPanel": "Fermer le panneau divisé",
-    "draftEditor": "Éditeur de brouillon"
+    "draftEditor": "Éditeur de brouillon",
+    "viewOnly": "Vue seule",
+    "viewOnlyHint": "Vous avez un accès visiteur. La modification est désactivée."
   },
   "common": {
     "save": "Enregistrer",
diff --git a/messages/ja.json b/messages/ja.json
index 53d015ec..c41ec2f3 100644
--- a/messages/ja.json
+++ b/messages/ja.json
@@ -13,7 +13,9 @@
     "focusMode": "集中モード",
     "splitPanel": "パネルを分割",
     "unsplitPanel": "パネルを閉じる",
-    "draftEditor": "下書きエディター"
+    "draftEditor": "下書きエディター",
+    "viewOnly": "閲覧のみ",
+    "viewOnlyHint": "閲覧者アクセスです。編集は無効になっています。"
   },
   "common": {
     "save": "変更を保存",
diff --git a/messages/ko.json b/messages/ko.json
index e9b982cd..c34bd0ce 100644
--- a/messages/ko.json
+++ b/messages/ko.json
@@ -13,7 +13,9 @@
     "focusMode": "집중 모드",
     "splitPanel": "패널 분할",
     "unsplitPanel": "패널 통합",
-    "draftEditor": "초안 편집기"
+    "draftEditor": "초안 편집기",
+    "viewOnly": "보기 전용",
+    "viewOnlyHint": "뷰어 권한이 있습니다. 편집이 비활성화되었습니다."
   },
   "common": {
     "save": "변경사항 저장",
diff --git a/messages/pl.json b/messages/pl.json
index 40a57f94..f9b9cc3d 100644
--- a/messages/pl.json
+++ b/messages/pl.json
@@ -13,7 +13,9 @@
     "focusMode": "Tryb skupienia",
     "splitPanel": "Podziel panel",
     "unsplitPanel": "Zamknij panel",
-    "draftEditor": "Edytor szkiców"
+    "draftEditor": "Edytor szkiców",
+    "viewOnly": "Tylko podgląd",
+    "viewOnlyHint": "Masz dostęp gościa. Edytowanie jest wyłączone."
   },
   "common": {
     "save": "Zapisz zmiany",
diff --git a/messages/zh.json b/messages/zh.json
index d988de9b..d130c2cd 100644
--- a/messages/zh.json
+++ b/messages/zh.json
@@ -13,7 +13,9 @@
     "focusMode": "聚焦模式",
     "splitPanel": "分割面板",
     "unsplitPanel": "合并面板",
-    "draftEditor": "草稿编辑器"
+    "draftEditor": "草稿编辑器",
+    "viewOnly": "仅查看",
+    "viewOnlyHint": "您拥有访客权限，编辑功能已禁用。"
   },
   "common": {
     "save": "保存",
diff --git a/src/app/api/auth/magic-link/verify/route.ts b/src/app/api/auth/magic-link/verify/route.ts
index 10e11a30..92a67c98 100644
--- a/src/app/api/auth/magic-link/verify/route.ts
+++ b/src/app/api/auth/magic-link/verify/route.ts
@@ -8,6 +8,7 @@ import * as UserService from "@src/server/service/user-service";
 import * as ProjectService from "@src/server/service/project-service";
 import * as MagicLinkService from "@src/server/service/magic-link-service";
 import * as Misc from "@src/lib/utils/misc";
+import * as CollabUtils from "@src/lib/cloud/utils";
 import { putBridgeToken } from "@src/lib/desktop-bridge";
 import {
     encodeDesktopBearer,
@@ -65,6 +66,14 @@ async function verifyMagicLinkRoute(req: NextRequest) {
             ) {
                 await ProjectService.upsertMember(invite.projectId, user.id);
                 await ProjectService.deleteInviteFromToken(record.inviteToken);
+                // Clear any leftover DO blacklist entry from a prior kick so
+                // the freshly re-invited user can actually open a WS to the
+                // project room (otherwise the upgrade returns 403 forever).
+                try {
+                    await CollabUtils.allowOnWebsocket(user.id, invite.projectId);
+                } catch (err) {
+                    console.error("[magic-link] Failed to clear blacklist:", err);
+                }
             }
         } catch (err) {
             console.error("[magic-link] Invite acceptance failed:", err);
diff --git a/src/app/api/projects/[projectId]/members/[userId]/route.ts b/src/app/api/projects/[projectId]/members/[userId]/route.ts
index 3ad9c65d..e186658f 100644
--- a/src/app/api/projects/[projectId]/members/[userId]/route.ts
+++ b/src/app/api/projects/[projectId]/members/[userId]/route.ts
@@ -80,6 +80,10 @@ async function updateProjectMemberRole(req: NextRequest, { routeParams, user }:
     }
 
     const updated = await ProjectService.upsertMember(projectId, userToUpdateId, newRole);
+    // Push the new role to any active WS so the server-side write gate and the
+    // client UI flip to the new permissions immediately. Without this the
+    // downgraded user keeps editing until they refresh — a security hole.
+    await CollabUtils.notifyRoleChange(userToUpdateId, projectId, newRole);
     return Success(updated);
 }
 
@@ -99,7 +103,12 @@ async function deleteProjectMember(req: NextRequest, { routeParams, user }: Auth
     if (isSelf) {
         if (member.role !== ProjectRole.OWNER) {
             await ProjectService.deleteProjectMember(projectId, userToDelete);
-            return Success({ redirectUrl: "/projects" });
+            // Blacklist the leaver too so any open WS gets a 4003 close,
+            // which surfaces ProjectUnavailableDialog on the leaver's tab
+            // (consistent with the kick flow). Without this the user would
+            // stay connected with stale credentials until the JWT expires.
+            await CollabUtils.blacklistFromWebsocket(userToDelete, projectId);
+            return SuccessNoContent();
         } else {
             throw new ForbiddenError("Owner cannot leave project");
         }
diff --git a/src/app/api/projects/accept-invite/route.ts b/src/app/api/projects/accept-invite/route.ts
index 055be2a0..b9a210b5 100644
--- a/src/app/api/projects/accept-invite/route.ts
+++ b/src/app/api/projects/accept-invite/route.ts
@@ -4,6 +4,7 @@ import { InternalServerError, NotFoundError, validate } from "@src/lib/utils/api
 import * as ProjectService from "@src/server/service/project-service";
 import * as UserService from "@src/server/service/user-service";
 import * as Misc from "@src/lib/utils/misc";
+import * as CollabUtils from "@src/lib/cloud/utils";
 
 import z from "zod";
 import { NextRequest } from "next/server";
@@ -38,6 +39,16 @@ async function acceptProjectInvite(req: NextRequest, { searchParams }: ApiContex
         await ProjectService.upsertMember(invite.projectId, user.id);
         await ProjectService.deleteInviteFromToken(token);
 
+        // The DO keeps a blacklist of kicked userIds (persisted in SQLite).
+        // If this user was previously kicked from this project, the entry is
+        // still there and would reject their next WS upgrade with 403. Clear
+        // it now so the re-invite actually grants access.
+        try {
+            await CollabUtils.allowOnWebsocket(user.id, invite.projectId);
+        } catch (err) {
+            console.error("[accept-invite] Failed to clear blacklist:", err);
+        }
+
         // If user is not logged in, send them to the home page with the email pre-filled
         // so they can request a magic link.
         const cookieUser = await getCookieUser();
diff --git a/src/app/projects/layout.tsx b/src/app/projects/layout.tsx
index 71531ab1..bd139936 100644
--- a/src/app/projects/layout.tsx
+++ b/src/app/projects/layout.tsx
@@ -50,50 +50,32 @@ interface ProjectLayoutInnerProps {
 }
 
 const ProjectLayoutInner = ({ children }: ProjectLayoutInnerProps) => {
-    const { isYjsReady, isProjectUnavailable, isStaleClient, migrationOutcome } = useProjectReady();
+    const { status } = useProjectReady();
     const { membership, isLoading: isMembershipLoading, isLocalOnly: isBrowserLocalOnly } = useProjectMembership();
 
-    // Desktop (Tauri) and browser local-only projects skip the cloud membership requirement
-    const isDesktop = isTauri();
-    const isLocalAccess = isDesktop || isBrowserLocalOnly;
+    // Desktop (Tauri) and browser local-only projects skip the cloud membership requirement.
+    const isLocalAccess = isTauri() || isBrowserLocalOnly;
 
-    // Server rejected this client as stale — its bundle predates the doc's
-    // schema version. Treat as a future-version outcome so the user gets a
-    // clear "update required" message.
-    if (isStaleClient) {
-        return <ProjectMigrationErrorDialog outcome={{ kind: "stale-client" }} />;
+    // Surface terminal error states first so the user always gets a clear message,
+    // before any redirect or loading gating runs.
+    if (status.kind === "needs-update") {
+        return <ProjectMigrationErrorDialog outcome={status.outcome} />;
     }
-
-    // Migration blocked the project from loading: show a dedicated error dialog
-    // before any other gating logic, so the user always gets a clear message.
-    if (
-        migrationOutcome &&
-        (migrationOutcome.kind === "future-version" || migrationOutcome.kind === "failed")
-    ) {
-        return <ProjectMigrationErrorDialog outcome={migrationOutcome} />;
-    }
-
-    // Wait for membership to resolve for potential cloud projects
-    if (!isLocalAccess && isMembershipLoading) {
-        return <Loading />;
+    // The cloud copy is gone (project deleted, or the user was removed). Checked
+    // before the redirect so a kicked user with a stale (undefined) membership
+    // lands on the dialog instead of being bounced to /projects mid-loop.
+    if (status.kind === "unavailable") {
+        return <ProjectUnavailableDialog />;
     }
-
-    // Always wait for local data to be ready
-    if (!isYjsReady) {
+    // Wait for local data and (for cloud projects) for membership to resolve.
+    if (status.kind === "loading" || (!isLocalAccess && isMembershipLoading)) {
         return <Loading />;
     }
-
-    // On web, redirect if no cloud membership and not a local project
+    // On web, redirect if no cloud membership and not a local project.
     if (!isLocalAccess && !membership) {
         redirect("/projects");
     }
 
-    // The cloud copy is gone (project deleted, or the user was removed). Offer the
-    // user a choice between keeping a local copy or discarding it — same on web and desktop.
-    if (isProjectUnavailable) {
-        return <ProjectUnavailableDialog />;
-    }
-
     return (
         <ViewProvider>
             <div style={{ display: "flex", flexDirection: "column", height: "100vh", overflow: "hidden" }}>
diff --git a/src/context/ProjectContext.tsx b/src/context/ProjectContext.tsx
index d9881b44..74e4c638 100644
--- a/src/context/ProjectContext.tsx
+++ b/src/context/ProjectContext.tsx
@@ -14,6 +14,7 @@ import { CharacterMap, mergeCharactersData } from "@src/lib/screenplay/character
 import { LocationMap, mergeLocationsData } from "@src/lib/screenplay/locations";
 import { mergeScenesData, PersistentSceneMap, Scene } from "@src/lib/screenplay/scenes";
 import { ProjectMembershipPayload } from "@src/server/repository/project-repository";
+import { ProjectRole } from "@src/generated/client/browser";
 import { useUser } from "@src/lib/utils/hooks";
 import {
     CollaboratorInfo,
@@ -24,8 +25,8 @@ import {
     PageMargin,
     DEFAULT_PAGE_MARGINS,
     ShelfEntry,
+    ProjectStatus,
 } from "@src/lib/project/project-state";
-import type { ProjectMigrationOutcome } from "@src/lib/project/migrations/project-migration-runner";
 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";
@@ -48,6 +49,11 @@ export interface ProjectContextType {
     provider: ThrottledWebsocketProvider | null;
     isYjsReady: boolean;
 
+    /** True when the current user has VIEWER role on a cloud project.
+     *  All edit affordances must be hidden/disabled when this is true,
+     *  and the repository's writes are no-ops as a safety net. */
+    isReadOnly: boolean;
+
     // Connection state
     connectionStatus: ConnectionStatus;
     users: CollaboratorInfo[];
@@ -137,6 +143,7 @@ const defaultContextValue: ProjectContextType = {
     repository: null,
     provider: null,
     isYjsReady: false,
+    isReadOnly: false,
 
     connectionStatus: "disconnected",
     users: [],
@@ -215,17 +222,11 @@ export const ProjectContext = createContext<ProjectContextType>(defaultContextVa
 // Stable context for rarely-changing infrastructure values.
 // Prevents ProjectLayoutInner from re-rendering on every screenplay change.
 interface ProjectReadyContextType {
-    isYjsReady: boolean;
-    isProjectUnavailable: boolean;
-    isStaleClient: boolean;
-    migrationOutcome: ProjectMigrationOutcome | null;
+    status: ProjectStatus;
 }
 
 const ProjectReadyContext = createContext<ProjectReadyContextType>({
-    isYjsReady: false,
-    isProjectUnavailable: false,
-    isStaleClient: false,
-    migrationOutcome: null,
+    status: { kind: "loading" },
 });
 
 export const useProjectReady = () => useContext(ProjectReadyContext);
@@ -251,12 +252,9 @@ export const ProjectProvider = ({ children, projectId }: ProjectProviderProps) =
     const {
         ydoc,
         provider,
-        isReady: isYjsReady,
+        status,
         connectionStatus: yjsConnectionStatus,
         users: yjsUsers,
-        isProjectUnavailable,
-        isStaleClient,
-        migrationOutcome,
     } = useProjectYjs({
         projectId,
         userName,
@@ -264,10 +262,15 @@ export const ProjectProvider = ({ children, projectId }: ProjectProviderProps) =
         userId: user?.id,
     });
 
+    // Derived for downstream consumers (editor, board, etc.) that only care
+    // whether the project is renderable, not which error state we're in.
+    const isYjsReady = status.kind === "ready";
+
     // Repository state - loaded dynamically
     const [repository, setRepository] = useState<ProjectRepository | null>(null);
 
     const [project, setProject] = useState<ProjectMembershipPayload | null>(null);
+    const isReadOnly = !!project && project.role === ProjectRole.VIEWER;
     const [editor, setEditor] = useState<Editor | null>(null);
     const [screenplay, setScreenplay] = useState<Screenplay>([]);
     const [characters, setCharacters] = useState<CharacterMap | undefined>(undefined);
@@ -357,6 +360,25 @@ export const ProjectProvider = ({ children, projectId }: ProjectProviderProps) =
         };
     }, [ydoc]);
 
+    useEffect(() => {
+        repository?.setReadOnly(isReadOnly);
+    }, [repository, isReadOnly]);
+
+    // 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
+    // revalidation of the membership endpoint.
+    useEffect(() => {
+        if (!provider) return;
+        const handler = (newRole: string) => {
+            setProject((prev) => (prev ? { ...prev, role: newRole as ProjectRole } : prev));
+        };
+        provider.on("role-changed", handler);
+        return () => {
+            provider.off("role-changed", handler);
+        };
+    }, [provider]);
+
     const updateScreenplay = useCallback((newScreenplay: Screenplay) => {
         setScreenplay(newScreenplay);
     }, []);
@@ -725,6 +747,7 @@ export const ProjectProvider = ({ children, projectId }: ProjectProviderProps) =
             repository,
             provider,
             isYjsReady,
+            isReadOnly,
             connectionStatus,
             users,
             editor,
@@ -788,6 +811,7 @@ export const ProjectProvider = ({ children, projectId }: ProjectProviderProps) =
             repository,
             provider,
             isYjsReady,
+            isReadOnly,
             connectionStatus,
             users,
             editor,
@@ -847,10 +871,7 @@ export const ProjectProvider = ({ children, projectId }: ProjectProviderProps) =
         ],
     );
 
-    const readyValue = useMemo(
-        () => ({ isYjsReady, isProjectUnavailable, isStaleClient, migrationOutcome }),
-        [isYjsReady, isProjectUnavailable, isStaleClient, migrationOutcome],
-    );
+    const readyValue = useMemo(() => ({ status }), [status]);
 
     return (
         <ProjectReadyContext.Provider value={readyValue}>
diff --git a/src/lib/cloud/index.ts b/src/lib/cloud/index.ts
index 5e4f2969..c934e69e 100644
--- a/src/lib/cloud/index.ts
+++ b/src/lib/cloud/index.ts
@@ -7,6 +7,7 @@ interface DecodedToken extends JWTPayload {
     type?: string;
     projectId?: string;
     userId?: string;
+    role?: string;
 }
 
 async function getVerifiedPayload(token: string | null, secret: string): Promise<DecodedToken | null> {
@@ -36,9 +37,12 @@ const worker = {
         // segments: [projectId, ...rest]
         const doPath = "/" + segments.slice(1).join("/");
 
-        // Authenticated API endpoints (saves, blacklist, allow)
+        // Authenticated API endpoints (saves, blacklist, allow, role-update)
         const isAuthEndpoint =
-            url.pathname.includes("/saves") || url.pathname.endsWith("/blacklist") || url.pathname.endsWith("/allow");
+            url.pathname.includes("/saves") ||
+            url.pathname.endsWith("/blacklist") ||
+            url.pathname.endsWith("/allow") ||
+            url.pathname.endsWith("/role-update");
 
         if (isAuthEndpoint && request.method !== "GET") {
             const authHeader = request.headers.get("Authorization");
@@ -99,6 +103,7 @@ const worker = {
 
             const newRequest = new Request(request);
             newRequest.headers.set("X-User-Id", userId);
+            newRequest.headers.set("X-User-Role", decoded.role || "VIEWER");
             newRequest.headers.set("X-Project-Id", projectId);
 
             const stub = env.PROJECT_ROOM.get(env.PROJECT_ROOM.idFromName(projectId));
diff --git a/src/lib/cloud/protocol.ts b/src/lib/cloud/protocol.ts
index 58576e11..261ba4b2 100644
--- a/src/lib/cloud/protocol.ts
+++ b/src/lib/cloud/protocol.ts
@@ -4,6 +4,15 @@ import * as syncProtocol from "y-protocols/sync";
 import * as awarenessProtocol from "y-protocols/awareness";
 import type { ProjectRoom } from "./room";
 
+/**
+ * Yjs sync sub-message types (mirrors y-protocols/sync constants).
+ * Step1 is a read-only request — the server replies with Step2.
+ * Step2 and Update both carry data that mutates the doc.
+ */
+const SYNC_STEP_1 = 0;
+const SYNC_STEP_2 = 1;
+const SYNC_UPDATE = 2;
+
 export function handleProtocolMessage(room: ProjectRoom, fullMessage: Uint8Array, sender: WebSocket) {
     const messageType = fullMessage[0];
     const messageContent = fullMessage.subarray(1);
@@ -12,16 +21,40 @@ export function handleProtocolMessage(room: ProjectRoom, fullMessage: Uint8Array
     try {
         switch (messageType) {
             case 0: // Sync (document updates)
+                const session = room.sessions.get(sender);
+                const isReadOnly = session?.role === "VIEWER";
+
                 const syncEncoder = encoding.createEncoder();
                 encoding.writeVarUint(syncEncoder, 0); // Message type 0 (sync)
 
-                // Handle multiple sync messages in a single packet (common in y-websocket)
+                // Handle multiple sync messages in a single packet (common in y-websocket).
+                // We dispatch sub-messages manually so we can drop writes from
+                // viewers while still answering their SyncStep1 read requests.
                 try {
                     while (decoding.hasContent(decoder)) {
-                        // Passing 'sender' (WebSocket) as origin causes the doc.on('update')
-                        // listener (set up in constructor) to broadcast the change,
-                        // schedule a hot save, and flag for cold snapshot.
-                        syncProtocol.readSyncMessage(decoder, syncEncoder, room.doc, sender);
+                        const subType = decoding.readVarUint(decoder);
+                        if (subType === SYNC_STEP_1) {
+                            // Read-only: server responds with SyncStep2 carrying the current doc state.
+                            syncProtocol.readSyncStep1(decoder, syncEncoder, room.doc);
+                        } else if (subType === SYNC_STEP_2 || subType === SYNC_UPDATE) {
+                            // Both carry an update payload that would mutate the doc.
+                            // For viewers we read the bytes off the decoder but never
+                            // apply them, so the rest of the packet stays parseable.
+                            if (isReadOnly) {
+                                decoding.readVarUint8Array(decoder);
+                                console.warn(
+                                    `[Room] Dropped doc write from viewer ${session?.userId ?? "?"}`,
+                                );
+                            } else if (subType === SYNC_STEP_2) {
+                                syncProtocol.readSyncStep2(decoder, room.doc, sender);
+                            } else {
+                                syncProtocol.readUpdate(decoder, room.doc, sender);
+                            }
+                        } else {
+                            // Unknown sub-type — bail to avoid mis-aligning the decoder.
+                            console.warn(`[Room] Unknown sync sub-message type: ${subType}`);
+                            break;
+                        }
                     }
                 } catch (e) {
                     console.error("[Room] Error reading sync message:", e);
diff --git a/src/lib/cloud/room.ts b/src/lib/cloud/room.ts
index 9af67d3b..8d359e1b 100644
--- a/src/lib/cloud/room.ts
+++ b/src/lib/cloud/room.ts
@@ -164,12 +164,16 @@ export class ProjectRoom extends DurableObject {
         const hibernatedSockets = this.ctx.getWebSockets();
         for (const ws of hibernatedSockets) {
             const attachment = ws.deserializeAttachment() as
-                | { userId: string; clientIds: number[] }
+                | { userId: string; role?: string; clientIds: number[] }
                 | null;
             if (!attachment) continue;
             this.sessions.set(ws, {
                 clientIds: new Set(attachment.clientIds),
                 userId: attachment.userId,
+                // Older attachments may not have a role; default to VIEWER
+                // (read-only) to fail safe — the client will reconnect with a
+                // fresh JWT carrying the correct role on the next message.
+                role: attachment.role || "VIEWER",
                 lastActivity: Date.now(),
             });
             this.userConnections.set(attachment.userId, ws);
@@ -189,14 +193,15 @@ export class ProjectRoom extends DurableObject {
 
     /**
      * Persist the current session state on the WebSocket so it survives
-     * Cloudflare DO hibernation. Called whenever clientIds or userId changes
-     * for a session.
+     * Cloudflare DO hibernation. Called whenever clientIds, userId, or role
+     * changes for a session.
      */
     private persistSessionAttachment(ws: WebSocket): void {
         const session = this.sessions.get(ws);
         if (!session) return;
         ws.serializeAttachment({
             userId: session.userId,
+            role: session.role,
             clientIds: Array.from(session.clientIds),
         });
     }
@@ -582,12 +587,46 @@ export class ProjectRoom extends DurableObject {
             return new Response(`User ${userId} allowed.`, { status: 200 });
         }
 
+        // Role-update endpoint — push a role change to a connected user.
+        // Updates the in-memory SessionInfo so the protocol's write gate uses
+        // the new role on the next message, and notifies the client so its
+        // local `project.role` updates without a manual refresh. We don't
+        // close the socket: the existing JWT carries the OLD role, but the
+        // server-side gate is the source of truth and is now correct.
+        if (request.method === "POST" && url.pathname === "/role-update") {
+            const { userId, role } = (await request.json()) as { userId?: string; role?: string };
+            if (!userId || !role) {
+                return new Response("Missing userId or role", { status: 400 });
+            }
+
+            const socket = this.userConnections.get(userId);
+            if (socket) {
+                const session = this.sessions.get(socket);
+                if (session) {
+                    session.role = role;
+                    this.persistSessionAttachment(socket);
+                }
+                try {
+                    const encoder = encoding.createEncoder();
+                    encoding.writeVarUint(encoder, 100); // custom message type: role-update
+                    encoding.writeVarString(encoder, role);
+                    socket.send(encoding.toUint8Array(encoder));
+                } catch (e) {
+                    console.warn(`[Room] Failed to push role-update to ${userId}:`, e);
+                }
+            }
+
+            console.log(`[Room] Role updated for user ${userId} -> ${role}`);
+            return new Response(`User ${userId} role updated.`, { status: 200 });
+        }
+
         // WebSocket upgrade
         if (request.headers.get("Upgrade") === "websocket") {
             const userId = request.headers.get("X-User-Id");
             if (!userId) {
                 return new Response("Missing User Identity", { status: 400 });
             }
+            const role = request.headers.get("X-User-Role") || "VIEWER";
 
             if (this.blacklist.has(userId)) {
                 return new Response("Unauthorized: You have been kicked.", { status: 403 });
@@ -642,6 +681,7 @@ export class ProjectRoom extends DurableObject {
             this.sessions.set(server, {
                 clientIds: new Set(),
                 userId,
+                role,
                 lastActivity: Date.now(),
             });
             this.userConnections.set(userId, server);
diff --git a/src/lib/cloud/types.ts b/src/lib/cloud/types.ts
index 33006eeb..d85d6cd9 100644
--- a/src/lib/cloud/types.ts
+++ b/src/lib/cloud/types.ts
@@ -21,6 +21,8 @@ export const RETENTION_INTERVAL_30MIN_MS = 30 * 60 * 1000;
 export interface SessionInfo {
     clientIds: Set<number>;
     userId: string;
+    /** Project role from the JWT — used to gate doc writes (VIEWER is read-only). */
+    role: string;
     lastActivity: number;
 }
 
diff --git a/src/lib/cloud/utils.ts b/src/lib/cloud/utils.ts
index d9c5adc2..2edded27 100644
--- a/src/lib/cloud/utils.ts
+++ b/src/lib/cloud/utils.ts
@@ -4,6 +4,7 @@ import * as bc from "lib0/broadcastchannel";
 import { WebsocketProvider } from "y-websocket";
 import * as Y from "yjs";
 import * as encoding from "lib0/encoding";
+import * as decoding from "lib0/decoding";
 import * as syncProtocol from "y-protocols/sync";
 import * as awarenessProtocol from "y-protocols/awareness";
 import { CURRENT_PROJECT_VERSION } from "../project/migrations/project-migrations";
@@ -41,8 +42,11 @@ export class ThrottledWebsocketProvider extends WebsocketProvider {
     on(event: "document-restored", listener: () => void): this;
     on(event: "stale-client-version", listener: () => void): this;
     on(event: "session-replaced", listener: () => void): this;
+    on(event: "kicked", listener: () => void): this;
+    on(event: "role-changed", listener: (role: string) => void): this;
     on(event: Parameters<WebsocketProvider["on"]>[0], listener: Parameters<WebsocketProvider["on"]>[1]): this;
-    on(event: string, listener: (...args: unknown[]) => void): this {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    on(event: string, listener: (...args: any[]) => void): this {
         return super.on(
             event as unknown as Parameters<WebsocketProvider["on"]>[0],
             listener as unknown as Parameters<WebsocketProvider["on"]>[1],
@@ -52,6 +56,8 @@ export class ThrottledWebsocketProvider extends WebsocketProvider {
     emit(event: "document-restored", args: []): this;
     emit(event: "stale-client-version", args: []): this;
     emit(event: "session-replaced", args: []): this;
+    emit(event: "kicked", args: []): this;
+    emit(event: "role-changed", args: [string]): this;
     emit(event: Parameters<WebsocketProvider["emit"]>[0], args: Parameters<WebsocketProvider["emit"]>[1]): this;
     emit(event: string, args: unknown[]): this {
         super.emit(
@@ -60,6 +66,20 @@ export class ThrottledWebsocketProvider extends WebsocketProvider {
         );
         return this;
     }
+
+    off(event: "document-restored", listener: () => void): this;
+    off(event: "stale-client-version", listener: () => void): this;
+    off(event: "session-replaced", listener: () => void): this;
+    off(event: "kicked", listener: () => void): this;
+    off(event: "role-changed", listener: (role: string) => void): this;
+    off(event: Parameters<WebsocketProvider["off"]>[0], listener: Parameters<WebsocketProvider["off"]>[1]): this;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    off(event: string, listener: (...args: any[]) => void): this {
+        return super.off(
+            event as unknown as Parameters<WebsocketProvider["off"]>[0],
+            listener as unknown as Parameters<WebsocketProvider["off"]>[1],
+        ) as unknown as this;
+    }
     private updateQueue: Uint8Array[] = [];
     private awarenessQueue: Set<number> = new Set();
     private flushInterval: ReturnType<typeof setInterval> | null = null;
@@ -92,6 +112,7 @@ export class ThrottledWebsocketProvider extends WebsocketProvider {
     private isIdleDisconnected: boolean = false;
     private isSessionReplaced: boolean = false;
     private isStaleClient: boolean = false;
+    private isKicked: boolean = false;
     private lastKnownUserCount: number = 1;
 
     // Store userInfo so we can restore it on reconnection
@@ -99,6 +120,7 @@ export class ThrottledWebsocketProvider extends WebsocketProvider {
 
     // Close codes from server
     private readonly CLOSE_CODE_SESSION_REPLACED = 4001;
+    private readonly CLOSE_CODE_KICKED = 4003;
     private readonly CLOSE_CODE_DOCUMENT_RESTORED = 4005;
     private readonly CLOSE_CODE_STALE_CLIENT_VERSION = 4006;
 
@@ -165,6 +187,22 @@ export class ThrottledWebsocketProvider extends WebsocketProvider {
             this.lastMessageTime = Date.now();
         };
 
+        // Custom message type 100 — server pushes the user's new role when an
+        // admin changes it. The DO has already updated its in-memory SessionInfo
+        // (so the server-side write gate is correct on the next message); this
+        // handler propagates the change to the UI so editor affordances flip
+        // immediately, without waiting for an SWR revalidation.
+        (this as unknown as WSInternals).messageHandlers[100] = (_encoder, ...rest: unknown[]) => {
+            this.lastMessageTime = Date.now();
+            const decoder = rest[0] as decoding.Decoder;
+            try {
+                const role = decoding.readVarString(decoder);
+                this.emit("role-changed", [role]);
+            } catch (e) {
+                console.warn("[WS] Failed to read role-changed message:", e);
+            }
+        };
+
         // Handle connection status changes
         this.on("status", this.onStatusChange);
 
@@ -215,8 +253,8 @@ export class ThrottledWebsocketProvider extends WebsocketProvider {
         let currentWs: WebSocket | null = null;
 
         const checkAndHookWs = () => {
-            // Don't hook if session was already replaced or rejected as stale
-            if (this.isSessionReplaced || this.isStaleClient) return;
+            // Don't hook if session was already replaced, rejected as stale, or kicked
+            if (this.isSessionReplaced || this.isStaleClient || this.isKicked) return;
 
             const ws = (this as unknown as WSInternals).ws;
             if (ws && ws !== currentWs) {
@@ -227,6 +265,10 @@ export class ThrottledWebsocketProvider extends WebsocketProvider {
                         this.handleSessionReplaced();
                         return;
                     }
+                    if (event.code === this.CLOSE_CODE_KICKED) {
+                        this.handleKicked();
+                        return;
+                    }
                     if (event.code === this.CLOSE_CODE_DOCUMENT_RESTORED) {
                         this.handleDocumentRestored();
                         return;
@@ -244,8 +286,13 @@ export class ThrottledWebsocketProvider extends WebsocketProvider {
 
         // Hook into new WebSocket connections when status changes
         this.on("status", (event: { status: string }) => {
-            // Only hook when connecting, not when already replaced or stale-rejected
-            if (event.status === "connecting" && !this.isSessionReplaced && !this.isStaleClient) {
+            // Only hook when connecting, not when already replaced, stale-rejected, or kicked
+            if (
+                event.status === "connecting" &&
+                !this.isSessionReplaced &&
+                !this.isStaleClient &&
+                !this.isKicked
+            ) {
                 setTimeout(checkAndHookWs, 0);
             }
         });
@@ -288,6 +335,29 @@ export class ThrottledWebsocketProvider extends WebsocketProvider {
         this.emit("document-restored", []);
     }
 
+    /**
+     * Handle kick close (4003) — the user was removed from the project. Stop
+     * reconnecting (the cloud token endpoint will reject us with 403 forever)
+     * and notify the consumer to surface the project-unavailable dialog.
+     */
+    private handleKicked(): void {
+        console.log("[WS] User was kicked from the project. Stopping reconnection.");
+        this.isKicked = true;
+
+        if (this.reconnectTimeout) {
+            clearTimeout(this.reconnectTimeout);
+            this.reconnectTimeout = null;
+        }
+
+        this.shouldConnect = false;
+        this.disconnect();
+        this.emit("kicked", []);
+    }
+
+    public get wasKicked(): boolean {
+        return this.isKicked;
+    }
+
     /**
      * Handle stale-client-version close — this client's bundle is older than
      * the project's schema version. Stop reconnecting (would just be rejected
@@ -660,13 +730,21 @@ export class ThrottledWebsocketProvider extends WebsocketProvider {
      * Handle document updates (throttled)
      */
     private onThrottledUpdate = (update: Uint8Array, origin: unknown): void => {
-        if (origin !== this) {
-            this.updateQueue.push(update);
-            // Cap queue length on long disconnects. The local doc still holds
-            // every change; sync on reconnect will replay them.
-            if (this.updateQueue.length > this.MAX_UPDATE_QUEUE) {
-                this.updateQueue.splice(0, this.updateQueue.length - this.MAX_UPDATE_QUEUE);
-            }
+        if (origin === this) return;
+
+        // Read-only short-circuit: when the local doc is in viewer mode, the
+        // ProjectState rollback guard reverts every local write immediately.
+        // Both the original write and the inverse op fire `update` events, but
+        // the server would drop them anyway (protocol.ts blocks viewer writes).
+        // Skip the queue entirely to save bandwidth and keep the WS quiet.
+        const ydoc = this.doc as { isReadOnly?: boolean };
+        if (ydoc.isReadOnly) return;
+
+        this.updateQueue.push(update);
+        // Cap queue length on long disconnects. The local doc still holds
+        // every change; sync on reconnect will replay them.
+        if (this.updateQueue.length > this.MAX_UPDATE_QUEUE) {
+            this.updateQueue.splice(0, this.updateQueue.length - this.MAX_UPDATE_QUEUE);
         }
     };
 
@@ -904,3 +982,21 @@ export const blacklistFromWebsocket = async (userId: string, projectId: string)
         body: JSON.stringify({ userId }),
     });
 };
+
+export const notifyRoleChange = async (userId: string, projectId: string, role: string) => {
+    const payload = {
+        type: "admin-action",
+        projectId,
+    };
+
+    const secret = new TextEncoder().encode(process.env.JWT_SECRET!);
+    const token = await new SignJWT(payload).setProtectedHeader({ alg: "HS256" }).setExpirationTime("1m").sign(secret);
+    await fetch(`${process.env.NEXT_PUBLIC_CLOUD_URL}/${projectId}/role-update`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({ userId, role }),
+    });
+};
diff --git a/src/lib/import/import-project.ts b/src/lib/import/import-project.ts
index 276e9817..97f4f177 100644
--- a/src/lib/import/import-project.ts
+++ b/src/lib/import/import-project.ts
@@ -58,6 +58,11 @@ export async function importFileIntoProject(
         throw new Error(`Unsupported file type: ${file.name.split(".").pop()}`);
     }
 
+    // Bail before reading the file when the doc is in read-only mode (viewer
+    // role). The Y.Doc rollback gate would revert every write the adapter
+    // emits — this just avoids a brief flash of imported content in the UI.
+    if (repository?.getState().isReadOnly) return;
+
     const content = await file.arrayBuffer();
     adapter.import(content, editor, titlePageEditor, repository);
     if (editor) editor.commands.focus();
diff --git a/src/lib/persistence/storage-provider/local-persistence.ts b/src/lib/persistence/storage-provider/local-persistence.ts
index 53bd90c2..1162f684 100644
--- a/src/lib/persistence/storage-provider/local-persistence.ts
+++ b/src/lib/persistence/storage-provider/local-persistence.ts
@@ -133,8 +133,9 @@ export async function migrateToCachedProject(
 /**
  * Promote a local-only cached project to a cloud project, reusing the same id.
  * Creates a cloud project record + membership, then flips the local cache flag.
- * The Y.js doc at `scriptio-{projectId}` is unchanged — `useCloudSync` will
- * push it to the empty server doc on next mount via the standard CRDT handshake.
+ * The Y.js doc at `scriptio-{projectId}` is unchanged — the cloud provider in
+ * `useProjectYjs` will push it to the empty server doc on next mount via the
+ * standard CRDT handshake.
  */
 export async function promoteLocalProjectToCloud(projectId: string): Promise<void> {
     const local = await getCachedProject(projectId);
@@ -155,18 +156,23 @@ export async function promoteLocalProjectToCloud(projectId: string): Promise<voi
 }
 
 /**
- * Discard a cloud project's local data (cached entry + Yjs IndexedDB database).
+ * Delete the Yjs IndexedDB database for a project without touching its metadata.
+ * Used when the server restores a snapshot so the next load syncs a clean state.
  */
-export async function discardCloudProjectData(projectId: string): Promise<void> {
-    // Remove the cached project entry
-    await deleteCachedProject(projectId);
-
-    // Delete the Yjs IndexedDB database for this project
+export async function clearYjsData(projectId: string): Promise<void> {
     const dbName = yjsDbKey(projectId);
-    await new Promise<void>((resolve, reject) => {
+    await new Promise<void>((resolve) => {
         const req = indexedDB.deleteDatabase(dbName);
         req.onsuccess = () => resolve();
-        req.onerror = () => reject(req.error);
+        req.onerror = () => resolve(); // best-effort
         req.onblocked = () => resolve();
     });
 }
+
+/**
+ * Discard a cloud project's local data (cached entry + Yjs IndexedDB database).
+ */
+export async function discardCloudProjectData(projectId: string): Promise<void> {
+    await deleteCachedProject(projectId);
+    await clearYjsData(projectId);
+}
diff --git a/src/lib/project/migrations/project-migration-runner.ts b/src/lib/project/migrations/project-migration-runner.ts
index fb185017..9a8ddcd1 100644
--- a/src/lib/project/migrations/project-migration-runner.ts
+++ b/src/lib/project/migrations/project-migration-runner.ts
@@ -6,9 +6,9 @@
  *     DurableObject (server-side gatekeeper) to migrate the doc on load
  *     before serving updates to clients.
  *   - `migrateProjectDoc`: client wrapper that adds an IndexedDB pre-migration
- *     backup so a failed step can be rolled back. Called from
- *     `useLocalPersistence` after `y-indexeddb` has synced and before the
- *     cloud `WebsocketProvider` connects.
+ *     backup so a failed step can be rolled back. Called from the session
+ *     cache in `project-state.ts` after `y-indexeddb` has synced and before
+ *     the cloud `WebsocketProvider` connects.
  *
  * Both rely on idempotent migration steps so concurrent migrations across
  * the DO and any number of clients converge cleanly under CRDT merge.
diff --git a/src/lib/project/project-doc.ts b/src/lib/project/project-doc.ts
index 8bf590d7..936c2c7f 100644
--- a/src/lib/project/project-doc.ts
+++ b/src/lib/project/project-doc.ts
@@ -181,6 +181,16 @@ export class ProjectState extends Y.Doc {
         SHELF: "shelf",
     } as const;
 
+    private _readOnly: boolean = false;
+
+    setReadOnly(readOnly: boolean): void {
+        this._readOnly = readOnly;
+    }
+
+    get isReadOnly(): boolean {
+        return this._readOnly;
+    }
+
     metadata(): TypedMap<ProjectMetadata> {
         return this.getMap(this.KEYS.METADATA) as unknown as TypedMap<ProjectMetadata>;
     }
@@ -233,11 +243,3 @@ export class ProjectState extends Y.Doc {
     }
 }
 
-// -------------------------------- //
-//          MAP HELPERS             //
-// -------------------------------- //
-
-export const getCharactersMap = (ydoc: ProjectState): Y.Map<CharacterItem> => ydoc.characters();
-export const getLocationsMap = (ydoc: ProjectState): Y.Map<LocationItem> => ydoc.locations();
-export const getScenesMap = (ydoc: ProjectState): Y.Map<PersistentScene> => ydoc.scenes();
-export const getBoardMap = (ydoc: ProjectState): TypedMap<BoardData> => ydoc.board();
diff --git a/src/lib/project/project-repository.ts b/src/lib/project/project-repository.ts
index b5e15d74..5402e11e 100644
--- a/src/lib/project/project-repository.ts
+++ b/src/lib/project/project-repository.ts
@@ -41,6 +41,22 @@ export class ProjectRepository {
         this.ydoc = ydoc;
     }
 
+    setReadOnly(readOnly: boolean): void {
+        this.ydoc.setReadOnly(readOnly);
+    }
+
+    get readOnly(): boolean {
+        return this.ydoc.isReadOnly;
+    }
+
+    private guardWrite(op: string): boolean {
+        if (this.ydoc.isReadOnly) {
+            console.warn(`[Repo] Blocked ${op}: project is read-only`);
+            return true;
+        }
+        return false;
+    }
+
     /**
      * Get the underlying Y.js document.
      * Use sparingly - prefer using repository methods when possible.
@@ -118,10 +134,12 @@ export class ProjectRepository {
     }
 
     setTitle(title: string): void {
+        if (this.guardWrite("setTitle")) return;
         this.ydoc.metadata().set("title", title);
     }
 
     setAuthor(author: string): void {
+        if (this.guardWrite("setAuthor")) return;
         this.ydoc.metadata().set("author", author);
     }
 
@@ -229,6 +247,7 @@ export class ProjectRepository {
      * Returns the scene id.
      */
     upsertScene(sceneId: string, data: Partial<PersistentScene>): string {
+        if (this.guardWrite("upsertScene")) return sceneId;
         const map = this.ydoc.scenes();
         const existing = map.get(sceneId) as PersistentScene | undefined;
 
@@ -266,6 +285,7 @@ export class ProjectRepository {
      * Delete a scene's persistent data.
      */
     deleteScene(sceneId: string): void {
+        if (this.guardWrite("deleteScene")) return;
         const map = this.ydoc.scenes();
         if (map.has(sceneId)) {
             map.delete(sceneId);
@@ -305,30 +325,39 @@ export class ProjectRepository {
     }
 
     setPageSize(pageSize: PageFormat) {
+        if (this.guardWrite("setPageSize")) return;
         this.ydoc.layout().set("pageSize", pageSize);
     }
     setPageMargins(margins: PageMargin) {
+        if (this.guardWrite("setPageMargins")) return;
         this.ydoc.layout().set("pageMargins", margins);
     }
     setDisplaySceneNumbers(display: boolean) {
+        if (this.guardWrite("setDisplaySceneNumbers")) return;
         this.ydoc.layout().set("displaySceneNumbers", display);
     }
     setSceneHeadingSpacing(spacing: number) {
+        if (this.guardWrite("setSceneHeadingSpacing")) return;
         this.ydoc.layout().set("sceneHeadingSpacing", spacing);
     }
     setSceneNumberOnRight(onRight: boolean) {
+        if (this.guardWrite("setSceneNumberOnRight")) return;
         this.ydoc.layout().set("sceneNumberOnRight", onRight);
     }
     setContdLabel(label: string) {
+        if (this.guardWrite("setContdLabel")) return;
         this.ydoc.layout().set("contdLabel", label);
     }
     setMoreLabel(label: string) {
+        if (this.guardWrite("setMoreLabel")) return;
         this.ydoc.layout().set("moreLabel", label);
     }
     setElementMargins(margins: Record<string, { left: number; right: number }>) {
+        if (this.guardWrite("setElementMargins")) return;
         this.ydoc.layout().set("elementMargins", margins);
     }
     setElementStyles(styles: Record<string, ElementStyle>) {
+        if (this.guardWrite("setElementStyles")) return;
         this.ydoc.layout().set("elementStyles", styles);
     }
 
@@ -350,12 +379,14 @@ export class ProjectRepository {
     }
 
     addCommentToMap(map: Y.Map<Comment>, comment: Omit<Comment, "id">): string {
+        if (this.guardWrite("addComment")) return "";
         const id = uuidv7();
         map.set(id, { ...comment, id });
         return id;
     }
 
     updateCommentInMap(map: Y.Map<Comment>, commentId: string, data: Partial<Comment>): void {
+        if (this.guardWrite("updateComment")) return;
         const existing = map.get(commentId);
         if (!existing) return;
         map.set(commentId, { ...existing, ...data });
@@ -366,6 +397,7 @@ export class ProjectRepository {
     }
 
     addReplyToMap(map: Y.Map<Comment>, commentId: string, reply: Omit<CommentReply, "id">): string | undefined {
+        if (this.guardWrite("addReply")) return undefined;
         const existing = map.get(commentId);
         if (!existing) return undefined;
         const id = uuidv7();
@@ -375,6 +407,7 @@ export class ProjectRepository {
     }
 
     deleteCommentFromMap(map: Y.Map<Comment>, commentId: string): void {
+        if (this.guardWrite("deleteComment")) return;
         if (map.has(commentId)) {
             map.delete(commentId);
         }
@@ -434,6 +467,7 @@ export class ProjectRepository {
 
     /** Create a new shelf entry or add a version to an existing one. Returns the version ID. */
     shelveNode(nodeId: string, title: string, type: ShelfEntryType, content: JSONContent[]): string {
+        if (this.guardWrite("shelveNode")) return "";
         const map = this.ydoc.shelf();
         const existing = map.get(nodeId) as ShelfEntry | undefined;
         const versionId = generateNodeId();
@@ -465,6 +499,7 @@ export class ProjectRepository {
     }
 
     renameShelfVersion(nodeId: string, versionId: string, newTitle: string): void {
+        if (this.guardWrite("renameShelfVersion")) return;
         const map = this.ydoc.shelf();
         const entry = map.get(nodeId) as ShelfEntry | undefined;
         if (!entry) return;
@@ -473,6 +508,7 @@ export class ProjectRepository {
     }
 
     deleteShelfEntry(nodeId: string): void {
+        if (this.guardWrite("deleteShelfEntry")) return;
         const map = this.ydoc.shelf();
         const entry = map.get(nodeId) as ShelfEntry | undefined;
         if (!entry) return;
@@ -487,6 +523,7 @@ export class ProjectRepository {
     }
 
     deleteShelfVersion(nodeId: string, versionId: string): void {
+        if (this.guardWrite("deleteShelfVersion")) return;
         const map = this.ydoc.shelf();
         const entry = map.get(nodeId) as ShelfEntry | undefined;
         if (!entry) return;
diff --git a/src/lib/project/project-state.ts b/src/lib/project/project-state.ts
index 9563db0b..9196005a 100644
--- a/src/lib/project/project-state.ts
+++ b/src/lib/project/project-state.ts
@@ -10,9 +10,6 @@ import type { ThrottledWebsocketProvider } from "../cloud/utils";
 import { ScreenplaySchema } from "../screenplay/editor";
 import { TitlePageSchema } from "../titlepage/editor";
 import { yXmlFragmentToProseMirrorRootNode } from "y-prosemirror";
-import type { CharacterMap } from "../screenplay/characters";
-import type { LocationMap } from "../screenplay/locations";
-import type { PersistentSceneMap } from "../screenplay/scenes";
 import type { YjsLocalProvider } from "../persistence/y-local-provider";
 import type { ProjectMigrationOutcome } from "./migrations/project-migration-runner";
 
@@ -25,10 +22,6 @@ export {
     DEFAULT_PAGE_MARGINS,
     DEFAULT_ELEMENT_MARGINS,
     DEFAULT_ELEMENT_STYLES,
-    getCharactersMap,
-    getLocationsMap,
-    getScenesMap,
-    getBoardMap,
 } from "./project-doc";
 export type {
     ShelfEntryType,
@@ -61,19 +54,31 @@ export const getProjectRepository = async () => {
 
 export type ConnectionStatus = "disconnected" | "connecting" | "connected";
 
+/**
+ * High-level state of a project from the layout's perspective. Replaces the
+ * previous bag of `isReady` / `isProjectUnavailable` / `isStaleClient` /
+ * `migrationOutcome` booleans — a single discriminated union makes the
+ * priority of error states explicit and lets the layout switch on one value.
+ *
+ * Priority (highest first): needs-update > unavailable > loading > ready.
+ */
+export type ProjectStatusOutcome = Extract<
+    ProjectMigrationOutcome,
+    { kind: "future-version" | "failed" | "stale-client" }
+>;
+
+export type ProjectStatus =
+    | { kind: "loading" }
+    | { kind: "ready" }
+    | { kind: "needs-update"; outcome: ProjectStatusOutcome }
+    | { kind: "unavailable" };
+
 export interface ProjectYjsState {
     ydoc: ProjectState | null;
     provider: ThrottledWebsocketProvider | null;
-    isLocalReady: boolean;
-    isCloudReady: boolean;
-    isCloudSynced: boolean;
+    status: ProjectStatus;
     connectionStatus: ConnectionStatus;
     users: CollaboratorInfo[];
-    isLockedByServer: boolean;
-    isSessionReplaced: boolean;
-    isProjectUnavailable: boolean;
-    isStaleClient: boolean;
-    migrationOutcome: ProjectMigrationOutcome | null;
 }
 
 export interface CollaboratorInfo {
@@ -103,28 +108,6 @@ async function getYProtocols() {
     return yProtocolsModule;
 }
 
-/**
- * Utility to clear the local IndexedDB cache for a specific project.
- * Used when the server restores a document from a snapshot to avoid merge conflicts.
- */
-export async function clearLocalProjectCache(projectId: string): Promise<void> {
-    try {
-        const { IndexeddbPersistence } = await import("y-indexeddb");
-        const tmpDoc = new Y.Doc();
-        const tmpPersistence = new IndexeddbPersistence(`scriptio-${projectId}`, tmpDoc);
-
-        // Check if clearData is available on the persistence instance
-        const provider = tmpPersistence as unknown as { clearData?: () => Promise<void> };
-        if (typeof provider.clearData === "function") {
-            await provider.clearData();
-        }
-
-        tmpPersistence.destroy();
-        tmpDoc.destroy();
-    } catch (e) {
-        console.warn(`[ProjectState] Failed to clear local cache for ${projectId}:`, e);
-    }
-}
 
 // -------------------------------- //
 //   PROSEMIRROR HELPERS (browser)  //
@@ -151,358 +134,293 @@ export const titlepageOf = (ydoc: ProjectState): JSONContent[] => {
 };
 
 // -------------------------------- //
-//          LOCAL PERSISTENCE       //
+//        SESSION CACHE             //
 // -------------------------------- //
 
 /**
- * Hook to initialize local persistence for the Yjs document.
+ * Per-projectId session cache holding the Yjs doc, the IndexedDB local
+ * provider, and the cloud WebSocket provider. RefCount + a deferred dispose
+ * timer let a synchronous unmount/remount pair (React StrictMode in dev,
+ * route remounts) reuse the same resources instead of tearing them down and
+ * rebuilding from scratch — which previously produced two disconnect/connect
+ * cycles per page refresh in dev.
  */
-export const useLocalPersistence = (projectId: string | null) => {
-    const [ydoc, setYdoc] = useState<ProjectState | null>(null);
-    const [isLocalReady, setIsLocalReady] = useState(false);
-    const [migrationOutcome, setMigrationOutcome] = useState<ProjectMigrationOutcome | null>(null);
-    const persistenceRef = useRef<YjsLocalProvider | null>(null);
-
-    useEffect(() => {
-        if (!projectId || typeof window === "undefined") {
-            setYdoc(null);
-            setIsLocalReady(false);
-            setMigrationOutcome(null);
-            return;
-        }
-
-        let isDestroyed = false;
-        const initPersistence = async () => {
-            const state = new ProjectState();
-            const { createLocalYjsProvider } = await import("../persistence/y-local-provider");
-            const localProvider = await createLocalYjsProvider(projectId, state);
-
-            localProvider.on("synced", async () => {
-                if (isDestroyed) return;
-                const { migrateProjectDoc } = await import("./migrations/project-migration-runner");
-                const outcome = await migrateProjectDoc({ ydoc: state, projectId });
-                if (isDestroyed) return;
-                setMigrationOutcome(outcome);
-                if (outcome.kind === "future-version" || outcome.kind === "failed") {
-                    // Block UI from rendering the project; layout shows error dialog instead.
-                    return;
-                }
-                setIsLocalReady(true);
-            });
-
-            persistenceRef.current = localProvider;
-
-            if (!isDestroyed) {
-                setYdoc(state);
-            }
-        };
-
-        initPersistence();
+type SessionEntry = {
+    projectId: string;
+    state: ProjectState;
+    localProvider: YjsLocalProvider | null;
+    cloudProvider: ThrottledWebsocketProvider | null;
+    isLocalReady: boolean;
+    isCloudSynced: boolean;
+    isCloudInitStarted: boolean;
+    migrationOutcome: ProjectMigrationOutcome | null;
+    connectionStatus: ConnectionStatus;
+    users: CollaboratorInfo[];
+    isProjectUnavailable: boolean;
+    isSessionReplaced: boolean;
+    isStaleClient: boolean;
+    currentUserInfo: UserInfo;
+    lastUsersJson: string;
+    refCount: number;
+    disposeTimer: ReturnType<typeof setTimeout> | null;
+    subscribers: Set<() => void>;
+};
 
-        return () => {
-            isDestroyed = true;
-            if (persistenceRef.current) {
-                persistenceRef.current.destroy();
-                persistenceRef.current = null;
-            }
-            setYdoc((prev) => {
-                prev?.destroy();
-                return null;
-            });
-            setIsLocalReady(false);
-            setMigrationOutcome(null);
-        };
-    }, [projectId]);
+const sessionCache = new Map<string, SessionEntry>();
 
-    return { ydoc, isLocalReady, migrationOutcome };
+const notifySubscribers = (entry: SessionEntry): void => {
+    entry.subscribers.forEach((cb) => cb());
 };
 
-// -------------------------------- //
-//          CLOUD SYNC              //
-// -------------------------------- //
-
 /**
- * Hook to manage cloud WebSocket synchronization.
+ * Has the cache evicted this entry while we were awaiting? Used to bail out
+ * of async init paths whose entry was disposed before they completed.
  */
-export const useCloudSync = (
-    projectId: string | null,
-    ydoc: ProjectState | null,
-    userInfo: UserInfo,
-) => {
-    const [provider, setProvider] = useState<ThrottledWebsocketProvider | null>(null);
-    const [users, setUsers] = useState<CollaboratorInfo[]>([]);
-    const [connectionStatus, setConnectionStatus] = useState<ConnectionStatus>("disconnected");
-    const [isCloudSynced, setIsCloudSynced] = useState(false);
-    const [isLockedByServer] = useState(false);
-    const [isSessionReplaced, setIsSessionReplaced] = useState(false);
-    const [isProjectUnavailable, setIsProjectUnavailable] = useState(false);
-    const [isStaleClient, setIsStaleClient] = useState(false);
-
-    const isMountedRef = useRef(true);
-    const providerRef = useRef<ThrottledWebsocketProvider | null>(null);
-    const lastUsersJsonRef = useRef<string>("");
-
-    // Use ref for userInfo to avoid triggering effects on every render
-    const userInfoRef = useRef(userInfo);
-    useEffect(() => {
-        userInfoRef.current = userInfo;
-    }, [userInfo]);
+const isLive = (entry: SessionEntry): boolean => sessionCache.get(entry.projectId) === entry;
 
-    // Ref for the refresh function so it can be called from event handlers
-    const refreshAndReconnectRef = useRef<() => Promise<void>>();
+const initLocalProvider = async (entry: SessionEntry): Promise<void> => {
+    const { createLocalYjsProvider } = await import("../persistence/y-local-provider");
+    if (!isLive(entry)) return;
 
-    // Refresh token and reconnect
-    const refreshAndReconnect = useCallback(async () => {
-        if (!providerRef.current || !projectId) return;
-
-        try {
-            const { token } = await getCloudToken(projectId);
-            if (token && isMountedRef.current) {
-                await providerRef.current.updateToken(token);
-            }
-        } catch (e) {
-            console.warn("[ProjectYjs] Failed to refresh token:", e);
+    const localProvider = await createLocalYjsProvider(entry.projectId, entry.state);
+    if (!isLive(entry)) {
+        localProvider.destroy();
+        return;
+    }
+    entry.localProvider = localProvider;
+
+    localProvider.on("synced", async () => {
+        const { migrateProjectDoc } = await import("./migrations/project-migration-runner");
+        const outcome = await migrateProjectDoc({ ydoc: entry.state, projectId: entry.projectId });
+        if (!isLive(entry)) return;
+        entry.migrationOutcome = outcome;
+        if (outcome.kind === "future-version" || outcome.kind === "failed") {
+            notifySubscribers(entry);
+            return;
         }
-    }, [projectId]);
+        entry.isLocalReady = true;
+        notifySubscribers(entry);
+        void initCloudProvider(entry);
+    });
+};
 
-    // Keep the ref up to date
-    useEffect(() => {
-        refreshAndReconnectRef.current = refreshAndReconnect;
-    }, [refreshAndReconnect]);
+const initCloudProvider = async (entry: SessionEntry): Promise<void> => {
+    if (entry.isCloudInitStarted) return;
+    entry.isCloudInitStarted = true;
+    entry.connectionStatus = "connecting";
+    notifySubscribers(entry);
 
-    // Initialize provider when doc is ready
-    useEffect(() => {
-        isMountedRef.current = true;
-        setIsProjectUnavailable(false);
-        setIsSessionReplaced(false);
-
-        if (!ydoc || !projectId || typeof window === "undefined") {
-            setConnectionStatus("disconnected");
+    try {
+        const { isTauri } = await import("@tauri-apps/api/core");
+        const isDesktop = isTauri();
+
+        const { isLocalOnlyProject } = await import(
+            "../persistence/storage-provider/local-persistence"
+        );
+        if (await isLocalOnlyProject(entry.projectId)) {
+            if (!isLive(entry)) return;
+            entry.connectionStatus = "disconnected";
+            entry.isCloudSynced = true;
+            notifySubscribers(entry);
             return;
         }
 
-        // If provider already exists for this doc, don't recreate
-        if (providerRef.current) {
+        const { token, status } = await getCloudToken(entry.projectId);
+        if (!isLive(entry)) return;
+        if (!token) {
+            entry.connectionStatus = "disconnected";
+            entry.isCloudSynced = true;
+            // 403 means the cloud project was deleted or the user was removed.
+            // Surface the recovery dialog on both desktop and web — the local
+            // cache is still valid and the user should choose what to do with it.
+            if (status === 403) entry.isProjectUnavailable = true;
+            notifySubscribers(entry);
             return;
         }
 
-        const setupProvider = async () => {
-            setConnectionStatus("connecting");
-
+        const { ThrottledWebsocketProvider } = await import("../cloud/utils");
+        if (!isLive(entry)) return;
+
+        const cloudWsUrl = (process.env.NEXT_PUBLIC_CLOUD_URL || "").replace(/^http/, "ws");
+        const cloudProvider = new ThrottledWebsocketProvider(
+            cloudWsUrl,
+            entry.projectId,
+            entry.state,
+            {
+                params: { token, clientId: entry.state.clientID.toString() },
+                userInfo: entry.currentUserInfo,
+                disableBc: isDesktop,
+            },
+        );
+        entry.cloudProvider = cloudProvider;
+        notifySubscribers(entry);
+
+        cloudProvider.awareness.on("update", () => {
+            const states = Array.from(cloudProvider.awareness.getStates().values());
+            const uniqueUsers = new Map<string, CollaboratorInfo>();
+            for (const s of states) {
+                if (s.user) {
+                    const user = s.user as CollaboratorInfo;
+                    const key = user.userId || user.name;
+                    if (!uniqueUsers.has(key)) uniqueUsers.set(key, user);
+                }
+            }
+            const next = Array.from(uniqueUsers.values());
+            const nextJson = JSON.stringify(next);
+            if (nextJson !== entry.lastUsersJson) {
+                entry.lastUsersJson = nextJson;
+                entry.users = next;
+                notifySubscribers(entry);
+            }
+        });
+
+        cloudProvider.on("connection-error", async () => {
+            // Skip terminal states — refreshing after a kick would just hit
+            // cloud-token, get 403, and loop forever.
+            if (cloudProvider.wasSessionReplaced || cloudProvider.wasKicked) return;
+            console.warn("[ProjectYjs] Connection error, attempting to refresh token...");
+            entry.connectionStatus = "connecting";
+            notifySubscribers(entry);
             try {
-                // Check if we're in Tauri environment first
-                const { isTauri } = await import("@tauri-apps/api/core");
-                const isDesktop = isTauri();
-
-                // Local-only projects (not cloud-synced) don't need cloud sync
-                const { isLocalOnlyProject } =
-                    await import("../persistence/storage-provider/local-persistence");
-                if (await isLocalOnlyProject(projectId)) {
-                    setConnectionStatus("disconnected");
-                    setIsCloudSynced(true);
+                const { token: refreshed, status: refreshStatus } = await getCloudToken(
+                    entry.projectId,
+                );
+                if (!isLive(entry)) return;
+                if (refreshStatus === 403) {
+                    cloudProvider.shouldConnect = false;
+                    cloudProvider.disconnect();
+                    entry.isProjectUnavailable = true;
+                    entry.connectionStatus = "disconnected";
+                    notifySubscribers(entry);
                     return;
                 }
-
-                const { token, status } = await getCloudToken(projectId);
-                if (!token || !isMountedRef.current) {
-                    setConnectionStatus("disconnected");
-                    setIsCloudSynced(true); // Mark as "synced" so isReady becomes true
-
-                    // 403 means the cloud project was deleted or the user was removed.
-                    // Surface the recovery dialog on both desktop and web — the local
-                    // cache is still valid and the user should choose what to do with it.
-                    if (status === 403) {
-                        setIsProjectUnavailable(true);
-                    }
-                    return;
+                if (refreshed) await cloudProvider.updateToken(refreshed);
+            } catch (e) {
+                console.warn("[ProjectYjs] Failed to refresh token:", e);
+            }
+        });
+
+        cloudProvider.on("status", (e: { status: string }) => {
+            entry.connectionStatus = e.status as ConnectionStatus;
+            if (e.status === "connected" && cloudProvider.synced) entry.isCloudSynced = true;
+            notifySubscribers(entry);
+        });
+
+        cloudProvider.on("sync", (isSynced: boolean) => {
+            if (isSynced) {
+                entry.isCloudSynced = true;
+                notifySubscribers(entry);
+            }
+        });
+
+        cloudProvider.on("session-replaced", () => {
+            entry.isSessionReplaced = true;
+            entry.connectionStatus = "disconnected";
+            notifySubscribers(entry);
+        });
+
+        cloudProvider.on("kicked", () => {
+            entry.isProjectUnavailable = true;
+            entry.connectionStatus = "disconnected";
+            notifySubscribers(entry);
+        });
+
+        cloudProvider.on("document-restored", async () => {
+            console.log("[ProjectYjs] Document restored — clearing local cache and reloading");
+            try {
+                if (entry.localProvider?.clearData) {
+                    await entry.localProvider.clearData();
+                } else {
+                    const { clearYjsData } = await import(
+                        "../persistence/storage-provider/local-persistence"
+                    );
+                    await clearYjsData(entry.projectId);
                 }
+            } catch (e) {
+                console.warn("[ProjectYjs] Failed to clear local cache:", e);
+            }
+            window.location.reload();
+        });
+
+        cloudProvider.on("stale-client-version", () => {
+            console.warn("[ProjectYjs] Server rejected this client as stale");
+            entry.isStaleClient = true;
+            notifySubscribers(entry);
+        });
+    } catch (e) {
+        console.error("[ProjectYjs] Failed to initialize provider:", e);
+        if (!isLive(entry)) return;
+        entry.connectionStatus = "disconnected";
+        entry.isCloudSynced = true;
+        notifySubscribers(entry);
+    }
+};
 
-                // Dynamically import collaboration utils
-                const { ThrottledWebsocketProvider } = await import("../cloud/utils");
-
-                const cloudWsUrl = (process.env.NEXT_PUBLIC_CLOUD_URL || "").replace(/^http/, "ws");
-                const cloudProvider = new ThrottledWebsocketProvider(
-                    cloudWsUrl,
-                    projectId,
-                    ydoc,
-                    {
-                        params: {
-                            token,
-                            clientId: ydoc.clientID.toString(),
-                        },
-                        userInfo: userInfoRef.current,
-                        disableBc: isDesktop,
-                    },
-                );
+const acquireSession = (projectId: string, userInfo: UserInfo): SessionEntry => {
+    const existing = sessionCache.get(projectId);
+    if (existing) {
+        existing.refCount++;
+        existing.currentUserInfo = userInfo;
+        existing.cloudProvider?.setUserInfo(userInfo);
+        if (existing.disposeTimer) {
+            clearTimeout(existing.disposeTimer);
+            existing.disposeTimer = null;
+        }
+        return existing;
+    }
 
-                // Track connected users - only update state if users actually changed
-                cloudProvider.awareness.on("update", () => {
-                    if (!isMountedRef.current) return;
-
-                    const states = Array.from(cloudProvider.awareness.getStates().values());
-                    const uniqueUsersMap = new Map<string, CollaboratorInfo>();
-
-                    for (const state of states) {
-                        if (state.user) {
-                            const user = state.user as CollaboratorInfo;
-                            const key = user.userId || user.name;
-                            if (!uniqueUsersMap.has(key)) {
-                                uniqueUsersMap.set(key, user);
-                            }
-                        }
-                    }
-
-                    const connectedUsers = Array.from(uniqueUsersMap.values());
-                    const usersJson = JSON.stringify(connectedUsers);
-                    if (usersJson !== lastUsersJsonRef.current) {
-                        lastUsersJsonRef.current = usersJson;
-                        setUsers(connectedUsers);
-                    }
-                });
-
-                // Handle connection errors
-                cloudProvider.on("connection-error", async () => {
-                    if (cloudProvider.wasSessionReplaced) return;
-                    console.warn("[ProjectYjs] Connection error, attempting to refresh token...");
-                    if (isMountedRef.current) {
-                        setConnectionStatus("connecting");
-                        if (refreshAndReconnectRef.current) {
-                            await refreshAndReconnectRef.current();
-                        } else {
-                            cloudProvider.scheduleReconnect();
-                        }
-                    }
-                });
-
-                // Status updates
-                cloudProvider.on("status", (e: { status: string }) => {
-                    if (!isMountedRef.current) return;
-                    setConnectionStatus(e.status as ConnectionStatus);
-                    if (e.status === "connected" && cloudProvider.synced) {
-                        setIsCloudSynced(true);
-                    }
-                });
-
-                // Track when initial cloud sync completes
-                cloudProvider.on("sync", (isSynced: boolean) => {
-                    if (isMountedRef.current && isSynced) {
-                        setIsCloudSynced(true);
-                    }
-                });
-
-                // Surface session-replaced state to the UI so the connection
-                // indicator and recovery dialogs reflect the terminal state
-                // (the provider stops reconnecting after this fires).
-                cloudProvider.on("session-replaced", () => {
-                    if (!isMountedRef.current) return;
-                    setIsSessionReplaced(true);
-                    setConnectionStatus("disconnected");
-                });
-
-                // Handle document restore
-                cloudProvider.on("document-restored", async () => {
-                    if (!isMountedRef.current) return;
-                    console.log(
-                        "[ProjectYjs] Document restored — clearing local cache and reloading",
-                    );
-                    await clearLocalProjectCache(projectId);
-                    window.location.reload();
-                });
-
-                // Server rejected this client as stale — its bundle predates
-                // the doc's schema version. Surface to the UI so the user is
-                // prompted to update.
-                cloudProvider.on("stale-client-version", () => {
-                    if (!isMountedRef.current) return;
-                    console.warn("[ProjectYjs] Server rejected this client as stale");
-                    setIsStaleClient(true);
-                });
-
-                // Poll for synced status
-                const checkSynced = () => {
-                    if (!isMountedRef.current) return;
-                    if (cloudProvider.synced) {
-                        setIsCloudSynced(true);
-                    } else {
-                        setTimeout(checkSynced, 100);
-                    }
-                };
-                setTimeout(checkSynced, 50);
+    const entry: SessionEntry = {
+        projectId,
+        state: new ProjectState(),
+        localProvider: null,
+        cloudProvider: null,
+        isLocalReady: false,
+        isCloudSynced: false,
+        isCloudInitStarted: false,
+        migrationOutcome: null,
+        connectionStatus: "disconnected",
+        users: [],
+        isProjectUnavailable: false,
+        isSessionReplaced: false,
+        isStaleClient: false,
+        currentUserInfo: userInfo,
+        lastUsersJson: "",
+        refCount: 1,
+        disposeTimer: null,
+        subscribers: new Set(),
+    };
+    sessionCache.set(projectId, entry);
+    void initLocalProvider(entry);
+    return entry;
+};
 
-                providerRef.current = cloudProvider;
-                setProvider(cloudProvider);
-            } catch (e) {
-                console.error("[ProjectYjs] Failed to initialize provider:", e);
-                if (isMountedRef.current) {
-                    setConnectionStatus("disconnected");
-                    setIsCloudSynced(true);
-                }
-            }
-        };
+const releaseSession = (projectId: string): void => {
+    const entry = sessionCache.get(projectId);
+    if (!entry) return;
+    entry.refCount--;
+    if (entry.refCount > 0) return;
 
-        setupProvider();
+    // Defer disposal so a synchronous remount (StrictMode) can cancel it via
+    // clearTimeout in acquireSession before the resources are torn down.
+    entry.disposeTimer = setTimeout(async () => {
+        entry.disposeTimer = null;
+        if (entry.refCount > 0) return;
 
-        const handleUnload = async () => {
-            if (providerRef.current && ydoc) {
+        if (entry.cloudProvider) {
+            try {
                 const { removeAwarenessStates } = await getYProtocols();
                 removeAwarenessStates(
-                    providerRef.current.awareness,
-                    [ydoc.clientID],
-                    "window unload",
+                    entry.cloudProvider.awareness,
+                    [entry.state.clientID],
+                    "session release",
                 );
-            }
-        };
-
-        window.addEventListener("beforeunload", handleUnload);
-
-        return () => {
-            isMountedRef.current = false;
-            window.removeEventListener("beforeunload", handleUnload);
-        };
-    }, [ydoc, projectId]);
-
-    useEffect(() => {
-        if (providerRef.current) {
-            providerRef.current.setUserInfo(userInfo);
+            } catch {}
+            entry.cloudProvider.destroy();
         }
-    }, [userInfo]);
-
-    useEffect(() => {
-        return () => {
-            if (providerRef.current) {
-                if (ydoc) {
-                    getYProtocols().then(({ removeAwarenessStates }) => {
-                        if (providerRef.current) {
-                            removeAwarenessStates(
-                                providerRef.current.awareness,
-                                [ydoc.clientID],
-                                "component unmount",
-                            );
-                            providerRef.current.destroy();
-                            providerRef.current = null;
-                            setProvider(null);
-                        }
-                    });
-                } else {
-                    providerRef.current.destroy();
-                    providerRef.current = null;
-                    setProvider(null);
-                }
-            }
-        };
-    }, [ydoc]);
-
-    return {
-        provider,
-        users,
-        connectionStatus,
-        isCloudSynced,
-        refreshAndReconnect,
-        isLockedByServer,
-        isSessionReplaced,
-        isProjectUnavailable,
-        isStaleClient,
-    };
+        entry.localProvider?.destroy();
+        entry.state.destroy();
+        sessionCache.delete(projectId);
+    }, 0);
 };
 
 // -------------------------------- //
@@ -516,13 +434,28 @@ export interface UseProjectYjsOptions {
     userId?: string;
 }
 
+const computeStatus = (entry: SessionEntry | null): ProjectStatus => {
+    if (!entry) return { kind: "loading" };
+    if (entry.isStaleClient) {
+        return { kind: "needs-update", outcome: { kind: "stale-client" } };
+    }
+    if (
+        entry.migrationOutcome?.kind === "future-version" ||
+        entry.migrationOutcome?.kind === "failed"
+    ) {
+        return { kind: "needs-update", outcome: entry.migrationOutcome };
+    }
+    if (entry.isProjectUnavailable) return { kind: "unavailable" };
+    if (!entry.isLocalReady) return { kind: "loading" };
+    return { kind: "ready" };
+};
+
 export const useProjectYjs = ({
     projectId,
     userName,
     userColor,
     userId,
 }: UseProjectYjsOptions): ProjectYjsState & {
-    isReady: boolean;
     refreshAndReconnect: () => Promise<void>;
 } => {
     const [fallback] = useState(() => ({
@@ -538,39 +471,80 @@ export const useProjectYjs = ({
         [userName, userColor, userId, fallback.name, fallback.color],
     );
 
-    const { ydoc, isLocalReady, migrationOutcome } = useLocalPersistence(projectId);
-    const {
-        provider,
-        users,
-        connectionStatus,
-        isCloudSynced,
-        refreshAndReconnect,
-        isLockedByServer,
-        isSessionReplaced,
-        isProjectUnavailable,
-        isStaleClient,
-    } = useCloudSync(projectId, isLocalReady ? ydoc : null, userInfo);
+    const entryRef = useRef<SessionEntry | null>(null);
+    const [, setVersion] = useState(0);
+
+    useEffect(() => {
+        if (!projectId || typeof window === "undefined") {
+            entryRef.current = null;
+            setVersion((v) => v + 1);
+            return;
+        }
+
+        const entry = acquireSession(projectId, userInfo);
+        entryRef.current = entry;
+        const onChange = () => setVersion((v) => v + 1);
+        entry.subscribers.add(onChange);
+        setVersion((v) => v + 1);
+
+        const handleUnload = async () => {
+            if (entry.cloudProvider) {
+                const { removeAwarenessStates } = await getYProtocols();
+                removeAwarenessStates(
+                    entry.cloudProvider.awareness,
+                    [entry.state.clientID],
+                    "window unload",
+                );
+            }
+        };
+        window.addEventListener("beforeunload", handleUnload);
+
+        return () => {
+            window.removeEventListener("beforeunload", handleUnload);
+            entry.subscribers.delete(onChange);
+            entryRef.current = null;
+            releaseSession(projectId);
+        };
+        // userInfo is intentionally NOT in the deps: re-acquiring on every
+        // userInfo change would defeat the cache. Updates flow via the
+        // separate effect below, which calls setUserInfo on the live provider.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [projectId]);
 
-    // isReady: project is ready when ydoc exists and local storage is synced
-    // Cloud sync happens in the background and will merge data when it arrives
-    const isCloudReady = connectionStatus === "connected";
-    const isReady = ydoc !== null && isLocalReady;
+    useEffect(() => {
+        const entry = entryRef.current;
+        if (!entry) return;
+        entry.currentUserInfo = userInfo;
+        entry.cloudProvider?.setUserInfo(userInfo);
+    }, [userInfo]);
+
+    const refreshAndReconnect = useCallback(async () => {
+        const entry = entryRef.current;
+        if (!entry?.cloudProvider || !projectId) return;
+        try {
+            const { token, status } = await getCloudToken(projectId);
+            if (status === 403) {
+                entry.cloudProvider.shouldConnect = false;
+                entry.cloudProvider.disconnect();
+                entry.isProjectUnavailable = true;
+                entry.connectionStatus = "disconnected";
+                notifySubscribers(entry);
+                return;
+            }
+            if (token) await entry.cloudProvider.updateToken(token);
+        } catch (e) {
+            console.warn("[ProjectYjs] Failed to refresh token:", e);
+        }
+    }, [projectId]);
 
+    const entry = entryRef.current;
     return {
-        ydoc,
-        provider,
-        isLocalReady,
-        isCloudReady,
-        isCloudSynced,
-        isReady,
-        connectionStatus,
-        users,
+        ydoc: entry?.state ?? null,
+        provider: entry?.cloudProvider ?? null,
+        status: computeStatus(entry),
+        connectionStatus: entry?.connectionStatus ?? "disconnected",
+        users: entry?.users ?? [],
         refreshAndReconnect,
-        isLockedByServer,
-        isSessionReplaced,
-        isProjectUnavailable,
-        isStaleClient,
-        migrationOutcome,
     };
 };
 
diff --git a/src/lib/screenplay/characters.ts b/src/lib/screenplay/characters.ts
index 38dbb98f..b9d59995 100644
--- a/src/lib/screenplay/characters.ts
+++ b/src/lib/screenplay/characters.ts
@@ -11,7 +11,6 @@ import { ProjectContextType } from "@src/context/ProjectContext";
 import { getNodeFlattenContent } from "./screenplay";
 import { ScreenplayElement } from "../utils/enums";
 import { Screenplay } from "../utils/types";
-import { getCharactersMap } from "@src/lib/project/project-state";
 
 // -------------------------------- //
 //          TYPE DEFINITIONS        //
@@ -46,13 +45,14 @@ export type CharacterItem = {
  * This will automatically sync to all connected collaborators.
  */
 export const upsertCharacterData = (data: CharacterData, projectCtx: ProjectContextType) => {
-    const ydoc = projectCtx.repository?.getState();
-    if (!ydoc) {
+    if (projectCtx.isReadOnly) return;
+    const projectState = projectCtx.repository?.getState();
+    if (!projectState) {
         console.warn("[Characters] Cannot upsert: Yjs document not available");
         return;
     }
 
-    const charactersMap = getCharactersMap(ydoc);
+    const charactersMap = projectState.characters();
     const characterItem: CharacterItem = {
         persistent: true, // Explicitly created/edited characters are always persistent
         gender: data.gender,
@@ -71,13 +71,14 @@ export const upsertCharacterData = (data: CharacterData, projectCtx: ProjectCont
  * Delete a character from the Yjs document.
  */
 export const deleteCharacter = (name: string, projectCtx: ProjectContextType) => {
-    const ydoc = projectCtx.repository?.getState();
-    if (!ydoc) {
+    if (projectCtx.isReadOnly) return;
+    const projectState = projectCtx.repository?.getState();
+    if (!projectState) {
         console.warn("[Characters] Cannot delete: Yjs document not available");
         return;
     }
 
-    const charactersMap = getCharactersMap(ydoc);
+    const charactersMap = projectState.characters();
     if (charactersMap.has(name)) {
         charactersMap.delete(name);
         console.log(`[Characters] Deleted character: ${name}`);
@@ -89,14 +90,19 @@ export const deleteCharacter = (name: string, projectCtx: ProjectContextType) =>
  * If the character exists in the persistent map, it will be renamed.
  * If not, this is a no-op (the character will be created by upsertCharacterData).
  */
-export const renameCharacter = (oldName: string, newName: string, projectCtx: ProjectContextType) => {
-    const ydoc = projectCtx.repository?.getState();
-    if (!ydoc) {
+export const renameCharacter = (
+    oldName: string,
+    newName: string,
+    projectCtx: ProjectContextType,
+) => {
+    if (projectCtx.isReadOnly) return;
+    const projectState = projectCtx.repository?.getState();
+    if (!projectState) {
         console.warn("[Characters] Cannot rename: Yjs document not available");
         return;
     }
 
-    const charactersMap = getCharactersMap(ydoc);
+    const charactersMap = projectState.characters();
 
     // Find the character with case-insensitive matching
     const oldNameUpper = oldName.toUpperCase();
@@ -112,7 +118,7 @@ export const renameCharacter = (oldName: string, newName: string, projectCtx: Pr
 
     if (existingKey && character) {
         const characterToRename = character;
-        ydoc.transact(() => {
+        projectState.transact(() => {
             charactersMap.delete(existingKey!);
             charactersMap.set(newName.toUpperCase(), characterToRename);
         });
@@ -132,7 +138,10 @@ export const doesCharacterExist = (name: string, projectCtx: ProjectContextType)
 /**
  * Get a character by name (case-insensitive).
  */
-export const getCharacter = (name: string, projectCtx: ProjectContextType): CharacterItem | undefined => {
+export const getCharacter = (
+    name: string,
+    projectCtx: ProjectContextType,
+): CharacterItem | undefined => {
     if (!projectCtx.characters) return undefined;
     const nameUppered = name.toUpperCase();
     const key = Object.keys(projectCtx.characters).find((k) => k.toUpperCase() === nameUppered);
@@ -175,7 +184,10 @@ export const getCharacterNames = (screenplay: Screenplay): string[] => {
 /**
  * Count how many times a character appears in the screenplay.
  */
-export const countCharacterAppearances = (screenplay: Screenplay, characterName: string): number => {
+export const countCharacterAppearances = (
+    screenplay: Screenplay,
+    characterName: string,
+): number => {
     if (!screenplay) return 0;
 
     const upperName = characterName.toUpperCase();
@@ -216,7 +228,10 @@ export const createDefaultCharacterItem = (): CharacterItem => ({
  * - Persistent characters (from Yjs) take precedence
  * - Auto-detected characters (from screenplay) fill in the rest with default values
  */
-export const mergeCharactersData = (persistentCharacters: CharacterMap, screenplay: Screenplay): CharacterMap => {
+export const mergeCharactersData = (
+    persistentCharacters: CharacterMap,
+    screenplay: Screenplay,
+): CharacterMap => {
     const result: CharacterMap = { ...persistentCharacters };
     const namesFromScreenplay = getCharacterNames(screenplay);
 
diff --git a/src/lib/screenplay/locations.ts b/src/lib/screenplay/locations.ts
index 45500f55..23ab6f82 100644
--- a/src/lib/screenplay/locations.ts
+++ b/src/lib/screenplay/locations.ts
@@ -11,7 +11,6 @@ import { ProjectContextType } from "@src/context/ProjectContext";
 import { getNodeFlattenContent } from "./screenplay";
 import { ScreenplayElement } from "../utils/enums";
 import { Screenplay } from "../utils/types";
-import { getLocationsMap } from "@src/lib/project/project-state";
 
 // -------------------------------- //
 //          TYPE DEFINITIONS        //
@@ -38,13 +37,14 @@ export type LocationItem = {
  * This will automatically sync to all connected collaborators.
  */
 export const upsertLocationData = (data: LocationData, projectCtx: ProjectContextType) => {
+    if (projectCtx.isReadOnly) return;
     const ydoc = projectCtx.repository?.getState();
     if (!ydoc) {
         console.warn("[Locations] Cannot upsert: Yjs document not available");
         return;
     }
 
-    const locationsMap = getLocationsMap(ydoc);
+    const locationsMap = ydoc.locations();
     const locationItem: LocationItem = {
         persistent: true,
         description: data.description,
@@ -61,13 +61,14 @@ export const upsertLocationData = (data: LocationData, projectCtx: ProjectContex
  * Delete a location from the Yjs document.
  */
 export const deleteLocation = (name: string, projectCtx: ProjectContextType) => {
+    if (projectCtx.isReadOnly) return;
     const ydoc = projectCtx.repository?.getState();
     if (!ydoc) {
         console.warn("[Locations] Cannot delete: Yjs document not available");
         return;
     }
 
-    const locationsMap = getLocationsMap(ydoc);
+    const locationsMap = ydoc.locations();
     if (locationsMap.has(name)) {
         locationsMap.delete(name);
         console.log(`[Locations] Deleted location: ${name}`);
@@ -78,13 +79,14 @@ export const deleteLocation = (name: string, projectCtx: ProjectContextType) =>
  * Rename a location in the Yjs document.
  */
 export const renameLocation = (oldName: string, newName: string, projectCtx: ProjectContextType) => {
+    if (projectCtx.isReadOnly) return;
     const ydoc = projectCtx.repository?.getState();
     if (!ydoc) {
         console.warn("[Locations] Cannot rename: Yjs document not available");
         return;
     }
 
-    const locationsMap = getLocationsMap(ydoc);
+    const locationsMap = ydoc.locations();
     const location = locationsMap.get(oldName);
 
     if (location) {
@@ -233,7 +235,7 @@ export const isLocationPersistent = (name: string, projectCtx: ProjectContextTyp
     const ydoc = projectCtx.repository?.getState();
     if (!ydoc) return false;
 
-    const locationsMap = getLocationsMap(ydoc);
+    const locationsMap = ydoc.locations();
     const upperName = name.toUpperCase();
 
     let found = false;
@@ -252,10 +254,11 @@ export const isLocationPersistent = (name: string, projectCtx: ProjectContextTyp
  * If not, creates a new persistent location entry.
  */
 export const makeLocationPersistent = (name: string, projectCtx: ProjectContextType, data?: Partial<LocationItem>) => {
+    if (projectCtx.isReadOnly) return;
     const ydoc = projectCtx.repository?.getState();
     if (!ydoc) return;
 
-    const locationsMap = getLocationsMap(ydoc);
+    const locationsMap = ydoc.locations();
 
     // Get existing data from merged locations (could be auto-detected)
     const existingData = projectCtx.locations?.[name] || createDefaultLocationItem();